Generating an Answer Summary

An answer summary is a viewing option for a HotDocs interview. An answer summary displays a list of interview questions and their answers so that users can review or print the answers.

Prerequisites

Before displaying an answer summary in the browser, you must have:

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

  • A work item with an answer file – 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

An answer summary displays a list of interview questions and their answers. HotDocs generates the questions from the variables and dialogs you define in your template and displays the corresponding answers from the answer file you supply. You can review and print the answers; you cannot edit the answers in this view.

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 answer summary for the assembly session into a web page. The Implementation Steps section of this topic explains these steps in detail.

Response Data from Create New Work Item Version

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

Name Type Description
versionId 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.
coreAssemblySessionId Guid Identifies the assembly session within the Core Assembly Service. You will need this ID when using HD$.AttachSession to display the answer summary 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 answer summary is displayed.
urls.serviceMetadataUrl String The URL for the current assembly session in the Core Assembly Service.

Implementation Steps

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

  1. Pass required assembly session data to your answer summary page.
  2. Add the interview container div to your answer summary page.
  3. Add the interview.js reference to your answer summary 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 answer summary page.

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

1. Pass required assembly session data to your answer summary page

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

  • ServiceMetadataUrl – the URL for the assembly session in Core Assembly Service; from the begin assembly session response
  • CoreAssemblySessionId – 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 answer summary; 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 answer summary 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 answer summary page

To display the answer summary 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 answer summary page

>Your web application will have a page on which to display the answer summary. On this page you must include a script reference to the HotDocs interview.js file, required to display the answer summary. 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 answer summary 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 OnHDStart (function) - the event that fires when an interview is fully loaded and initialized in the browser, but before the user has a chance to interact with the interview. To display an answer summary you must set the following settings:
    • SetVisibility - set to false to hide the interview
    • SwitchView - set to AnswerSummary to display the answer summary

Example

<script type="text/javascript">
    var interviewOptions = {
        Container: "hdMainDiv",
        Theme: "default.css",
        OnInit: () => {
            HD$.RegisterHandler ("OnHDStart", (eventArgs: any) => {
                HD$.SetVisibility("Toolbar", false);
                HD$.SwitchView("AnswerSummary");
            });
            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 answer summary

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

Example

Assuming you are using an ASP.NET web application, and are displaying the answer summary 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,
    CoreSessionId = assemblySessionData.CoreSessionId,
    WorkItemId = workItemId,
    Token = token
};
return View(interviewViewModel);

Related Topics