Get Interview

The GetInterview method provides an answer-gathering interview to display in a browser. The response from the method provides:

An Interview HTML fragment to embed on the page in your Web application where you want the interview to appear.
The interview definition files that contain the template-specific logic for the interview. Either:
- JavaScript files (for JavaScript interviews)
- Compiled Silverlight DLLs (for Silverlight interviews)
Any images used on interview dialogs

Displaying the Interview

Before the interview can be rendered in the browser, there are several files that the interview needs to access. These files are:

Interview Runtime Files
Interview Definition File
Interview Stylesheet
Interview Image Files (optional) – any images used by Dialog Elements in the Interview.

For more information about displaying the interview, see Displaying HotDocs Interviews.

Download Interview Runtime Files

See Browser Interview Release Notes for download links to the latest release of the Interview Runtime Files.

Get Interview POST

HTTP Request

POST https://{subscribedEndpoint}/hdcs/interview/{subscriberID}/{packageID}/{templatename=null}

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 Template Package File containing the Template for which to display an interview. 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.
templatename	Path	No	The file name of the specific Template for which you are requesting the interview. This can be omitted to automatically request the interview for the primary Template in the Template Package File.
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 GetInterview for more information.
format	Query string	Yes	The interview format requested. This can be: JavaScript Silverlight Unspecified
markedVariables	Query string	No
tempimageurl	Query string	Yes	The URL to a folder where temporary files are created during the interview. For example, when an interview uses Image Dialog Elements, the image files are copied to this folder. The interview can retrieve the image files from this location when they are required. Also, when HotDocs Server generates a document preview, the preview files are copied to this folder. Files in this folder are automatically deleted at an appropriate time after completing the assembly.
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 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.

encodeFileNames	Query string	Yes	Either True (encoded) or False (unencoded). Indicates whether filenames in the returned multi-part MIME document are encoded. All new integrations with Cloud Services must encode file names. Unencoded file names are for legacy integrations only. If True, the filenames are first encoded in UTF-8, then URL-encoded. This allows any special character valid in a file name to be passed back in the Response. This flag is useful as special characters can lead to errors when parsing the response back from the server, if filenames are not encoded properly. If retrieved files are saved to disk, the file names should be decoded before writing to disk.
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.
(additional settings)	Query string	No	You can also optionally include any interview settings listed in GetInterviewOptions.Settings. Settings specified on the query string will override the defaults designated in the Cloud Services administration portal. Several Interview Settings are required: FormActionUrl HotDocsJsUrl HotDocsCssUrl InterviewDefUrl DocPreviewUrl
answers	Request body	No	An XML answer string used to pre-populate the interview. Answer XML is sent back from completed interviews to the URL specified by the FormActionUrl parameter (see above). If Answer XML is used in the interview, you must add the appropriate Content-Type header to the request (see below).

Example URL

https://cloud.hotdocs.ws/hdcs/interview/examplesubscriber/ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29?format=JavaScript&tempimageurl=exampleUrl&billingRef=exampleref

Response

If successful, this method returns a multi-part MIME document in the response body. The first MIME part contains the HTML fragment necessary to initialize the browser interview in the context of your web page. Subsequent MIME parts are interview definition files and images that may be requested by the end user's web browser as the interview initializes and the user interacts with it.

Request Headers

The Get Interview request must include the following headers.

Name	Type	Example Data	Description	Example (C#)
x-hd-date	DateTime value	2015-01-31T08:55:19Z	The Date and Time of 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"));
Content-Type	String	text/xml	Optional. The type of content sent with the request. When requesting an interview, HotDocs Answer XML content may be used to load existing answers into the interview. If you do not send answer XML with the request, the Content-Type header can be omitted.	request.Headers.Add("Content-Type", "text/xml");
Authorization	String	Calculated HMAC	The HMAC used to sign the request.	request.Headers.TryAddWithoutValidation("Authorization", hmac);
Keep-Alive	Boolean	false	The connection to Cloud Services should not be a persistent connection when assembling a document, as only a single request is being made.	request.Headers.Add("Keep-Alive", "false");

Example Request

POST https://cloud.hotdocs.ws/hdcs/interview/examplesubscriber/ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29?format=JavaScript&tempimageurl=test&HotDocsJsUrl=https://machine-name/HDServerFiles/6.5/js/&HotDocsCssUrl=https://machine-name/HDServerFiles/6.5/stylesheets/&FormActionUrl=Disposition.aspx
HTTP/1.1 
x-hd-date: 2015-08-06T11:34:45Z 
Authorization: 4FT9unxKK2Ygy136W6WkU5LPdJU= 
Keep-Alive: false 
Content-Type: text/xml 
Host: cloud.hotdocs.ws 
Content-Length: 165 
Expect: 100-continue 
Connection: Keep-Alive 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><AnswerSet version="1.1"><Answer name="TextExample-t"><TextValue>Hello World</TextValue></Answer></AnswerSet>

HMAC Calculation for Get Interview

For calls to Upload Package, the HMAC is calculated from the following list of parameters, in order:

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	ed40775b-5e7d-4a51-b4d1-32bf9d6e9e29	The name of the HotDocs Package File (.hdpkg) uploaded to Cloud Services.
templateName	String	ExampleTemplate1	A string value. The name of the template in the package file that is to be assembled. If there is only one template in the package, an empty string is used.
sendPackage	Boolean	False	Always False for GetInterview requests, as a Template Package File is not sent with the request.
billingRef	String	ExampleCustomer, Template Upload	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.
format	String	Native	The interview format requested.
tempImageUrl	String	http://www.companyname/images/	The base URL from which the browser interview can request graphics or other peripheral files necessary for an interview in progress. For example, when an interview is displayed that uses Image dialog elements, your host application must know about those image files, and be able to deliver them in response to requests to this URL.
settings	String	AddHdMainDiv=true\nUnansweredFormat=[Variable]	A string containing assembly settings, to control assembly behaviour, separated by a newline character. These include URLs for retrieving JavaScript and stylesheets. If you are not using any assembly settings, you must use an empty string to calculate the HMAC.

Example (C#)

Walkthrough

For a full walkthrough of displaying an interview retrieved from Cloud Services, see the Cloud Services Example 3: Display an Interview article in the HotDocs Integrations documentation.

Code

For a full code example of displaying an interview using Cloud Services, see the CloudServicesAPIExample3Interview project in the HotDocs Integration Examples.