SDK Example 9: Assemble a Document using the HotDocs Web Service

HotDocs creates a document by merging answer data with a HotDocs template. The following example demonstrates using the HotDocs Web Service API to assemble a completed document from a HotDocs template, using existing answer data. In this example, you will:

Create a WebServiceTemplateLocation object
Retrieve a Template using the WebServiceTemplateLocation
Assemble a completed document using the template and answer data
Save the completed document to disk

Full source code for this example is available at the bottom of the page.

Example Source Code on GitHub

The SdkExample9WebServiceDocumentAssembly example project is available on GitHub, in the HotDocs-Samples repository.

1. Create a Visual Studio Project for Example 2

Before you start, create a new Console Application project for this example, named SdkExample9WebServiceDocumentAssembly. You will gradually add code to this project until you have a working example.

3. Create a Template

When using the SDK, you will interact with a HotDocs Package File (.hdpkg). This package is created when a template file is uploaded from HotDocs Developer. It contains several files used to display content in a HotDocs interview and create a completed document. It is from a HotDocs Package File that you will retrieve the HotDocs template.

3.1 Create a GetTemplate method

First, create a method to return a Template. We will expand this method in the next steps of this example.

private static Template GetTemplate() 
{ 
}

To return a template, you must:

Create a WebServiceTemplateLocation object (required by the template object)
Create a Template object

3.2 Create a WebServiceTemplateLocation

To retrieve a HotDocs Template, you will use WebServiceTemplateLocation. This shows the application where to look for the HotDocs Package file (.hdpkg) containing the template and gives it a unique identifier. WebServiceTemplateLocation requires two parameters:

Package Id – the unique package ID for the template package uploaded in the previous example.
Service URL – the URL from which the Web Service is accessed.

Create a new WebServiceTemplateLocation using the parameters above:

var templateLocation = new WebServiceTemplateLocation("7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2", "http://localhost:80/HDSWebAPI/api/HDCS");

At this stage, you use a static Package ID. This is the ID of the template package uploaded in the previous example.

3.2.1 Add RegisterLocation to the Global.asax.cs file

Before the TemplateLocation can be used by the example code, you must add the following line to the Application_Start method in the project's Global.asax.cs file:

TemplateLocation.RegisterLocation(typeof (WebServiceTemplateLocation));

`3.3 Retrieve the Template`

Once the template location has been created, you can use the Web Service Template Location to locate and retrieve the template. This template object can now be returned.

var template = new Template(templateLocation);

return 
 template;

The final CreateTemplate method looks like this:

private static Template GetTemplate() {
        var templateLocation = new WebServiceTemplateLocation("7A7BF8B9-C895-4BC9-BC1A-44E61D6008A2", "http://localhost:80/HDSWebAPI/api/HDCS");
        var template = new Template(templateLocation);
        return template;
}

4. HotDocs Answer Data

In this example, assume that answer data has already been collected and is ready to be passed to the assembly. You will use an existing string of HotDocs Answer XML to populate the assembled document. Create a new GetAnswers method and return the following answer XML:

private static StringReader GetAnswers() 
{ 
    return new StringReader(@"<?xml version=""1.0"" encoding=""UTF-8"" standalone=""yes""?><AnswerSet version=""1.1""><Answer name=""TextExample-t""><TextValue>World</TextValue></Answer></AnswerSet>"); 
}

We will use this method later, when preparing to assemble the document.

`5. Using the template to assemble a document`

Once the HotDocs Template has been retrieved, it must be passed to the HotDocs Web Service along with answer data. Using the template and answer data, the HotDocs Service can then assemble a completed document.

`5.1 Create the AssembleDocument method`

Create a new method to assemble the document, AssembleDocument:

private static AssembleDocumentResult AssembleDocument()
{                                           
}

In the next two steps, you will retrieve the data required to access the Web Service.

5.2 Retrieve the Template and Answer Data

Use the CreateTemplate and GetAnswers methods created above to retrieve the template and answer data:

var template = CreateTemplate();            
var answers = GetAnswers();

5.3 Create the AssembleDocument Settings

When assembling a document, you must create Assemble Document Settings. These settings define how the assembly should behave. This includes options for specifying the assembled document format (e.g. PDF, DOCX), date formats, and other options. For more information, see the full list of AssembleDocumentSettings Members.

For this example, you will create the AssembleDocumentSettingsObject without changing any of its options. It is created with default values, which produces a Microsoft Word DOCX document. Inside the GetAssembleDocumentResult method, add the following line:

var assembleDocumentSettings = new AssembleDocumentSettings();

5.4 Connect to the HotDocs Web Service

Now that you have collected all the data required to assemble the document, you can connect to the service and invoke the service's AssembleDocument method to output a document.

To connect to the service, you require the URL from which the service is accessed. This will differ depending on your installation of the service. By default, it is http://localhost:80/hdswebapi/api/HDCS. If you customised the port and site name during installation, you can substitute these in like so: http://machine_name:port_number/hdswebapi/api/HDCS.

Create the service using the service URL:

var service = new OnPremiseServices("http://localhost:80/hdswebapi/api/HDCS");

Finally, assemble the document using the service's Assemble Document method, the template, and the answers:

return service.AssembleDocument(template, answers, assembleDocumentSettings, "ExampleLogRef");

The final method looks like this:

private static AssembleDocumentResult AssembleDocument()
{                                           
        var template = CreateTemplate();            
        var answers = GetAnswers();
        var assembleDocumentSettings = new AssembleDocumentSettings();
        
        var service = new OnPremiseServices("http://localhost:80/hdswebapi/api/HDCS");
        return service.AssembleDocument(template, answers, assembleDocumentSettings, "ExampleLogRef");
}

Now that the method is complete, in the next step you will use the method to create the assembled document and save it to a file.

5. Save the Assembled Document

In the Main method of the project, retrieve the assembled document:

var assembledDocumentResult = AssembleDocument();

Next, create an output file and copy the AssembleDocumentResult into the file:

var fileStream = File.Create(@"C:\temp\output" + assembledDocumentResult.Document.FileExtension);

assembledDocumentResult.Document.Content.CopyTo(fileStream);

When the project is run, a completed document will now be assembled and saved to disk.

6. Test

To test assembling a document using the Web Service:

Set the current project as the Startup Project (Right-click the SdkExample9WebServiceDocumentAssembly project in Visual Studio and select Startup Project from the drop-down menu)
Press F5 to run the Project. The console opens and closes.
Open the newly-created output document (C:\temp\output.docx). The answers from the answer collection have been merged into the completed document.

Example Source Code (C#)

using System;
using System.IO;
using HotDocs.Sdk;
using HotDocs.Sdk.Server;
using HotDocs.Sdk.Server.OnPremise;
namespace SdkExample9WebServiceDocumentAssembly
{
    internal class SdkExample9WebServiceDocumentAssembly
    {
        private static void Main(string[] args)
        {
            var assembledDocumentResult = AssembleDocument();
            var fileStream = File.Create("output" + assembledDocumentResult.Document.FileExtension);
               
            assembledDocumentResult.Document.Content.CopyTo(fileStream);                            
        }
        private static AssembleDocumentResult AssembleDocument()
        {                                           
            var template = CreateTemplate();            
            var answers = GetAnswers();
            var assembleDocumentSettings = new AssembleDocumentSettings();
            var service = new OnPremiseServices("http://localhost:80/hdswebapi/api/HDCS");
            return service.AssembleDocument(template, answers, assembleDocumentSettings, "ExampleLogRef");
        }
        private static Template CreateTemplate()
        {
            const string packagePath = @"C:\Temp\HelloWorld.hdpkg";
            string packageId = Guid.NewGuid().ToString();
            var templateLocation = new PackagePathTemplateLocation(packageId, packagePath);
            var template = new Template(templateLocation);
            return template;
        }
        private static StringReader GetAnswers()
        {
        return new StringReader(@"<?xml version=""1.0"" encoding=""UTF-8"" standalone=""yes""?><AnswerSet version=""1.1""><Answer name=""TextExample-t""><TextValue>World</TextValue></Answer></AnswerSet>"); 
        }
    }
}