Creating a Work Item (via API)

The Create work item API method enables you to create a work item in an existing work group and pre-populate the work item with answer data.

Prerequisites

Before making a 'create work item' 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

Overview

The 'create work item' 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 provide users with a new work item that is pre-populated with a set of answers sourced from another system. Users can then modify the answer data in the work item according to their needs. In the method call, you supply answer data in the form of HotDocs Answer XML.

Work items created using the API are marked with a 'New' icon in the Advance UI. This tells users that the work item has been created but its answers are not yet updated.

Validating the HotDocs Answer Set XML

Authentication

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

API Documentation

Request

Request URL

Headers

Parameters

Examples

Example Request URL

https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/WorkItems/2d9f3d10-6fdb-494f-9929-955515c6f114

Example Request JSON

"answerXml": "<AnswerSet title='' version='1.1' useMangledNames='false'><Answer name='CompanyName'><TextValue>ExampleCorp</TextValue></Answer></AnswerSet>",

Example Response

Code Example


using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace HotDocsAdvanceApiExamples
{
    public class WorkItemRequest
    {
        public async Task<HttpStatusCode> CreateWorkItem(string token)
        {
            // Create the 'create work item' request  
            var workItemId = Guid.NewGuid();
            var request = CreateHttpRequestMessage(workItemId);

            //Send create user request to Advance
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                var response = await client.SendAsync(request);
                return response.StatusCode;
            }
        }

        private HttpRequestMessage CreateHttpRequestMessage(Guid workItemId)
        {
            // Create the request for the 'create work item' API endpoint
            var createWorkItemUrl = string.Format("https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/WorkItems/{0}", workItemId);


            return new HttpRequestMessage
            {
                RequestUri = new Uri(createWorkItemUrl),
                Method = HttpMethod.Put,
                Content = GetRequestContent()
            };
        }

        private StringContent GetRequestContent()
        {
            // Generate the JSON request body required by the 'create user' method
            var json = "{\"name\": \"Example Contract A\",\"templatePackageId\": \"03000000-0000-0000-0000-000000000003\",\"workGroupId\": \"09000000-0000-0000-0000-000000000001\",\"answerXml\": \"<answerset title="\'\'" version="\'1.1\'" usemanglednames="\'false\'"><answer name="\'ClientName\'"><textvalue>Bob Sherunkle</textvalue></answer></answerset>\",\"assembleImmediately\": true, \"completeAssemblySession\": false, \"isPrivateToOwner\": true}";
            return new StringContent(json, Encoding.UTF8, "application/json");
        }
    }
}

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]

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.
id	Guid	URL	Yes	A new Guid to identify the work item. The ID cannot be the same as that of an existing work item.
name	String	Request body	Yes	A unique name for the work item. The name cannot be the same as that of an existing work item.
description	String	Request body	No	A friendly description for the work item.
workGroupId	Guid	Request body	Yes	The ID for an existing work group.
templatePackageId	Guid	Request body	Yes	The ID for an existing template package. The template package must be: Activated; and Assigned to the work group specified above The live version of the template package is always used to create the work item.
answerXml	string	Request body	No	A HotDocs answer set, containing an initial set of answer data to be used by the assembly session. This is a string of XML that validates against the HotDocs answer set schema. You can omit this parameter if you do not want to pre-populate the work item with answer data.
assembleImmediately	Boolean	Request body	No	Determines if Advance runs an assembly session to produce completed documents as soon as the new work item is created. True – Advance generates assembled documents for the work item as soon as it is created False – the work item is not created with assembled documents; to generate documents, either a user must open and complete an interview through the Advance UI or you can assemble documents using the API
completeAssemblySession	Boolean	Request body	No	Set the status of assembly session for the work item to Complete. If a user opens the work item in the UI, they will not be prompted to open the interview (i.e. with the "You have an unfinished interview in progress" message).
isPrivateToOwner	Boolean	Request body	No	Set the privacy status of the new work item. Either: True – the work item is Private and can only be accessed by the owner; or False – the work item is Public and is accessible to other users that have access to the specified work group, set by the workGroupId parameter.

Creating a Work Item