Template Management
HotDocs Developer 10.2 and later contain the HotDocs Cloud Upload plug-in, a HotDocs add-on that lets template authors create template packages and upload them to your host application. A template package is a collection of all the files necessary to display an interview or assemble a document for a template. The plug-in automatically scans templates for dependencies that must also be included in the package, such as shared component files, inserted templates, or dialog element images.
Because each template package is self-sufficient, shared files may exist in multiple template packages. For example, if a common inserted template is updated, the template author would need to create & upload new template packages for each template that uses that inserted template.
The host application is responsible for managing the upload and storage of template packages. It is also responsible for displaying a list of available templates to end users, allowing users to select which templates to use when.
Template Uploading
There are two ways your host application can choose to handle template uploads: direct upload from HotDocs Developer, and manual upload.
Direct Upload (Recommended)
When a template author uses the Cloud Upload plug-in in HotDocs Developer, he or she must specify the URL of the host application's Upload page. This is the page to which the template package(s) will be uploaded; it must adhere to a certain specification for receiving those uploaded packages. For an example upload page, refer to Upload.aspx in Sample Cloud Portal.
Information about your host application's upload page (URL, etc.) can be distributed to template authors either manually or via a simple .hduploadconfig configuration file distributed by your host application. Once configured to point at your upload page, the Cloud Upload plug-in makes it a simple matter to upload template packages, as well as allow users to configure or classify the uploaded templates using features provided by your upload page.
Manual Upload
If template uploading is not expected to be a common occurrence in your host application, you may opt to handle template uploads through other means. The HotDocs Cloud Upload plug-in can be configured to store published template packages locally to the template author's file system. These package files (typically bearing the .hdpkg or .pkg file name extension) can then be transferred or made available to your host application by any means you wish.
Template Storage
Once your users have uploaded a template package, it is your host application's responsibility to provide permanent storage for that package (until such a time as you decide you don't want it any more). HotDocs Cloud Services, while it does maintain a cache of frequently-used templates, makes no guarantees about how long templates will remain in the cache. So your application should be prepared to send the package any time it calls one of the web services, for example when requesting an interview or assembly.
Note that due to the size of templates, sending a template with every request (even if the template is already cached) results in a great deal of wasted bandwidth and unnecessary latency. Host applications should therefore only send the package if HotDocs Cloud Services throws an exception indicating that the specified template package is not already found in its cache; if you send a package that is already in the cache, HotDocs Cloud Services will throw an exception.
Template Organization, Management & User Selection
It is up to your host application to expose templates to your users in any way that makes sense. A host application that deals with only a few specific templates may choose to have a simple user interface for choosing a template -- perhaps buttons or a drop-down list. Other host applications may have complex classification schemes for templates in different subject matter areas or jurisdictions, and allow searching and filtering based on any number of criteria. The only requirement is that you can determine what template to work with, so you can pass it to HotDocs Cloud Services when necessary to make a request.
Template Identification and Caching
To reduce bandwidth requirements and improve performance, HotDocs Cloud Services maintains a cache of recently-used template packages. Templates must be identified by a version-specific identifier that is unique to your host application. In practice we recommend the use of GUIDs as template identifiers. Whenever you make a request to Cloud Services regarding a template, Cloud Services checks for a template in its cache with the identifier you have supplied. If it has a cached template package with the indicated identifier, that template is used. If not, a code is returned indicating that the requested template is not present in the cache. At that point, the call should then be repeated with the template package attached (SOAP), or the template should be uploaded before repeating the call (REST).
If you update the files in a template package, you must use a new packageID since there is no way to replace one package with a new version of the same package in the template cache. (Once a designated time period has elapsed in which the old package has not been used, HotDocs Cloud Services will remove it from the template cache.)