Using the New Work Item Version Complete Webhook to Receive Notifications

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
  • URLhttps://localhost/WebhookExampleApp/NewWorkItemVersionComplete
  • EventNew Work Item Version Complete (sends event data when a user completes a new work item version)
  • Authentication methodexampleHMAC
  • Active StatusActive
  • Untrusted SSL certificatesNo

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.

Authentication method

The token specified in the webhook is passed in the request sent to your endpoint, in the Authorization header. HMAC authentication is the recommended authentication method to authenticate requests from Advance to your own application.

See also Authentication Types

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/HdaApi/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.

JSON Response Data Size

The size of JSON response data is limited to 200Kb by default. If your response data is often larger than this, you can change the default allowable size by adding the ExternalAnswersMaxBytes setting to your HdaInstallerSettings.json file. In between the "SiteSettings": braces add the following setting, replace 200 with the number of bytes you require:

"ApiSiteSettings.AppSettings.ExternalAnswersMaxBytes": 200,

This setting can be added before the installation of Advance. If you have already installed Advance, you can add this setting to the installer settings file and run the Hdainstaller.exe setting gu installer command. This uses the updated installer settings file to update the configuration of your installed version of Advance.

If other settings are listed below, ensure the comma at the end of the ExternalAnswersMaxBytes setting is included. If you add the setting below all other settings, then a comma is not required.

Please note that large JSON response data files can affect interview performance.

This setting affects custom interview and load interview event webhooks.

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.