Recipe: Creating Work Item Versions
When you complete an assembly session, Advance creates a new version of the work item, with a new set of assembled documents. You can use versions to add data sequentially. One user can add information, then pass the work item to another user to add more data. You can also use the API to import an externally modified answer file. At each point, an assembly session is used to create a new set of documents. You can track previous versions, which is useful if you are using source control systems.
The following example illustrates a scenario where multiple work item versions are created in various ways.
In this scenario you:
- have an initial set of answers, such as the contact details of your law firm.
- wish to gather data from two users, for example you want an associate to prepare some basic information, then a specialist to add more.
- want to add some data programmatically, perhaps some case numbers.
- need to upload an image, perhaps photographic evidence for a claim.
- have a user give the data a final check.
- assemble documents.
While this is one possible scenario, you can adapt sections of this illustration to fit your own workflow. Steps can be repeated and re-ordered as required.
Step 1 - Create a work item with an initial answer set
To gather data and assemble documents, you must first create a work item. A work item is a named location in HotDocs Advance where you choose a template, enter and edit answer data, and assemble documents from that template and answer data.
You can choose to supply an initial answer set in the form of HotDocs Answer XML. If you do not supply an initial answer set, the work item is created without any answer data.
See: Creating a work item
Step 2 - Display an interview to a user
To gather data for a work item, you must begin a new version, which starts an assembly session. An assembly session is a distinct instance of the document assembly process for a work item.
See: Begin an assembly session
If you want to gather data from your users, you can present an interview to them. An interview is a set of questions that are generated by HotDocs based on the variables and dialogs defined in your template. After receiving a response from the begin assembly session request you can use the Core Assembly Service JavaScript API to embed the interview into a web page in your own application.
See: Display an Interview
To complete a new work item version, you must finish your assembly session. When you complete an assembly session, Advance processes the data it has gathered and completes the new version, including the assembled documents and the new answer set.
See: Complete the assembly session
You now have a work item with a completed work item version.
Step 3 - Display an interview to a user
Repeat step 2 for your second user.
This creates a second work item version.
You can continue to repeat this step until you have gathered all the data you require. Each iteration creates a new work item version.
Step 4 - Programmatically update your answer set
Extract the answer set from the last version of your work item. You can then externally modify this answer set to add your own data.
See: Update an Answer Set Programmatically
To update the answer set, begin a new assembly session, attaching your HotDocs Answer XML.
When you do this, Advance overwrites the existing data file with the answer data you provide. Be sure to keep any answers you wish to retain when modifying the file externally.
Complete the assembly session.
Step 5 - Attach an image
You can upload an image to a document using Advance's API methods. Using this method, you can also associate existing image values in Advance to which you have access permissions with your work item. You create a new assembly session, query the API for the images required by the work item, then upload the requested images.
See: Adding Images to a Document (via API)
Complete the assembly session.
If you do not want to download documents, finish here and skip step 6.
Step 6 - Download assembled documents
- If you want to display an interview to a user, perhaps to perform a final proof read of the data, repeat step 2, making sure you complete the assembly session.
After completing an assembly session, you can query the API for the assembled documents, then download the assembled documents by handling the response stream.