Modifying a Document When the Interview is Complete

Note: only users with the Site Administrator or Integration Administrator user role can manage webhooks.

The Post-assembly Processing Event webhook enables HotDocs Advance to notify your own web application of new assembled documents when a user completes an assembly. When it receives the notification, your web application can then retrieve your assembled documents, modify them, and upload the amended documents back into Advance.

For example, you can insert a QR code from another system into an assembled document, then upload the document back into Advance.

Prerequisites

This webhook has the following prerequisites:

  • Creating a Webhook – you must have an existing webhook that:
    • Uses the Post-assembly processing Event type
    • Has access to the templates to which you want the webhook to apply
  • An endpoint on your web application that accepts a POST request

Only one Post-assembly processing Event webhook is permitted in each site.

Overview

When you create a post-assembly processing event webhook, you specify an endpoint on your own web application that accepts a POST request.

The post-assembly processing webhook activates when a user completes an assembly using a specific template. Advance sends data to your web application with details of the assembled documents that are ready to be modified. When the post-assembly processing webhook is activated, the work item details pane displays a message to the user that says post-assembly processing is in progress.

Once your documents have been retrieved and modified, your web application uploads them back into Advance and updates the post-assembly processing status to Complete. When post-assembly processing is complete, Advance displays your modified documents in the work item details pane.

This is useful as it enables you to modify assembled documents outside of Advance in an application of your choice and send them back into Advance. For example, you might be assembling documents which you want to add a QR code to. When a user completes an assembly, Advance sends data to your QR code processing web application. Your web application can then retrieve your documents and insert a QR code on your documents. Once your documents have been processed, your web application uploads your modified documents back into Advance.

Workflow

The POST request to your endpoint is activated when a user completes an assembly using a specific template. Advance sends data to your own application in which your documents are retrieved, modified, and uploaded back into Advance using a PUT request. When your documents are uploaded back into Advance, the post-assembly processing status is set to Complete using another PUT request.

Your Existing Webhook

This example supposes that you have an existing webhook with the following properties:

  • Name – WebhookExample04
  • URL – https://localhost/WebhookExampleApp/PostProcessing
  • Event Type – Post-assembly processing Event (sends request to your own application to notify you of assembled documents that can be modified)
  • Authentication method – exampleHMAC
  • Active Status – Active
  • Untrusted SSL certificates – No

The URL for the webhook should point to the post-assembly processing endpoint in your own web application.

Authentication method

The token specified in the webhook is passed in the request sent to your endpoint, in the Authorization header. HMAC authentication is the recommended authentication method to authenticate requests from Advance to your own application.

See also Authentication Types

Data Sent from Advance to your Endpoint

When the post-assembly processing event webhook is activated by a user, the webhook sends a POST request to your endpoint. The request contains a JSON string that includes the following data:

  • userContextData — the user context data for the template; this includes details about the user that activated the webhook
  • Documents — the document data for the assembled documents in your work item
  • AnswersUrl — the URL of the assembled documents and answer files

For example:

{
    "userContextData":{
         "userId":"e9bc358f-945c-4bf0-8431-9e9fe5261813",
         "userFirstName":"Administrator",
         "userLastName":"User",
         "userEmailAddress":"administrator@example.com",
         "isClientInterview":false,
         "workGroupId":"3cbee577-4ab3-484c-a954-f71d82992e11",
         "workGroupName":"Work Group One",
         "userGroupIds":[
         "0": "baa86c59-98e7-4ce4-95e4-66a69b7c780c"
         ],
         "userGroups":[
         "0": "ProservTest"
         ],
         "clientId":"00000000-0000-0000-0000-000000000000",
         "clientTitle":null,
         "clientFirstName":null,
         "clientLastName":null,
         "clientEmailAddress":null,
         "clientMobileNumberCountry":null,
         "clientMobileNumber":null,
         "workItemName":"John Sample Json Request",
         "workItemId":"d5275304-35e9-4e61-9286-68294126f850",
         "workItemVersionId":"7e77d8c8-e9d9-4748-a5f7-a73138cefa4a",
         "siteMoniker":"manual1",
         "linkData":null,
         "templatePackageId":"1d63ce39-8544-4db5-91d9-154fd6cdd8ea",
         "templateName":"Sales Agreement",
         "templateVersionNumber":1
    },
    "documents":[
      {
         "documentId":"d794ae69-2e3c-53da-acb3-96111832cda7",
         "name":"Sales Agreement",
         "fileName":"Sales Agreement (1).docx",
         "mimeType":"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "createdDate":"2022-08-15T15:11:26.7824552Z",
         "assemblySessionId":"7e77d8c8-e9d9-4748-a5f7-a73138cefa4a",
         "hasContent":true,
         "assembledOrder":0,
         "url":"https://manual1.cd.hotdocsadvancetest.com/api/rest/v1.1/workitems/d5275304-35e9-4e61-9286-68294126f850/documents/d794ae69-2e3c-53da-acb3-96111832cda7/content"
      }
    ],
     "answersUrl":"https://manual1.cd.hotdocsadvancetest.com/api/rest/v1.1/workitems/d5275304-35e9-4e61-9286-68294126f850/answerfile/content",
     "relativeTimestamp":1660576288>
}

Once the webhook is activated, Advance expects a successful response from your web application application. Anything other than a 200-299 response will result in Advance setting the post-processing status to failed.

Get Documents from Advance via your Endpoint

When your application receives the notification from Advance, your web application must use the following GET request to get your assembled documents:

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

Once your web application retrieves your documents, post-assembly processing can begin.

Upload Documents from your Endpoint to Advance

After modifying the documents, your web application must upload them back into Advance to enable the post-assembly processing status to complete.

Uploading your documents back into Advance

Your modified documents are limited to 30 megabytes.

Once your web application has modified the documents, it must use the following PUT request to upload the documents back into Advance:

PUT /WorkItems/{workItemId}/Versions/active/Documents/{documentId}/Content?name={name}&filename={filename}

You can also use the following PUT request using a specific work item version ID:

PUT /WorkItems/{workItemId}/Versions/{versionId}/Documents/{documentId}/Content?name={name}&filename={filename}

Your document must be in PDF or DOCX format. You must also set the content-type header for the request with the mime type that matches the content you are sending:

  • application/pdf — if the document you are uploading is a PDF document
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document — if the document you are uploading is a DOCX document

The parameters for this request are:

Name Type Location Required Description
workItemId String Request URL Yes The ID of the work item.
documentId String Request URL Yes The ID of the document in your work item.
versionId String Request URL Yes The ID of the work item version.
name String Query string No The display name of the assembled document, shown in the work item details pane.
filename String Query string No

The name and file extension of the file (docx or pdf).

For more information, see the full Advance API documentation.

If you change the file extension of the filename parameter, the file type of the document you upload back into Advance must match. You must also ensure the MimeType in the request header matches the file type of the document you upload back into Advance.

Updating the Post-processing status

After your documents are uploaded back into Advance, your web application must use the following PUT request to update the post-assembly processing status:

PUT /WorkItems/{workItemId}/Versions/active/PostProcessingComplete

You can also use the following PUT request using a specific work item version ID:

PUT /WorkItems/{workItemId}/Versions/{versionId}/PostProcessingComplete

{
    isSuccess: true,
    message: "string"
}

Name Type Location Required Description
isSuccess Boolean Request body Yes The post-processing status of your document.
message String Request body No The message describing the reason for the post-assembly processing status outcome. Advance displays the message in the work item details pane. This is limited to 128 characters.

If post-assembly processing fails, you must use this request to indicate to Advance that post processing is incomplete for the work item. This is done by setting isSuccess to false.

If you do not update the post-assembly processing status within the time allocated by Advance, your work item will be set to Post-assembly processing failed and your documents will not be available to download. By default, you have 5 minutes to update the status.

Retrying unsuccessful post-assembly processing

If post-assembly processing is unsuccessful, the user can relaunch the interview with the same answers by clicking Retry interview in the work item details pane. When the user finishes the interview, post-assembly processing will be reapplied to the assembled document. 

Post-processing Statuses (Internal)

Not sure about this section as these statuses aren't visible to the user in the UI, only the API users. ~Catherine~

The work item's post-processing status enables you to monitor the progress of a work item from document assembly to post-processing completion. The current stage of a work item (the work item's post-processing status) is displayed on the work item details pane.

For example, the following post-processing statuses are:

  • In Progress — the work item's interview is in progress
  • Pending Assembly — the work item's documents are being assembled
  • Post Processing — the assembled documents are sent to the user's application
  • Complete — the modified documents are displayed in the work item details pane

If the core assembly service fails to assemble your documents, Advance displays the following post-processing status in the work item details pane:

  • Post Processing Failed — the document assembly has failed

Webhook Restrictions

If you have Post-assembly processing and New Work Item Version Complete event webhooks configured, the post-processing status must be set to Complete before the New Work Item Version Complete event can activate.