Get Interview File

The GetInterviewFile method enables the host application to retrieve a specified file from a HotDocs Package File stored in CloudWeb Services.

Using Get Interview File

Use the GetInterviewFile method when you need additional files for the interview. When the interview requires the file:

The interview triggers a callback to an endpoint in the host application.
The endpoint in the host application uses GetInteviewFile to retrieve the requested file from the Template Package in Cloud Services.
The host application returns the file.

You must define the endpoint URLs for the Interview File callbacks in the Get Interview call.

Interview Files

Typically, you use the GetInterviewFile method to retrieve the files in the table below.

File Type	Example File Name	Description	Interview Setting in Get Interview
Interview Definition file	ExampleTemplate.docx.js	A JavaScript file used when rendering the interview. This file defines the interview layout and content.	InterviewDefUrl
Image Files (optional)	DialogImage.png	Any image used by Image-type Dialog Elements in the interview. Images used by Dialog Elements are stored in the HotDocs Package File containing the Template.	TempInterviewUrl

For more information on the files required by the interview, see Displaying HotDocs Interviews.

Interview File GET

HTTP Request

GET https://{subscribedEndpoint}/hdcs/interviewfile/{subscriberID}/{packageID}?filename={filename}

Parameters

Name	Location	Required	Description
subscribedEndpoint	Path	Yes	The endpoint to which the caller is subscribed. This is either: USA – cloud.hotdocs.ws EU – europe.hotdocs.ws
subscriberID	Path	Yes	The caller's Cloud Services subscriber ID.
packageID	Path	Yes	An ID identifying the package containing the template about which you are requesting information. This is set when uploading the package file. If you are using the HotDocs Hub to store templates, see Get a Package ID from HotDocs Hub.
filename	Query string	Yes	The name of the file to retrieve from the package file. For example, ExampleTemplate1.docx.js.
date	HTTP header or query string	Yes	The date and time (in UTC) of the request, formatted according to RFC 1123. This date can be included either as a parameter on the query string or in an "x-hd-date" (custom) HTTP header.
signature	HTTP header	Yes	The base64-encoded HMAC calculated using the parameters of this request. Note: the HMAC must be included in an "Authorization" HTTP header. See HMAC calculation for Component Info.
billingRef	Query string	No	Enables you to specify information to include in usage logs for this call. For example, you can use a string to uniquely identify the end user that initiated the request and/or the context in which the call was made. When you later review usage logs, you can then see which end user initiated each request. This information can enable you to audit or pass costs on to those end users.
RetrieveFromHub	Query string	No	Enables you to retrieve a HotDocs template from the HotDocs Hub instead of a template stored in the Cloud Services cache. Select from the following options (case-insensitive): No (default value) – do not connect to HotDocs Hub; use the Package ID in request path (see above) to get the template from the Cloud Services cache ByTemplateId – use the Package ID in request path as the ID of the template to retrieve. Cloud Services checks the HotDocs Hub for the latest version of the template and: If the Cloud Services cache has the latest version of the template, the template is retrieved from the cache. If the Cloud Services cache does not have the latest version of the template, the latest version of the template is retrieved from the HotDocs Hub. The Cloud Services cache is updated with the template retrieved from the HotDocs Hub. ByVersionId – use the Package ID in request path as the ID of the specific template Version to retrieve. Cloud Services checks the HotDocs Hub for the specific version of the template and: If the Cloud Services cache has the same version of the template as the Hub, the template is retrieved from the cache. If the Cloud Services cache does not have the same version of the template as the hub, the specific version of the template is retrieved from the HotDocs Hub. The Cloud Services cache is updated with the template retrieved from the HotDocs Hub.

Example URL

https://cloud.hotdocs.ws/hdcs/interviewfile/examplesubscriber/ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29?filename=example.docx.js&billingRef=exampleref

Response

If successful, this method returns a Stream containing the requested file.

Request Headers

A GetInterviewFile request must include the following headers.

Name	Data Type	Data	Description	Example (C#)
x-hd-date	DateTime value	2015-01-31T08:55:19Z	A Date and Time for the request. This is the same value as the date/time used when calculating the HMAC.	request.Headers.Add("x-hd-date", timestamp.ToString("yyyy-MM-ddTHH:mm:ssZ"));
Authorization	String	Calculated HMAC	The HMAC used to sign the request.	request.Headers.TryAddWithoutValidation("Authorization", hmac);

Example Request

GET https://cloud.hotdocs.ws/hdcs/interviewfile/examplesubscriber/ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29?filename=ExampleTemplate.docx.js HTTP/1.1
x-hd-date: 2015-07-13T10:21:40Z
Authorization: 7wSpwmWQFaqctzE29+3vz8W4JBc=
Host: cloud.hotdocs.ws
Connection: Keep-Alive

HMAC Calculation for Get Interview File

The HMAC for a Get Interview File request is calculated from the following list of parameters:

Name	Type	Example Data	Description
signingKey	String	example-signing-key	The Signing Key assigned to your Cloud Services account. You can find your Signing Key by logging in to the Cloud Services Portal.
date	DateTime	2015-01-31T08:55:19Z	Date and time, using the format "yyyy-MM-ddTHH:mm:ssZ". For example, a datetime of 31/05/2015 08:55:19 is formatted as 2015-01-31T08:55:19Z.
subscriberID	String	ExampleCompany	Subscriber ID named used to connect to Cloud Services. This was provided when you signed up to Cloud Services.
packageID	String		The ID of the HotDocs Package File (.hdpkg) uploaded to Cloud Services where you retrieve the file.
fileName	String	ExampleTemplate1.docx.js	The name of the file to retrieve from the package file.
billingRef	String	ExampleCustomer, call to GetInterviewFile	Enables you to specify information to include in usage logs for this call. For example, you can use a string to uniquely identify the end user that initiated the request and/or the context in which they made the call. When you later review usage logs, you can see which end users initiated each request. This information can enable you to audit or pass costs on to those end users.

Example (C#)

Walkthrough

For a full walkthrough of calculating the HMAC and retrieving an Interview File from a template package in Cloud Services, see the Cloud Services Example 5: Get Interview File article in the HotDocs Integrations documentation.

Code

For a full code example of retrieving an Interview File from a template package in Cloud Services, see the CloudServicesAPIExample5InterviewFile project in the HotDocs Integration Examples.