Create a New Work Item Version

The create new work item version API method enables you to create a new version for a work item.

Prerequisites

Before making a 'create new work item version' 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 for which you are creating a new work item version:

A work item

Overview

The 'create new work item version' API method is a command method. The API client invoking this method must have either a command or a root scope.

This method is useful when you want to display a HotDocs interview or assemble documents from within your own application.

Validating the HotDocs Answer Set XML

When sending HotDocs answer set XML in a begin assembly session request, you must first validate the answer set against the HotDocs answer Set schema.

You can track the progress of your work item version from creation to completion using work item version statuses.

Authentication

See Authentication for more information about authenticating requests to the Advance API.

API Documentation

You can view the latest reference documentation for the Advance API at https://yourorganization.com/HdaApi/rest/documentation/index.html, where yourorganization.com is the domain under which your Advance deployment is located.

Request

Request URL

PUT https://{tenancymoniker}.{domain}/HdaApi/rest/v2.0/WorkItems/{workItemId}/Versions/{versionId}

Headers

Key	Required	Description	Example value
Authorization	Yes	The Authorization header for the request. Uses the access token retrieved (see Prerequisites section above for more information).	Bearer [access token]

Parameters

Name	Type	Location	Required	Description
tenancymoniker	String	URL	Yes	The tenancy moniker for the tenancy in which you want to create the new work item.
domain	String	URL	Yes	Your domain. For example, yourorganization.com.
workItemId	Guid	URL	Yes	The Guid for an existing work item.
versionId	Guid	URL	Yes	A new Guid, used to identify the assembly session in Advance.
templatePackageId	Guid	Body	Yes	The ID of a single template package associated with a work item.

Examples

Example Request URL

https://tenancy1.yourorganization.com/HdaApi/rest/v2.0/WorkItems/2d9f3d10-6fdb-494f-9929-955515c6f114/Versions/54210021-e86e-429d-ab1b-cc8e101cf7e1

Example Request JSON

{"templatePackageId"; "3d9f3d10-6fdb-494f-9929-955515c6f1945"}

Example Response

Status: 201 OK

Body:

{

"versionId": "32b701fa-fh73-4d58-a70c-71e27c277df9",

"coreAssemblySessionId": "mntekqe11s9w3rhe7u3rfdxws3ur1fhdpo68j74rpw6ofmkcoyn9ene3dzz84bnrh7qcy35geon855o7drgsahi3t9ba8yhg",

"urls": {

"interviewJsUrl": "https://yourorganization.com/AssemblyService/scripts/interview.js",

"serviceMetadataUrl": "https://yourorganization.com/AssemblyService/ipi/session/mntekqe11s9w3rhe7u3rfdxws3ur1fhdpo68j74rpw6ofmkcoyn9ene3dzz84bnrh7qcy35geon855o7drgsahi3t9ba8yhg"

"workItemUrl": "",

}

Using the Response Data

The begin assembly session method provides the following data in its response:

Name	Type	Description	Example data
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.	32b701fa-fh73-4d58-a70c-71e27c277df9
coreAssemblySessionId	Guid	Identifies the assembly session within the Core Assembly Service. You will need this ID when using HD$.AttachSession to display the interview in a user's browser.	mntekqe11s9w3rhe7u3rfdxws3ur1fhdpo68j74rpw6ofmkcoyn9ene3dzz84bnrh7qcy35geon855o7drgsahi3t9ba8yhg
interviewJsUrl	String	The URL from which to load the interview.js file. You must include this in the page on which the interview is displayed.	https://yourorganization.com/AssemblyService/scripts/interview.js
serviceMetadataUrl	String	The URL for the current assembly session in the Core Assembly Service.	https://yourorganization.com/AssemblyService/ipi/session/mntekqe11s9w3rhe7u3rfdxws3ur1fhdpo68j74rpw6ofmkcoyn9ene3dzz84bnrh7qcy35geon855o7drgsahi3t9ba8yhg
workItemUrk	String	The URL for the work item.	https://yourorganization.com/WorkItems/{guid}

You will require this data when displaying an interview.

Code Example

C#

Note: this code example assumes that you are using .Net Framework 4.6 and a new ASP.NET Web Application project. You will build upon this project in the later code examples for displaying an interview and completing an assembly session.

HomeController.cs

using System.Web.Mvc;
using System.Threading.Tasks;
namespace AdvanceExampleApplication.Controllers
{
    public class HomeController : Controller
    {
        public async Task<ActionResult> Index()
        {
            // You should have already implemented the 'ResourceOwnerAuthorization' method in the 'Getting an Access Token using the Resource Owner flow' topic.
            var token = await ResourceOwnerAuthorization.GetResourceOwnerToken();
            var assemblySessionData = await AssemblySessionHandler.BeginAssemblySession(token);
            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://tenancy1.yourorganization.com/HdaApi/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; }
    }
}