Web Service Example 5: Get Interview Files

To display correctly, the HotDocs Interview requires additional Interview Files when the interview is initialized. These include:

  • Interview Definition Files – a JavaScript file that defines the structures and content of the interview
  • Image Files – any image files used in Image-style Dialog Elements

This example takes you through the process of retrieving Interview Files from a HotDocs Template Package File uploaded to Web Services.

In this example you will:

  • Create a new MVC project in Visual Studio

  • Retrieve an Interview Definition File from a HotDocs Template Package File in Web Services

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

Example Source Code on GitHub

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

Requirements

Displaying an interview in Web Services requires that a HotDocs Template Package File is uploaded to the service. For information on uploading a Template Package File, see Example 1: Uploading a Template.

1. Create a new MVC Project in Visual Studio

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

2. Reference the DLLs

In the project, edit Program.cs. Add the following using statements at the beginning of the file:

  • using System.Net.Http;

3. Add Subscriber Information and Other Data

In the Main method of the class, add a subscriber ID variable:

var subscriberId = "0";

The Subscriber ID used to connect to local Web Services is always "0".

Next, add a Package ID variable:

var packageId = "ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29";

This is the unique ID (in this case, a GUID) that identifies the HotDocs Template Package File used for the assembly.

Add the required Filename:

var fileName = "HelloWorld.docx.js";

This is the name of the file requested by the interview. In this example, it is an Interview Definition File. The Interview Definition File is a JavaScript file used when rendering the interview. It defines the interview layout and content.

4. Create the Interview File Request

4.1 Create the CreateHttpRequestMessage method

Create a new method, CreateHttpRequestMessage:

private static HttpRequestMessage CreateHttpRequestMessage(string subscriberId, string packageId, string fileName)
{
}

This method takes the following parameters:

  • subscriberId – your ID for signing in to Web Services.
  • packageId – the name of the Template Package used for the assembly.
  • fileName – the name of the Interview File to be retrieved from the Template Package File

4.2 Create the Get Interview File URL

To get an interview file using the Web Services REST service, you use the following address:

  • http://{MachineName}:{PortNumber}/hdswebapi/api/hdcs/interviewfile/{SubscriberId}/{PackageId}

Where

  • MachineName – the name of the server where the Web Service is installed
  • PortNumber – the appropriate port for the Web Service in IIS
  • SubscriberId – the ID of the Subscriber accessing the Interview File. In Web Services, this ID is always '0'.

The URL used when retrieving interview files from the Web Service must also contain specific parameters:

  • FileName – the name of the interview file to be retrieved from the package file

To the Web Services REST service address, the parameters above are added. The complete get interview file URL is formatted as follows:

  • http://{MachineName}:{PortNumber}/hdswebapi/api/hdcs/interviewfile/{SubscriberId}/{PackageId}?filename={FileName}

In the method, add the following line to create the Get Interview File URL:

var interviewFileUrl = string.Format("http://localhost:80/HDSWEBAPI/api/hdcs/interviewfile/{0}/{1}?filename={2}", subscriberId, packageId, filename);

4.3 Create the Request

Next, you create the request, using a HttpRequestMessage:

var request = new HttpRequestMessage { }

The request must have the following properties:

  • RequestUri – the URI to which the request is sent. This is the Get Interview File URL, created above.
  • Method – the method used to send the request. Retrieving an Interview File requires the GET method.

Add the properties to the request, like this:

RequestUri = new Uri(interviewFileUrl),
Method = HttpMethod.Get

Finally, add the following content headers Content headers to the request:

request.Headers.Add("Keep-Alive", "false");

You can now return the request message. The full method looks as follows:

private static HttpRequestMessage CreateHttpRequestMessage(string hmac, string subscriberId, string packageId, string fileName, DateTime timestamp)
{
        var interviewFileUrl = string.Format("http://localhost:80/HDSWEBAPI/api/hdcs/interviewfile/{0}/{1}?filename={2}", subscriberId, packageId, filename);
        var request = new HttpRequestMessage
        {
                RequestUri = new Uri(interviewFileUrl),
                Method = HttpMethod.Get
        };
        request.Headers.Add("Keep-Alive", "false");           
        return request;
}

5. Send the Request

The request can be sent to Web Services. In the Main method, you will now send the request and retrieve the response.

5.1 Create the request

First, create the request message, using the CreateHttpRequestMessage from above:

var request = CreateHttpRequestMessage(subscriberId, packageId, fileName);

5.2 Send the Request using HttpClient

In Main, create a new HttpClient:

var client = new HttpClient();    

This is used to send the request. Next, to send the request, pass the request message to the HttpClient method, SendAsync:

var response = client.SendAsync(request);

5.3 Read the Response

Once the Web Service returns a response, extract the result:



var attachmentContent = response.Result.Content.ReadAsStringAsync();
attachmentContent.Wait();

In this example, the result is read as a string, as it is a JavaScript file that is returned from Web Services. If the file returned was an image, you would write the content as a stream.

6. Save the Interview File

Once Web Services has retrieved the Interview File, the file can be saved. To do this, you will create a new method, SaveInterviewFilesToTempDirectory, that will write the file to disk.

6.1 Create the SaveInterviewFilesToTempDirectory method

Create a new method, SaveInterviewFilesToTempDirectory:

static async Task SaveInterviewFilesToTempDirectory(string filename, string interviewFileContent)
{
}

You will pass in the filename of the Interview File and the file content sent back from Web Services.

6.2 Save the Interview File

First, create an appropriate file path for the interview file. In this example, you will save the interview file in a temp folder in your host application:

var filePath = String.Format(@"C:\examplehostapplication\temp\{0}", filename);

Next, write the interview file content to the file:

File.WriteAllText(filePath, interviewFileContent);

The complete method appears as follows:

private static void SaveInterviewFilesToTempDirectory(string filename, string interviewFileContent)
{
        var filePath = String.Format(@"C:\examplehostapplication\temp\{0}", filename);
            File.WriteAllText(filePath, interviewFileContent);
}

6.3 Call the SaveInterviewFilesToTempDirectory method

In the Main method, add a call to SaveInterviewFilesToTempDirectory. Pass in the file name and the content returned from Web Services:

SaveInterviewFilesToTempDirectory(fileName, attachmentContent.Result);

When the project is run, the interview file content will be saved to the temp folder. From there, it can be accessed by call-backs from the HotDocs Interview.

Testing

To test retrieving an Interview File from a Template Package in Web Services:

  1. Set the current project as the Startup Project (Right-click the WebServicesExample5InterviewFile project in Visual Studio and select Startup Project from the drop-down menu)
  2. Press F5 to run the Project.
  3. Navigate to the location of the downloaded Interview File, C:\temp\. You will see the HelloWorld.docx.js file in the folder.

Source Code (C#)

using System;
using System.IO;
using System.Net.Http;
namespace WebServiceExample5InterviewFile
{
    class Program
    {
        static void Main(string[] args)
        {
            // Web Services Subscription Details
            string subscriberId = "0";
            
            // Request data      
            var packageId = "ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29";
            var fileName = "HelloWorld.docx.js";                                    
            // Create Interview File request            
            var request = CreateHttpRequestMessage(subscriberId, packageId, fileName);
            //Send Interview File request to Web Services
            var client = new HttpClient();
            var response = client.SendAsync(request);
            response.Wait();
            // Read Interview File content from Response
            var attachmentContent = response.Result.Content.ReadAsStringAsync();
            attachmentContent.Wait();
            // Save Interview File
            SaveInterviewFilesToTempDirectory(fileName, attachmentContent.Result);
        }
        private static void SaveInterviewFilesToTempDirectory(string filename, string interviewFile)
        {                
                var filePath = String.Format(@"C:\examplehostapplication\temp\{0}", filename);
                File.WriteAllText(filePath, interviewFile);            
        }
        private static HttpRequestMessage CreateHttpRequestMessage(string subscriberId, string packageId, string fileName)
        {
            var interviewFileUrl = string.Format("http://localhost:80/HDSWEBAPI/api/hdcs/interviewfile/{0}/{1}?filename={2}", subscriberId, packageId, fileName);
            var request = new HttpRequestMessage
            {
                RequestUri = new Uri(interviewFileUrl),
                Method = HttpMethod.Get
            };
            // Add request headers
            request.Headers.Add("Keep-Alive", "false");
            return request;
        }
    }
}