How To Topic

Receiving Data When the Interview is Complete

The New Work Item Version Complete webhook enables your web application to receive a notification when a user completes a work item in Advance.

Prerequisites

• Creating a Webhook – before you can receive data from a webhook, you must have an existing webhook.

Overview

Webhooks configured to use the NewWorkItemVersionComplete event run when a user in Advance completes a new version of a work item, usually when a user finishes a work item's interview. Finishing the interview typically results in Advance producing a new set of documents for the work item. When the new work item version is complete, Advance sends a set of event data to the endpoint you specified when creating the webhook.

This event is useful as it notifies you when a new set of documents is available for a work item. For example, this enables you to download the completed documents and send them to another system (e.g. a document management system).

Your Existing Webhook

This example supposes that you have an existing webhook with the following properties:

• Name – WebhookExample01
• URL – https://localhost/WebhookExampleApp/NewWorkItemVersionComplete
• Event – New Work Item Version Complete (sends event data when a user completes a new work item version)
• Authentication method – exampleHMAC
• Active Status – Active
• Untrusted SSL certificates – No

The URL for the webhook should point at the endpoint we are going to create in our example application. In this case, the application is named WebhookExampleApp, with an endpoint named NewWorkItemVersion. You can go back and edit the URL for the webhook after creating the example application, if necessary.

Example JSON Response Data

The following JSON data is an example of the response expected from a New Work Item Version Complete event.

{
    "eventId":"d395c096-5ca0-4225-8542-6ba313b93c96",
    "eventType":"NewWorkItemVersionComplete",
    "createdDate":"2018-10-31T13:13:13.8096177Z",
    "createdBy":{
        "id":"c955a8fa-cd7a-413e-811b-fe8618121cba",
        "loginName":"john.smith@example.com",
        "accountType":"UserAccount"    },
    "data":{
        "workItemId":"af8cee70-e59d-4a00-8b97-aa771f8b6ab9",
        "workItemVersionId":"20a06ea2-e6b3-4b04-bbeb-93913d4db9e4",
        "workItemName":"WI001",
        "documents":[{
            "id":"f8315acd-a2fa-5366-bca0-813f47c4b81c",
            "name":"Example Contract",
            "url":"https://advance.yourdomain.com/HdaApiyourtenancy.hotdocsadvance.com/api/rest/v1.1/workitems/af8cee70-e59d-4a00-8b97-aa771f8b6ab9/documents/f8315acd-a2fa-5366-bca0-813f47c4b81c/content"        }],
        "templateVersionId":"9767ee0b-5ec1-5903-8c25-0d1428fcc27b",
        "templateVersionName":"Example Contract"    },
    "relativeTimestamp":12
}

In the example you will create several classes to represent this set of data.

Code Example

C#

Note: this code example assumes that you are using .Net Framework 4.6 and a new ASP.NET Web Application project. It also assumes you have completed the Getting an Access Token using the Resource Owner Flow topic and can retrieve an access token.

NewWorkItemVersion.cs

This class represents the data you will receive from the webhook about the new work item version. For simplicity, we will define multiple classes within the same file.

using System;

namespace WebhookExampleApplication
{
    public class NewWorkItemVersion
    {
        public Guid EventId { get; set; }
        public string EventType { get; set; }
        public DateTime CreatedDate { get; set; }
        public User CreatedBy { get; set; }
        public WorkItem Data { get; set; }
        public string RelativeTimeStamp { get; set; }
    }
    public class User
    {
        public Guid Id { get; set; }
        public string LoginName { get; set; }
        public string AccountType { get; set; }
    }
    public class WorkItem
    {
        public Guid WorkItemId { get; set; }
        public Guid WorkItemVersionId { get; set; }
        public string WorkItemName { get; set; }
        public Document[] Documents { get; set; }
    }
    public class Document
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
        public string Url { get; set; }
        public Guid TemplateVersionId { get; set; }
        public string TemplateVersionName { get; set; }
    }
}

HomeController.cs

This class contains the endpoint ("NewWorkItemVersion") to which Advance posts data about the new work item version. When Advance posts the data to the endpoint, it downloads the new documents for the work item.

using System.Web.Mvc;
using System.Threading.Tasks;
namespace WebhookExampleApplication.Controllers
{
    public class HomeController : Controller
    {
        [HttpPost]
        public async Task NewWorkItemVersion(NewWorkItemVersion newWorkItemVersion)
        {
            // Document URLs
            var documentUrls = newWorkItemVersion.Data.Documents;            // Get the access token for making API requests
            // See Getting an Access Token using the Resource Owner Flow for more information.
	var token = await new ResourceOwnerAuthorization().GetResourceOwnerToken();
	// Download documents 
	var downloader = new DocumentsDownloader(); 
	await downloader.DownloadAsync(token, urls);
        }
    }
}

DocumentsDownloader.cs

This class downloads the new documents from the work item.

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
 
namespace WebhookExampleApplication
{
    public class DocumentsDownloader
    {
        public async Task DownloadAsync(string token, Document[] documents)
        {
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                foreach (var document in documents)
                {
                    // Download the document
                    var request = CreateHttpRequestMessage(document.Url);
                    var response = await client.SendAsync(request);
                    await SaveDocument(response);
                }
            }
        }
 
        private HttpRequestMessage CreateHttpRequestMessage(string documentUrl)
        {
            return new HttpRequestMessage
            {
                RequestUri = new Uri(documentUrl),
                Method = HttpMethod.Get
            };
        }
 
        private async Task SaveDocument(HttpResponseMessage response)
        {
            using (Stream output = File.OpenWrite(string.Format(@"C:\temp\{0}.docx", Guid.NewGuid()))) {
                await (await response.Content.ReadAsStreamAsync()).CopyToAsync(output);
                output.Close();
            }
        }
    }
}

Testing your example application

1. In Visual Studio, run your example application.
2. When the application opens in your web browser, make a note of the URL. For example, https://localhost/webhookexampleapplication/
3. Open Advance and look at your webhook; ensure the webhook URL matches the URL of your application (including the endpoint name). For example, https://localhost/webhookexampleapplication/newworkitemversion.
4. In Advance, create a new work item.
5. Once the interview for the work item is complete, you should see an assembled document appear in your C:\temp folder.