Displaying an Interview

Once you receive the response from the begin assembly session 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 begin assembly session API request (see Begin an Assembly Session)
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 assembly session.

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 assembly session 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 begin assembly session request, you can use the Core Assembly Service JavaScript API to embed an interview for the assembly session into a web page. The Implementation Steps section of this topic explains these steps in detail.

Response Data from Begin Assembly Session

The begin assembly session 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
hdaSessionId	Guid	Identifies the assembly session within Advance. You will need this ID when using other API methods that interact with the assembly session. For example, the save, delete, and complete assembly session endpoints.
coreSessionId	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.
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.
serviceMetadataUrl	String	The URL for the current assembly session in the Core Assembly Service.

Implementation Steps

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

Pass required assembly session 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 assembly session 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 begin assembly session response
CoreSessionId – the Core Assembly Service assembly session ID, from the begin assembly session response
WorkItemId – the ID of the work for which you are displaying the interview; you previously used this when making the begin assembly session request
Token – the access token; you previously used this token when making the begin assembly session request

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 beginning an assembly session.

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 CoreSessionId { 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:

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 begin assembly session API call.

Example

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

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 'CompleteAssemblySession' endpoint in your application (you will create this endpoint in the next topic, 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("POST", '/Home/CompleteAssemblySession', 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(coreSessionId, 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.CoreSessionId",
    "@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.ServiceMetadataUrl,
    InterviewJsUrl = assemblySessionData.InterviewJsUrl,
    CoreSessionId = assemblySessionData.CoreSessionId,
    WorkItemId = workItemId,
    Token = token
};
return View(interviewViewModel);

Code Example

C#

Note: this code example assumes that you are using .Net Framework 4.6 and an ASP.NET Web Application project, and have completed the beginning an assembly session topic.

HomeController.cs


public ActionResult Index()
{
    // The unique name of client making the request, created through the Advance Client Management application
    var clientName = "yourTenancyABCXYZ";
    // The endpoint for retrieving the access token
    var requestUrl = "https://yourtenancy.yourorganization.com/HdaAuth/Authorize/LogIn";
    var requestUrl = "https://yourtenancy.hotdocsadvance.com/Auth/Authorize/LogIn";
    // The endpoint (HandleToken, below) in your application to which the token is returned
    // This URL must be the same as the return URL specified when creating your client; 
    // see the Creating a new API Client topic for more information.
    var returnUrl = "https://yourorganization.com/YourApplication/Home/Interview";
    // The type of response, containing the access token, returned from Advance
    var responseMode = "FormPost";
    // The completed request URL, using the values specified above. You then redirect to the Advance login page
    var url = string.Format("{0}?clientName={1}&returnUrl={2}&responseMode={3}", requestUrl, clientName, returnUrl, responseMode);
    return Redirect(url);
}
[HttpPost]
public async Task<ActionResult> Interview()
{
    // Retrieve the access token; you can then use the token to make requests to the Advance API
    var token = Request.Form["ApiToken"];
 
    // Create a new work item; see Create Work Item example for more details
    var workItemId = await new WorkItemRequest().CreateWorkItem(token);
 
    // Create a new assembly session; see the Beginning an Assembly Session topic for more details 
    var interviewModel = await new AssemblySessionRequest().CreateAssemblySession(token, workItemId);
 
    interviewModel.WorkItemId = workItemId;
    interviewModel.Token = token;
    return View(interviewModel);
}

InterviewViewModel.cs

using System;

namespace AdvanceExampleApplication.Models
{
    public class InterviewViewModel
    {
        public string ServiceMetadataUrl { get; set; }
        public string InterviewJsUrl { get; set; }
        public string CoreSessionId { get; set; }
        public Guid WorkItemId { get; set; }
        public string Token { get; set; }
    }
}

Index.cshtml

@model AdvanceExampleApplication.Models.InterviewViewModel
 // Container div for the interview
<div id="hdMainDiv"></div>
 // Interview JavaScript reference
<script type="text/javascript" src="@Model.InterviewJsUrl"></script>
 <script type="text/javascript">
    var interviewOptions = {
        Container: "hdMainDiv",
        Theme: "default.css",
        OnInit: () => {
            HD$.RegisterHandler("OnSessionComplete",
                (e) => {
                    var xhr = new XMLHttpRequest();
                    xhr.open("POST", '/Home/CompleteAssemblySession', 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" }));
            });
        }     // Attach the assembly session to the interview
    HD$.AttachSession(
        "@Model.CoreSessionId",
        "@Model.ServiceMetadataUrl",
        interviewOptions
    );
</script>

Next Step

Completing an Assembly Session