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.
See also: API Reference Documentation
Document Assembly Workflow
The typical workflow using HotDocs for document assembly is to create a template in HotDocs Author (or Developer), upload it to HotDocs Advance, and assign it to a work group. Then, create a work item and gather data through an interview or programmatically. HotDocs Advance assembles the document for you.
Glossary of Advance Concepts
This table provides a broad outline of the concepts you may encounter when using the API.
See also: API Reference Documentation
| 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. | HotDocs Answer Sets Overview |
| 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 completed document(s) 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. HotDocs can assemble multiple documents in one assembly session. | |
| HotDocs Author | The desktop application used to create templates in Microsoft Word. This involves defining the variables and logic that will be used to generate the document. HotDocs Advance can also assemble templates created in HotDocs Developer. | |
| Interview | A series of questions used to gather answer 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 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 documents. | Quick Documents Overview |
| Quick group | A quick group is a shared folder that provides user access to transactional quick documents. | Quick Documents Overview |
| Service principal | A user account required 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 |
| 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 through the API |
| 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. | User Groups Overview |
| 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 | 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 |
| 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. | |
| Variable Data | An unknown value; you can define how to gather that value from a template user, how HotDocs stores that value as an answer, and the format HotDocs gives that answer when assembling a document. | |
| 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. | |
| Webhook | A webhook connects to an external application to provide real-time information. It automatically triggers an action when a specific event occurs, allowing the target application to receive and process data in real-time. | Webhooks Overview |
| 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. When using API 2.0 it is possible to add multiple templates to a work item. |
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 Auth (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/ |
| Auth | 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://tenancyA.yourorganization.com/HdaClientInterviews/ |