Integrating HotDocs Server
Welcome to the technical pages for HotDocs partners.
This section is aimed at providing HotDocs partners with all the technical knowledge needed to deploy enterprise level HotDocs implementations. Within this section you will find:
- HotDocs concepts
- Integration overview
- Links to tutorials on how to create content
- Guides to getting started with integration projects, including:
- An example of how HotDocs might be integrated within a bank lending process
We aim to provide all the technical information your organisation needs in order to embed HotDocs into your own products and customer solutions.
Before delving in into the technical detail, we cover HotDocs concepts and architectures, starting with who uses HotDocs and why. We overview the concepts of the HotDocs template and how they are created and used. Then we go into the detail of how to integrate HotDocs Server into a business application. Finally, we take a look how HotDocs might be used within a bank. By using the concepts covered below a HotDocs partner will be equipped to implement HotDocs just about anywhere, from the smallest enterprise to the largest organisations in the world.
What is HotDocs?
HotDocs was initially designed as a tool for the automated drafting of legal documents and was, therefore, used mostly by legal firms. More recently, however, HotDocs has been adopted by both large and small organisations to deal with all kinds of documentation. HotDocs is used by numerous large corporates, including many well know large financial institutions, as well as government bodies and electronic publishers .
One of the principle concepts behind HotDocs is that of the HotDocs template. A HotDocs template is a document outline that contains rules that govern how a document should be constructed or “assembled” given a set of business data. An element of business data might define the type of entity that a document is being created for, say a business or a private individual. When assembling a document, HotDocs follows the rules that have been applied in the HotDocs template regarding wording for private individuals or business and generates the appropriate output document. Similarly, a sales agreement may well have different wording depending on the products and services chosen by individual clients. In this case, the list of products and services selected by a client are fed into HotDocs, which generates documentation following rules defined in the HotDocs template.
Figure 1. Section of HotDocs template with assembly rules.
Creating HotDocs Templates
HotDocs templates are created using a tool called HotDocs Developer that itself uses Microsoft Word as the template editing environment. Most business related documentation is created in Word in the first place, so importing this documentation into HotDocs is a just a few clicks of a mouse.
A client might create their own HotDocs template or they may choose to rely on the services of a HotDocs partner or publisher.
For more information on how to create templates, please see the HotDocs Developer Tutorials documentation.
It is important that software engineers using HotDocs APIs to understand the capabilities of core HotDocs. In many instances, HotDocs reduces the task for engineers as the software can carry out much of the processing that an engineer may otherwise think has to occur in code. HotDocs can, for example, take care of most numeric calculations or manipulate data values internally before formatting documentation. Often there is no need to carry out calculations or manipulate strings of data before calling HotDocs.
HotDocs Interviews (Questionnaires)
Not only does HotDocs generate tailored documentation for end recipients based on the rules contained within the template, it also generates dynamic questionnaires based on the information and dependencies within those templates. These browser based questionnaires are called HotDocs interviews. Changes made to the underlying template, say the addition of a new field asking for a new piece of information, are made visible to the end user as soon as an amended template is “published” or uploaded to a production environment.
Businesses value, the ability HotDocs brings for document experts, rather than IT departments, to update HotDocs templates directly in Word and have that change affect both the documentation that is produced as well as the sequence of questions end users answer to generate that documentation.
Figure 2. A HotDocs Interview for a sample Employment Agreement displayed within a browser window.
Note that the HotDocs interview may or may not immediately precede the generation of the document itself and can be pre-populated with data from other sources. The HotDocs interview may be presented to more than one person and can even be used independently of the document generation itself. Likewise, the HotDocs interview need not be used at all. If all the data required is contained in an existing system, say a CRM, then HotDocs can use this data to generate a document without the need for a HotDocs interview to display.
As we have discussed, HotDocs templates are used for
- Defining and generating the HotDocs interviews; and
- Defining the rules for assembling documents
As a direct reflection on what HotDocs templates are used for, it should be of no surprise that HotDocs Server exposes two principle services. These are to generate interviews and to assemble documents.
Core HotDocs Server is essentially an interview generation and a document generation API. Business applications that require document generation services use the HotDocs Server API for these two principle services.
In a bank, for example, a lending process management application makes calls to the HotDocs APIs to render HotDocs interviews and then assemble lending documents. These HotDocs interviews are typically embedded into the client’s lending process application, or may be presented to the user as a pop-up. Later in this section we will cover a real-world banking process and how HotDocs can be integrated with it to improve document generation efficiency, while at the same time reducing risk.
When the document is assembled it is common for it to either be attached to the process in progress or for the document to be placed in a repository for later reference.
Figure 3. Schematic showing a HotDocs template interview and assembly process interacting with a business application and a document archive. Such an implementation would be typical in a loan document generation process within a bank.
The data that the user has entered into the HotDocs interview is typically saved within the business process or sent for storage in a back-end database. HotDocs uses an XML format called HotDocs Answer XML.
Integrating a business application with HotDocs Server
Here we outline the concepts of integrating with HotDocs. HotDocs technical documentation contains tutorials and C# sample code to get you started, as well as the guides you will need to begin the integration.
HotDocs Server has a native .NET interface and a Web Service interface. HotDocs also has a Cloud Service interface. To simplify porting applications from cloud to on premise, HotDocs Server and vice-versa we also have a HotDocs Open SDK that consists of a set of .NET classes that provide a single interface against which a systems integrator can code.
Before getting to the detail, we will cover the integration concepts for assembling a document, displaying an interview and interacting with the interview.
All HotDocs integrated applications use combinations of the following integration points no matter how complicated that business process is.
These concepts come complete with tutorials. For setting up your development environment see [link].
Assembling a document… no interview
Let’s take the simplest case.
You have a browser based application. How do we invoke HotDocs Server to assemble a document using data the application already holds? In this simple case we do not need an interview.
Assuming HotDocs Server is installed (see Installing HotDocs Server) and that we have a template (see guide to getting started with HotDocs Developer) this is what we need to do.
- Publish the HotDocs template as HotDocs Package and make it available to your application in an accessible folder. This only needs to happen once, not each time the template is assembled.
- In the business application source code we need to use the HotDocs Open SDK to call the “AssembleDocument” method passing in…
- The HotDocs Package created in the first step
- A HotDocs Answer XML that has been generated from your Data. (The Open SDK has methods to help with this but any technique to create XML will work)
- The data returned from the call contains the document that has been assembled. Your application can do as it wishes with the assembled document.
For details on setting up your development environment, as well as a tutorial and sample code, please see the HotDocs Integrations documentation.
Displaying the Interview
In most cases, we will want the user or several users to fill in a HotDocs Interview. How do you display a HotDocs interview within your application?
These are the steps:
- As for the assembled document case, the template needs to be available as a package.
- The business application needs to call “GetInterview” passing in:
- The HotDocs Package (This is the template and dependencies zipped into a single file by HotDocs Developer)
- Some Answer XML if the interview is to be generated
- The interview then renders. The user generally navigates the interview, providing answers to questions and swapping between dialogs in the interview without making calls back to your application. Optionally there can be some call-backs for previews or data lookups if they are implemented.
- On clicking “Finish”, the data from the interview is posted as an encoded string of XML.
- Your application makes a call to the method GetAnswers to retrieve un-encoded XML. You can also use the Answer Collection object to retrieve answers entered in the interview. You can pass the same sequence of data to AssembleDocument to generate documentation.
For a full sequence of tutorials and walk through showing please see the HotDocs Integrations Tutorials.
Note: This architecture allows HotDocs to scale exceptionally, as there is no client-server interaction between the interview loading and the data being passed back to the server. Many thousands of users can be supported on a single live server, though multiple servers should be implemented for failover purposes.
Interacting with the Interview in the Browser.
- To allow the user to select from a custom UI showing records to be pulled into the interview.
- To call some custom or centralised validation methods against data entered in the interview.
- To auto-save data as the user progresses through the interview.
Figure 4. A custom control allowing the user to select a client from an implementation-specific datasource.
Customising the look and feel of the interview
How you display the interview is entirely up to you. You can place the interview in an HTML div element within your own UI. HotDocs interviews are sometimes placed inside a JQuery modal dialogue.
Figure 5. The systems integrator has control over how, where and when the interview is displayed. In this case an interview is displayed in a JQuery modal dialog.
In addition, HotDocs provides you with CSS that can be modified to bring the styling of HotDocs interviews in-line with your own application. See the Customize the Interview Appearance help article for more details.
The different panes within the Interview Outline can be disabled at a template or application level. A HotDocs template developer can disable the Interview Outline pane or the Resource pane using component file options. A software application developer can also pass options through the HotDocs Server API to control certain elements of the interview UI. Finally there are default settings for HotDocs Server that can impact interview layout. Please see the the HotDocs Server Administrator guide for further details.