Template Management Overview

You can use the Advance APIs to manage the templates in your tenancy. These resources enable you to perform various actions, such as making a new version live and adding a template to a work group.

Overview

HotDocs Advance generates documents based on templates created in HotDocs Author. These templates, combined with user-supplied answer data, are used to assemble documents. When a template is uploaded to Advance from Author, it is stored as part of a template package. This package includes the template files and associated metadata files. Each subsequent upload of a template to HotDocs Advance creates a new version, maintaining a history of all uploaded versions.

Key terminology

Term Description
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 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.
Template package version A specific iteration of a template package.
Active template package

  • Active template packages can be allocated to work groups, used to create work items and used to assemble documents.

  • Inactive template packages cannot be used to create new work items. Existing work items that use the template package remain accessible, but users cannot open the interview or update their documents. Users can still download existing documents.
Live template package version The live version of a template is the version which template users can assemble. Only one version of a template can be live. The live version of a template might not be the latest version of the template uploaded.
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.

Workflow - Upload a new template and make it available to users

Once you have a template, you need to make it available to users. There are then further actions you can perform, by way of API calls, to change the template's properties, such as its status or availability.

Step 1 - Upload your template from HotDocs Author

A user with the author administrative role, working in HotDocs Author, uploads the template. This is also possible for users of HotDocs 11 with an additional plugin.

In very exceptional cases, you may need to upload the template package version directly to Advance. Whilst we provide an endpoint for this purpose, we do not recommend its use unless specifically advised.

Step 2 - Identify your template package

Some of the actions you can perform through the API require you to send your templatePackageId.

  • GET /TemplatePackages : Use the filters available to identify the templatePackageId for the template you wish to manage.

Step 3 - Activate your template package

By default, all templates uploaded to Advance are active. If you have kept the defaults, you can skip this step.

  1. PATCH /TemplatePackages/{templatePackageId}: Change the status of your template package.

Step 4 - Make a template available to users

To enable users to access the template, you need to add it to a work group. 

  1. PUT /WorkGroups/{workGroupId}/TemplatePackages : Add the template to a work group. 

You cannot add inactive templates to work groups.

Step 5 - Make a template version live

You must have a live template version before users can assemble documents from your template. By default, templates are set to live on upload. A Site Administrator can edit the site settings to change this.

  1. PUT /TemplatePackageVersions/{templatePackageVersionId}/LiveDate : Set the date and time from which the version is live. The template package version is automatically made live on the specified date and time. To forward publish, i.e. to upload a template ahead of time but not make it available until later, use this feature and set the date in the future.

You can then use the same workflow to add additional templates, or use these calls to manage existing templates.

Key considerations

Precedence

If a template has more than one version, only the latest version can be made live. When a template has a newer version, older versions cannot be made live.

For example, if you upload version 2 of a template and set it to be made live in the future, but then upload version 3 and make that live, version 2 will never go live.

Older versions cannot be restored or rolled back; they are retained for reference only. To use an older version, you must reupload it as the newest version.