How To Topic

Creating a Work Item

The Create work item API method enables you to create a work item in an existing work group. You can choose to 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:

• Getting an access token using the Resource Owner flow
• Getting an access token using the Hybrid flow
• Getting an access token using the Implicit flow

Additionally, you must have the following items in the tenancy in which you are creating the work item

• A work group  – the ID of a work group in your tenancy is required when making the request
• A template package – the ID of a template package uploaded to your tenancy is required when making the request

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 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

When sending HotDocs answer set XML in a create work item request, you must first validate the answer set against the HotDocs answer Set schema.

Authentication

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

API Documentation

Work Item Status

Work items have two statuses:

• Initialized – a work item initialized via the API; if a work item has an 'initialized' status, it has never been accessed by a user
• In-progress – a work item that was:
  • Created through the UI; or
  • Initialized via the API and subsequently updated by a user

An initialized work item always has a status of 'Initialized' until it is updated by a user (for example, by launching the interview). This enables users to identify work items that they have not yet updated.

Work items created through the UI always have an 'in-progress' status.

Request

Request URL

PUT https://{tenancymoniker}.{domain}/HdaApi/rest/v1.1/WorkItems/{id}

PUT https://{tenancymoniker}.hotdocsadvance.com/api/rest/v1.1/WorkItems/{id}

Headers

Parameters

Examples

Example Request URL

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

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

Example Request JSON

{

    "name": "ExampleCorp contract renewal",

    "description": "Updating the contract for ExampleCorp.",

    "workGroupId": "cb97f8d6-04a1-490a-aa09-92af12dfb305",

    "templatePackageId": "0ef6a9be-b007-4d7d-83f1-9d56f931cd0f",

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

    "assembleImmediately": true,

    "completeAssemblySession": false,

    "isPrivateToOwner": true

}

Example Response

Status: 200 OK

Code Example

See Create Work Item Example for further examples.

C#

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);
            var createWorkItemUrl = string.Format("https://yourtenancy.hotdocsadvance.com/api/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");
        }
    }
}