Advance Concepts for API Users

This topic provides an overview of concepts used in HotDocs Advance that you may need to know when using the API. This includes the structure of Advance and the types of resources you can access.

In this Topic Hide

  1. Advance Concepts
  2. Advance Applications

Advance Concepts

This table provides a broad outline of the concepts you may encounter when using the API.

Name Description See also
Administrative roles Additional permissions that can be allocated to a user, giving them permission to perform specific actions in Advance. A site administrator is an example of an administrative role. Administrative Roles Overview
Answer set A collection of the data submitted from an interview, input by a user.  
Answer XML The XML that comprises an answer set. When creating a work item using the API, you can optionally supply an answer XML string in the request.  
Assembly The process whereby HotDocs generates a completed document from a template package and an answer set. Assembly occurs when a user finishes an interview, usually as part of creating a work item or a quick document.  
Assembly Session A specific instance of the document assembly process. Using Assembly sessions, you can manage the creation of new versions of a work item. Assembly Sessions
Client (API Client) The client is an entity within Advance representing your application that needs to access the Advance API. When you use the client to make requests to the API, Advance uses the client to authenticate your request and determine if the requested action is authorized. API Clients
Client (Client Interview)

A client is an external user who receives a client interview email or link. You must create a client before you can send a client interview. Once a work item has a client attached, client interviews can only be sent to that client.

Client Interview

Client Interview

An interview sent to gather data from external end users. Users will generally create an interview by logging into the Advance UI application, creating a work item and then sending a link to the interview to an external client. The link is active, once clicked, for 96 hours. Client interviews can be resent and revoked. Client interviews are an additional subscription feature of Advance and must be activated in your tenancy.

Client Interview Overview

Core Assembly Service The HotDocs Core Assembly Service is a background process that runs when you launch an interview on HotDocs Advance. The service itself is responsible for delivering the interview and for creating assembled documents. It is installed separately for HotDocs Advance On-Premise configurations.  
Document The completed, customized document that is the result of the assembly process.  
Interview A series of questions used to gather data from end users. Users will generally access an interview by logging into the Advance UI application and either creating a work item or creating a quick document. The interview is generated by Advance based on the logic in the template. Interview Overview
Quick group A quick group is a shared folder that provides user access to transactional quick documents. Quick Documents Overview
Quick document A transactional document, created by a user through a Quick Group. It is similar to a work item, except no data is stored by Advance after the user finishes the interview and downloads their assembled document. Quick Documents Overview
Service principal A user account that when making requests using the Resource Owner authorization flow. Authorization Flows
Site administrator An administrative role that can be allocated to a user. Site administrators can administer users, users groups, templates and work groups. Administrative Roles Overview
User A user account within Advance. Users may have additional administrative roles, which provide them with authorization to perform specific actions in Advance. User Management Overview
Template A reusable HotDocs application containing boiler plate text and HotDocs logic, built in HotDocs Author. HotDocs uses the template, along with user-supplied answer data, to assemble a document. When uploaded to Advance from Author, the template is stored in Advance as part of a template package. Template Management Overview
Template package The zipped package of files sent to Advance when a template is uploaded from HotDocs Author. The template package contains the template files and associated metadata files.  
Tenancy An individual 'site' within your Advance deployment. Tenancies are separate from one another: they have their own databases, configuration settings, allocated users, templates, work groups, and so on. Data cannot be shared between tenancies. When using the API, you will make requests to a specific tenancy, identified by its unique tenancy moniker. Tenancies Overview
Tenancy moniker The unique identifying name for a tenancy, defined when a tenancy is created. This name is used in the URL for your tenancy. For example, in the URL https://tenancyA.yourorganization.com/HdAUi, tenancyA is the tenancy moniker. API Clients
User group A collection of user accounts, used to control access to work groups. Users can only access a work group if they are included in a user group that is allocated to that work group. User Groups Overview
Version A version is a snapshot of a particular set of assembled documents in a work item. When a user completes an assembly session, Advance creates a new version of the work item, with a new set of assembled documents.  
Viewer A role allocated to 'standard' (i.e. non-administrator) users. Viewers can see their own work items and the work groups/quick groups to which they are assigned.  
Work group A named location in which users can create work items. Users can only create work items in a work group if they are given access through a user group. By default, work items are accessible to any user that has access to the work group. You can make work items private, so that only the user that created the work item can access it or share with specific users in a work group. Work Groups Overview
Work item A named entity in HotDocs Advance with which you can enter and edit answer data, and assemble documents from that data, for a specific template. Users create work items through their allocated work groups. Work Items Overview

Advance Applications

Advance comprises the applications in the table below. When using the API, you will typically only need to interact with the API (to which you make API requests) and the Client management (through which you manage the clients used to authenticate requests to the API) applications.

Name Description Example URL
API The application that provides the Advance REST API.

https://tenancyA.yourorganization.com/HdaApi/

 
Client Management The application through which you manage API clients, used to authenticate requests to the API. You also manage service principal users (used by Resource Owner clients) through this application.

https://tenancyA.yourorganization.com/HdaAuth/

 
 
Root The application through which root administrators manage tenancies and tenancy administrators. https://hdroot.yourorganization.com/
 
UI The application used by end users. It provides an interface for creating work items, assembling documents, and managing access to templates.

https://tenancyA.yourorganization.com/HdaUi/

 

HdaClientInterviews

The web application which hosts client interviews.

https://yourtenancy.yourorganization.com/HdaClientInterviews