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:

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.

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.

You can track the progress of your work item from creation to completion using work item 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}

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 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 and is limited to 64 characters.
description String Request body   No

A friendly description for the work item.
workGroupId Guid Request body   Yes The ID for an existing work group.
templatePackageIds Guid Request body   Yes An array of one or more template packages that exist in the work group specified by the workGroupId parameter. The IDs supplied must be:
  • Activated; and
  • Assigned to the work group specified above
The live version of each 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.
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.
useDefaultAnswers Boolean Request body No If set to True, the work item will use the work group's default answer set when no answerXml is provided.

Examples

Example Request URL

https://yourtenancy.yourorganization.com/HdaApi/rest/v2.0/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",

    "templatePackageIds": ["0ef6a9be-b007-4d7d-83f1-9d56f931cd0f", "0ef6a9be-b007-4d7d-83f1-9d56f931cf3w"],

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

 

    "isPrivateToOwner": true,

    "useDefaultAnswers": true

}

Example Response

Status: 200 OK

Next Steps

Once you have a work item, you can: