SDK Example 1 - Assemble a Document

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

Create a PackagePathTemplateLocation object
Retrieve a Template using the PackagePathTemplateLocation
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 SdkExample1DocumentAssembly example project is available on GitHub, in the HotDocs-Samples repository.

1. Create a Visual Studio Project for Example 1

If you have not done so already, create a new Visual Studio Solution and Console Application project. Name it SdkExample1DocumentAssembly. You will use this solution and project to create the first example.

2. Reference the HotDocs Open SDK

Before you start developing with the HotDocs Open SDK, you should have either referenced the HotDocs Open SDK DLLs in your solution or added the SDK project files to your solution. If you have not done this, see Install the HotDocs Open SDK for instructions.

Open your solution and navigate to the class you wish to edit. Add the following Using statements at the beginning of your class:

Using HotDocs.Sdk; Using HotDocs.Sdk.Server; Using HotDocs.Sdk.Server.Local; Using HotDocs.SDK.Server.Contracts; Using Util = HotDocs.Sdk.Util;

In each new project you create, you should include the Using statements listed above. You are now ready to start using the HotDocs Open SDK.

3. Using HotDocs Templates

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 Copy the example package files to a suitable folder

In these examples, you will use an existing HotDocs Package file, HelloWorld.hdpkg, that contains a sample HotDocs Template. To use this Package file in the examples:

Copy the HelloWorld.hdpkg package file from the HotDocs Integration Examples > Example Files folder in the HotDocs-Samples project on GitHub.
Copy the file to C:\temp\. This is the directory from which you will access the package file throughout the examples.

3.2 Create a CreateTemplate method

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

private static Template CreateTemplate() { }

To return a template, you must:

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

3.3 Create a PackagePathTemplateLocation

To retrieve a HotDocs Template, create a new PackagePathTemplateLocation. This shows the application where to look for the HotDocs Package file (.hdpkg) containing the template and gives it a unique identifier.

In the CreateTemplate method created above, specify the package file path and unique identifier:

var packagePath = "C:\temp\HelloWorld.hdpkg"; var packageId = Guid.NewGuid().ToString();

Using the package file path and unique identifier, create the new PackagePathTemplateLocation:

var packageLocation = new HotDocs.Sdk.PackagePathTemplateLocation(packageId, packagePath);

3.3.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 
 (PackagePathTemplateLocation));

`3.4 Retrieve the Template`

Once the template location has been created, you can use the location to retrieve the template. This template object can now be returned.

var template = 
 new HotDocs.Sdk.Template(templateLocation); return template;

The final CreateTemplate method looks like this:

private static Template CreateTemplate() {

var packagePath = @"C:\temp\HelloWorld.hdpkg";

var packageId = Guid.NewGuid().ToString();

var packageLocation = new HotDocs.Sdk.PackagePathTemplateLocation(packageId, packagePath);

var template = new HotDocs.Sdk.Template(templateLocation);

return template;

}

`4. Using the template to assemble a document`

Once the HotDocs Template has been retrieved, it must be passed to a HotDocs Service (either HotDocs Server or HotDocs Core Services) along with answer data. Using the template and answer data, the HotDocs Service can then assemble a completed document.

4.1 HotDocs Answer Data

In this example, you will assume that answer data has already been collected and is ready to be passed to the assembly. We will cover the process of creating HotDocs answers in a later example. For now, 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.

4.2 Create the HotDocs Service

To interact with HotDocs, you need to create a new HotDocs Service to communicate with HotDocs Server. To do this, you will create a new method to create and return a Service object.

private static Services CreateHotDocsService() { }

Before assembling the document, you need to specify a temporary directory where the document can be stored.

var tempDirectoryPath = @"C:\temp\";

Using this directory, you then create the HotDocs Service. In this example, you use the HotDocs.Sdk.Server.Local namespace to access a locally-installed copy of HotDocs Server:

var service = new HotDocs.Sdk.Server.Local.Services(tempDirectoryPath);

This line tells the HotDocs Open SDK to look for a running local instance of HotDocs Server and create a Service object to interact with it. The final method looks like this:

private static 
 Services CreateHotDocsService() {

const string tempDirectoryPath = @"C:\temp\";

var service = new HotDocs.Sdk.Server.Local.Services(tempDirectoryPath);

return service;

}

`4.3 Create the CreateAssembleDocumentResult method`

Using the local instance of HotDocs Server, you can now use the template, answers, and assembly settings specified above to assemble the final document. Create a new method, CreateAssembleDocumentResult, to return a AssembleDocumentResult:

private 
 static AssembleDocumentResult CreateAssembleDocumentResult()

{ }

First, retrieve the HotDocs template using the CreateTemplate method created above:

var 
 template = CreateTemplate();

Next, retrieve the answer data using the GetAnswers method created above:

var answers = GetAnswers();

The next step is to specify how the template and answers will be used to produce a final document. To do this, you need to create the AssembleDocumentSettings.

`4.4 Create the AssembleDocumentSettings`

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 HotDocs.Sdk.AssembleDocumentSettings();

Once the AssembleDocumentSettings are created, the document can be assembled and the AssembleDocumentResult returned.

`4.5 Assemble the document`

To assemble the document and retrieve the result, use the HotDocs Service's AssembleDocument method. This requires three objects that you have created in previous steps:

Template
Answers
AssembleDocumentSettings

To assemble the document, add the following line to CreateAssembleDocumentResult:

var assembledDocumentResult 
 = service.AssembleDocument(template, answers, assembleDocumentSettings, 
 "Assembly Example Log Message");

When executed, this creates an AssemblyResult. The AssemblyResult contains the results from assembling a document, including arrays of documents, any remaining pending assemblies, and any unanswered variables. The AssemblyResult can then be returned.

The final GetAssembleDocumentResult method looks like this:

private static 
 AssembleDocumentResult GetAssembleDocumentResult() {

var template = CreateTemplate();

    var 
 answers = GetAnswers();

    var 
 assembleDocumentSettings = new AssembleDocumentSettings();

    var 
 service = CreateHotDocsService();

    var 
 assembledDocumentResult = service.AssembleDocument(template, answers, 
 assembleDocumentSettings, "Example Assemble Document Log Text");

    return 
 assembledDocumentResult;

}

5. Retrieve the Document

To retrieve an assembled document, create a new AssembleDocument method:

private static 
 void AssembleDocument()

{ }

Once the assembly is completed, you need a file in which to save the AssemblyResult.

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

We can use the assembly result to retrieve the completed document and copy it to the filestream.

assembledDocumentResult.Document.Content.CopyTo(fileStream);

Once the document content has copied to the filestream, the completed document is available to open from the output folder. The final method looks like this:

private static 
 void AssembleDocument()

{

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

assembledDocumentResult.Document.Content.CopyTo(fileStream); }

6. Test

To test the document assembly:

Set the current project as the Startup Project (Right-click the SdkExample1DocumentAssembly 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). A completed document has been assembled.

Example Source Code (C#)

using System;

using 
 System.IO;

using 
 HotDocs.Sdk;

using 
 HotDocs.Sdk.Server;

using 
 HotDocs.Sdk.Server.Local;

namespace SdkExample1DocumentAssembly {

    /// 
 <summary>

    /// This demonstrates assembling 
 a document from a template using HotDocs Server and assuming you already 
 have answer XML

    /// 
 </summary>

    internal 
 class Example1

{

        private 
 static void Main(string[] args)

{ AssembleDocument(); }

        private 
 static void AssembleDocument()

{

            var 
 assembledDocumentResult = CreateAssembleDocumentResult();

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

{ assembledDocumentResult.Document.Content.CopyTo(fileStream); } }

        private 
 static AssembleDocumentResult CreateAssembleDocumentResult()

{

            var 
 template = CreateTemplate();

            var 
 answers = GetAnswers();

            var 
 assembleDocumentSettings = new AssembleDocumentSettings();

            var 
 service = CreateHotDocsService();

            var 
 assembledDocumentResult = service.AssembleDocument(template, answers, 
 assembleDocumentSettings, "Example Assemble Document Log Text");

            return 
 assembledDocumentResult;

}

        private 
 static Services CreateHotDocsService()

{

            const 
 string tempDirectoryPath = @"C:\temp\";

            var 
 service = new Services(tempDirectoryPath);

            return 
 service;

}

        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>");

}

        private 
 static Template CreateTemplate()

{

            const 
 string packagePath = @"C:\temp\HelloWorld.hdpkg";

            var 
 packageId = Guid.NewGuid().ToString();

            var 
 templateLocation = new PackagePathTemplateLocation(packageId, packagePath);

            var 
 template = new Template(templateLocation);

            return 
 template;

} } }