Display Interview – Code Example

The examples below provide code for creating an assembly session, displaying an interview, and finishing an assembly session.

Prerequisites

Before making an 'display interview' request, you must have an access token to sign the request. You can retrieve an access token using one of the following flows:

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 example below. You should instead store the token server-side and use it to make the request to complete the assembly session.

Overview

The example below contains code for the following 'Using the API' topics:

Code Examples

C#

This code example assumes that you are using .Net Framework 4.6 and a new ASP.NET Web Application project. The HomeController.cs and Index.cshtml files should automatically appear in your project. You will need to add the following files to your project manually:

AssemblySessionHandler.cs
AssemblySessionDto.cs
InterviewViewModel.cs (under the Models folder)
LandingPage.cshtml (under the Views folder)

HomeController.cs

using System;
using System.Web.Mvc;
using System.Threading.Tasks;
using AdvanceExampleApplication.Models;
namespace AdvanceExampleApplication.Controllers
{
    public class HomeController : Controller
    {
        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);
        }
        [HttpPost]
        public async Task CompleteAssemblySession(string workItemId, string token)
        {
            await AssemblySessionHandler.CompleteAssemblySession(Guid.Parse(workItemId), token);            
        }
        public ActionResult LandingPage()
        {
            // Landing page for the user when they finish the interview; this endpoint is used in InterviewOptions, on the interview page.
            return View();
        }      }
}

AssemblySessionHandler.cs

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
namespace AdvanceExampleApplication
{
    public static class AssemblySessionHandler
    {
        public static async Task<assemblysessiondto> BeginAssemblySession(string token)
        {
            // ID of a work item for which you want to create the assembly session;
            // it must not have an in-progress assembly session
            var workItemId = Guid.Parse("a1e0e795-5a51-44f5-8fe2-e85a61dbf3c2");
            // Create the request
            var request = CreateHttpRequestMessage(workItemId);
            // Send the begin assembly session request to Advance
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                var response = await client.SendAsync(request);
                return JsonConvert.DeserializeObject<assemblysessiondto>(await response.Content.ReadAsStringAsync());
            }
        }
        private static HttpRequestMessage CreateHttpRequestMessage(Guid workItemId)
        {
            var assemblySessionId = Guid.NewGuid();
            var assemblySessionUrl = $"https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/WorkItems/{workItemId}/Versions/{assemblySessionId}";
            var assemblySessionUrl = $"https://yourtenancy.hotdocsadvance.com/api/rest/v1.1/WorkItems/{workItemId}/Versions/{assemblySessionId}";
            var body = new
            {
                forceCreate = true,
                answerXml = string.Empty
            };
            return new HttpRequestMessage
            {
                RequestUri = new Uri(assemblySessionUrl),
                Method = HttpMethod.Put,
                Content = new StringContent(JsonConvert.SerializeObject(body), Encoding.UTF8, "application/json")
            };
        }
    }
}

AssemblySessionDto.cs

namespace AdvanceExampleApplication
{
    public class AssemblySessionDto
    {
        public string InterviewJsUrl { get; set; }
        public string HdaSessionId { get; set; }
        public string CoreSessionId { get; set; }
        public string ServiceMetadataUrl { get; set; }
    }
}

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>

LandingPage.cshtml

<h2>Assembly Complete!</h2>