Displaying an Interview

Once you receive the response from the begin assembly session API endpoint, you can display an interview for a work item.

In this Topic ShowHide

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 (see Getting an Access Token using the Resource Owner Flow or Getting an Access Token using the Implicit Flow for more information)

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.

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 details.

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.

Implementation Steps

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

1. Pass required assembly session data to your interview page
2. Add the interview container div to your interview page
3. Add the interview.js reference to your interview page
4. Configure the HotDocs InterviewOptions object.
5. Add the HD$.AttachSession method call.

6. 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 (either Getting an Access Token using the Resource Owner Flow or 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:

<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 begin assembly session 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,
• 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) => {
                    $.post("CompleteAssemblySession",
                        {
                            Token: "@Model.Token",
                            WorkItemId: "@Model.WorkItemId"
                        },
                        function() {
                            // Redirect the user to your application's 'Interview Complete' landing page
                            window.location.href = "/Home/LandingPage";
                        });
            });
        }
    };
</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 async Task<ActionResult> Index()
{            
    // You should have implemented these methods in the 'Getting an Access Token using the Resource Owner flow' and 'Begin an assembly session' topics
    var token = await new ResourceOwnerAuthorization().GetResourceOwnerToken();
    var assemblySessionData = AssemblySessionHandler.BeginAssemblySession(token);
    // The ID of the work item; this must be the same as the one used in 'BeginAssemblySession'
    var workItemId = Guid.Parse("a1e0e795-5a51-44f5-8fe2-e85a61dbf3c2");
    // Create the view model, containing the data required to create the interview
    var interviewViewModel = new InterviewViewModel
    {
        ServiceMetadataUrl = assemblySessionData.ServiceMetadataUrl,
        InterviewJsUrl = assemblySessionData.InterviewJsUrl,
        CoreSessionId = assemblySessionData.CoreSessionId,
        WorkItemId = workItemId,
        Token = token
    };
    return View(interviewViewModel);
}

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">
    // Configure the interview options; this registers the 'OnSessionComplete' event that fires when the user clicks the
    // interview 'Finish' button. It then posts the data from the interview to your 'CompleteAssemblySession' endpoint.
    // You will add the 'CompleteAssemblySession' endpoint in the next topic, 'Completing an Assembly Session'.

    // Note that the value for the 'Container' property must match the ID of your interview container div at the top of the page.
    var interviewOptions = {
        Container: "hdMainDiv",
        Theme: "default.css",
        OnInit: () => {
            HD$.RegisterHandler("OnSessionComplete",
                (e) => {
                    $.post("CompleteAssemblySession",
                        {
                            Token: "@Model.Token",
                            WorkItemId: "@Model.WorkItemId"
                        },
                        function() {
                            // Redirect the user to your application's 'Interview Complete' landing page
                            window.location.href = "/Home/LandingPage";
                        });
                });
        }
    };
 
    // Attach the assembly session to the interview

    HD$.AttachSession(
        "@Model.CoreSessionId",
        "@Model.ServiceMetadataUrl",
        interviewOptions
    );
</script>

Next Step

• Completing an Assembly Session