Assembly Sessions

Assembly sessions are specific instances of the document assembly process, for a work item. You use assembly sessions to create new versions of work items.

In this Topic ShowHide

Overview

A work item is a named location in HotDocs Advance, comprising a reference to a specific HotDocs template and a collection of work item versions.

A version is a snapshot of the assembled documents for a work item at a particular point in time, and the data required for Advance to (if necessary) re-create those documents. A version comprises:

• A specific version of a template (to which the work item is linked)
• An answer set – the answer XML data required to create the assembled documents
• A collection of one or more assembled documents – the specific documents produced when Advance processes the specific template and answer set above

Every version created for a work item is saved in Advance. In this way, work item versions help you track how a work item has changed over time.

When you want to create a new version of a work item, you first create a new assembly session for the work item. You use the assembly session to manage the creation of the new version. While the assembly session is in progress, you can optionally display interviews for your end users, to gather answer data. When you complete an assembly session, Advance processes the data it has gathered and creates the new version, including the assembled documents and the new answer set.

Common tasks

• Beginning an assembly session
• Displaying an interview
• Completing an assembly session

Workflow

See Assembling Documents Overview for an overview of the implementation details for using assembly sessions.

There are two main work flows for using assembly sessions. The one you use will depend on whether you already have answer data or if you need to gather it from your end-users. The workflows are:

• Displaying an interview – when you want to gather answer data from an end user, via an interview
• Batch processing – when you already have answer data and want to assemble documents, without user involvement

Displaying an Interview

When gathering answer data from end-users, using an interview, you will use the following workflow:

1. You must create a work item or have an existing work item without a currently in-progress assembly session
2. Begin an assembly session
3. Display the interview in your web application
4. The user enters answer data into the interview
5. When the user clicks the Finish button in the interview, the answer data from the interview is posted back to an endpoint in your own application
6. Complete the assembly session; Advance produces the assembled documents for the new work item version
7. (Optional) Download Assembled Documents from the assembly session

Batch Processing

When assembling documents with existing answer data, you will use the following workflow:

1. You must create a work item or have an existing work item
2. Begin an assembly session, including your answer set in the request
3. Complete the assembly session; Advance produces the assembled documents for the new work item version
4. (Optional) Download Assembled Documents from the assembly session

Assembly Session Status

An assembly session has two states:

• In-progress – the assembly session is currently in-progress; you cannot create a new assembly session for the work item to which the in-progress assembly session is attached
• Complete – the assembly session is complete; you can create a new assembly session for the work item to which this assembly session is attached

When beginning an assembly session, you can use the forceCreate parameter to create a new assembly session even if the work item has a currently in-progress assembly session.

Begin an assembly session

API endpoint: PUT /WorkItems/{id}/Versions/{versionId}

Creates a new assembly session for the work item. See Beginning an Assembly Session for more information.

Complete an assembly session

API endpoint: PUT /WorkItems/{id}/Versions/Active/CompleteSession

When a user clicks the Finish button in an interview, the interview posts answer data to the server. At this point, for Advance to assemble the documents, the status of the assembly session must be set to 'Complete', using the endpoint above. See Completing an assembly session for more information.

Save an in-progress assembly session

API endpoint: PUT /WorkItems/{id}/Versions/Active/SaveSession

Your end users may sometimes decide to leave an interview incomplete, with the intention of returning to it at a later time. To support this, you should implement storing an assembly session. Stored assembly sessions can be resumed using the 'Begin assembly session' endpoint.

Delete an assembly session

API endpoint: DELETE /WorkItems/{id}/Versions/Active/

Your end users may sometimes decide to leave an interview, with no intention of returning to it. To support this, you should implement abandoning an assembly session. Abandoned assembly sessions do not assemble new documents and cannot be resumed.

Download completed documents from an assembly session

Once an assembly session is complete, you will often want to download the documents assembled by that session. This takes two steps with the API:

• Get a list of the most recently assembled documents from a work item (GET /WorkItems/{id}/Documents)
• Download a specific document from a work item (GET /WorkItems/{id}/Documents/{documentId}/Content)

This action is typically performed at the request of the end user who has just finished the interview.