Displaying an Interview

Once you receive the response from the create new work item version API endpoint, you can display an interview for a work item.

Prerequisites

Before displaying an interview in the browser, you must have:

The response data from the create new work item version API request
The access token used to make the above API request; either:
- Using the Implicit flow
- Using the Resource Owner flow

Additionally, you must have the following items in the tenancy in which you are creating the work item:

A work item – the ID of a work item in your tenancy is required when making the request

Note: if you use the resource owner flow, you should not pass the access token to the browser as is done in the implicit flow code example below. You should instead store the token server-side and use it to make the request to complete the work item version.

Overview

Note: displaying an interview is optional. If you do not want to gather data from a user – for example, if you just want to assemble documents using an existing set of data, without any user intervention – you can skip to the completing an work item version topic.
Alternatively, if you want your users to check or print the existing answers for a work item, you can generate an answer summary.

An interview is a series of questions used to gather data from your template users. HotDocs generates the questions from the variables and dialogs you define in your template. Once you receive the response from the create new work item version request, you can use the Core Assembly Service JavaScript API to embed an interview for the work item version into a web page. The Implementation Steps section of this topic explains these steps in detail.

Response Data from Create a New Work Item Version

The create new work item version method provides the following data in its response. You will use this data when displaying the interview in your own web application.

Name	Type	Description
versionId	Guid	Identifies the work item version within Advance. You will need this ID when using other API methods that interact with the work item version. For example, the save, delete, and complete work item version endpoints.
coreAssemblySessionId	Guid	Identifies the assembly session within the Core Assembly Service. You will need this ID when using HD$.AttachSession to display the interview in a user's browser.
urls.interviewJsUrl	String	The URL from which to load the interview.js file. You must include this file in the page on which the interview is displayed.
urls.serviceMetadataUrl	String	The URL for the current assembly session in the Core Assembly Service.
urls.workItemUrl	String	The URL of the work item.

Implementation Steps

To display an interview in your web application requires the following implementation steps:

Pass required work item version data to your interview page.
Add the interview container div to your interview page.
Add the interview.js reference to your interview page.
Configure the HotDocs InterviewOptions object.
Add the HD$.AttachSession method call.
Create a new endpoint in your application for returning the interview page.

This steps are explained in detail below. There is also a complete display interview code example at the end of this topic.

1. Pass required work item version data to your interview page

You must first pass the following data to the page on which you want to display the interview:

ServiceMetadataUrl – the URL for the assembly session in Core Assembly Service; from the create new work item version response
CoreAssemblySessionId – the Core Assembly Service assembly session ID, from the create new work item version response
WorkItemId – the ID of the work for which you are displaying the interview; you previously used this when making the create new work item version response
Token – the access token; you previously used this token when making the create new work item version response

All of these items of data are retrieved by requests you made when retrieving an access token (Getting an Access Token using the Implicit Flow) and creating a new work item version.

Example

In an ASP.NET web application, you would typically create a new view model to pass this data to the interview page. For example:

using System;
namespace InterviewTestApp.Models
{
    public class InterviewViewModel
    {
        public string ServiceMetadataUrl { get; set; }
        public string CoreAssemblySessionId { get; set; }
        public Guid WorkItemId { get; set; }
        public string Token { get; set; }
    }
}

You can then include this model at the top of the page on which you are displaying the interview:

 @model InterviewTestApp.Models.InterviewViewModel

2. Add the interview container div to your interview page

To display the interview HTML on your page, you must include an empty div to which Advance can attach the interview HTML. This div must have a unique ID. For example, hdMainDiv. The ID is used later, when configuring the Container property on the HotDocs InterviewOptions.

Example

Your div will look as follows:

<div id="hdMainDiv"></div>

3. Add the interview.js reference to your interview page

Your web application will have a page on which to display the interview. On this page you must include a script reference to the HotDocs interview.js file, required to display the interview. This will use the interviewJsUrl value passed back in the response from the create new work item version API call.

Example

When using the example view model from step 1, your reference will look like this:

<script type="text/javascript" src="Model.InterviewJsUrl"></script>

4. Configure the HotDocs InterviewOptions

Next, you must configure various options that instruct the interview how to behave. You do this using the IInterviewOptions interface The required properties are:

Container (string) – the ID of the div to which you want to attach the interview HTML; for example, hdMainDiv
Theme (string) – the styling to use for the interview; use default.css for the default interview theme
OnInit (function) – a function that invokes HD$.RegisterHandler; this registers the OnSessionComplete event that fires when the user clicks the Finish button in the interview. The OnSessionComplete handler function should:
- (Required) Post the access token and work item ID from the interview back to a '/WorkItems/{workItemId}/Versions/{versionId}/Complete' endpoint in your application (Completing an Assembly Session)
- (Optional) Redirect the user to a 'Interview Complete' page in your application

Example

<script type="text/javascript">
    var interviewOptions = {
        Container: "hdMainDiv",
        Theme: "default.css",
        OnInit: () => {
            HD$.RegisterHandler("OnSessionComplete",
                (e) => {
                    var xhr = new XMLHttpRequest();
                    xhr.open("PUT", '{baseUrl}/WorkItems/{workItemId}/Versions/{versionId}/Complete', true);
                    xhr.setRequestHeader("Content-Type", "application/json");
                    xhr.onreadystatechange = function() {
                        if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
                            window.location.href = "/Home/LandingPage";
                        }
                    }
                    xhr.send(JSON.stringify({ Token: "@Model.Token", WorkItemId: "@Model.WorkItemId" }));
            });
        }
    };></script>

5. Using HD$.AttachSession

You can now use the HD$.AttachSession method to attach the interview to the assembly session. The method call is defined as follows:

HD$.AttachSession(coreAssemblySessionId, serviceMetadataUrl, interviewOptions)

Example

When using the example view model from step 1 and the interviewOptions variable from step 4, add a call to attach session below interviewOptions:

HD$.AttachSession(
    "@Model.CoreAssemblySessionId",
    "@Model.ServiceMetadataUrl",
    interviewOptions
);

6. Create a new endpoint in your application for displaying the interview

Finally, you need to add an endpoint in your application that will return the interview page when requested by your end-user.

Example

Assuming you are using an ASP.NET web application, and are displaying the interview on the Index.cshtml page, add the following example code to the Index endpoint in your HomeController class:

var interviewViewModel = new InterviewViewModel
{
    ServiceMetadataUrl = assemblySessionData.Urls.ServiceMetadataUrl,
    InterviewJsUrl = assemblySessionData.Urls.InterviewJsUrl,
    CoreAssemblySessionId = assemblySessionData.CoreSessionId,
    WorkItemId = workItemId,
    Token = token
};
return View(interviewViewModel);

Next Step

Completing a Work Item Version