Assembling Documents Overview

When using HotDocs Advance, the typical goal of end users is to produce a completed, customized document. You use Assembly sessions to manage the process of gathering user data and producing assembled documents for a work item.

Overview

There are two main work-flows for using assembly sessions:

Displaying an interview

Generally, you will use this workflow when:

  • You do not already have a full set of answer data with which to assemble documents, and
  • You need to gather answer data from your end-users, through a HotDocs interview

If you already have a full set of answer data and want to assemble documents immediately, see the Create and assemble a new work item workflow instead.

Steps

The steps below outline how you should use the API to create a work item, display an interview, assemble, and download documents.

Step Name Description REST API Method
1 Create a work item Creates a new work item in Advance. Once a work item is created, you can create an assembly session for that work item. PUT /WorkItems/{id}
2

Begin the assembly session

 Creates a new assembly session for a specific work item. This request provides you with the data required to display an interview in the browser and interact with the assembly session. PUT /WorkItems/{id}/Versions/{versionId}
3

Display the interview

 The interview is displayed to your end user, in your own web application. This requires you to pass the following data to a page in your application:
  • response data from the begin assembly session request
  • The access token to a page in your application

This data is needed by the HotDocs Core Services JavaScript API to display the interview.

 N/A
4 User clicks Finish button in interview When the user decides they have entered all the necessary information into the interview, they click the Finish button. This posts the answer data from the interview to the endpoint you specified when configuring the interview. N/A
5 Complete the assembly session Call the Complete endpoint to assemble the completed documents and finish the assembly session. Advance creates a new work item version. PUT /WorkItems/{id}/Versions/active/CompleteSession
6 Download the documents Optional: you can download the documents produced by the completed assembly session. This requires two API requests:
  1. Get a list of work item documents
  2. Download the document
 

GET /WorkItems/{id}/Documents

and

GET /WorkItems/{id}/Documents/{documentId}/Content

Create and assemble a new work item

This workflow assembles documents without displaying an interview. Generally, you will use this workflow when:

  • You have an existing answer set with which to assemble documents, and
  • You do not require your end-users to supply any additional answer data

Steps

The steps below outline how you should use the API to create a work item, assemble, and download documents.

Step Name Description REST API Method
1 Create a work item

Creates a new work item in Advance. You must supply answer XML in the request; Advance will use these answers when assembling the new documents. To assemble documents immediately, ensure that your request is correctly configured for the following parameters:

  • AssembleImmediately (required) – set to true
  • CompleteAssemblySession – omit entirely or set to null
 PUT /WorkItems/{id}
2 Download the documents Optional: you can download the documents produced by the completed assembly session. This requires two API requests:
  1. Get a list of work item documents
  2. Download the document
 

GET /WorkItems/{id}/Documents

and

GET /WorkItems/{id}/Documents/{documentId}/Content

Assemble new documents for an existing work item

This workflow assembles a new set of documents for an existing work item, without displaying an interview. Generally, you will use this workflow when:

  • You have an existing work item, and
  • You have an existing answer set with which to assemble documents, and
  • You do not require your end-users to supply any additional answer data

Steps

The steps below outline how you should use the API to supply answer data, assemble, and download documents.

Step Name Description REST API Method
1

Assemble documents for a work item

Assembles documents for an existing work item. You must supply answer XML in the request; Advance will use these answers when assembling the new documents.

 PUT /WorkItems/{id}/AssemblySessions
2 Download the documents Optional: you can download the documents produced by the completed assembly session. This requires two API requests:
  1. Get a list of work item documents
  2. Download the document
 

GET /WorkItems/{id}/Documents

and

GET /WorkItems/{id}/Documents/{documentId}/Content

Next steps