WebSphere Process Server, Version 6.2.0.1 Operating Systems: AIX, HP-UX, Linux, Solaris, Windows, i5/OS, z/OS


Human Task Manager REST Interface - Task Resource - POST Method

Use this method to create a new instance of a human task.

Resource URI

POST /v1/task?{parameters}

Parameters

Required Parameters
NameValue TypeDescription
taskTemplateID string
The ID of the task template from which the new task instance is created.
Optional Parameters
NameValue TypeDescription
mode string
Specifies the mode in which the task instance is created.
ValueDescription
createOnly (default)
Creates the task but does not start the task. This value is not allowed if the parameters relation and parentTaskID are specified.
sync
Use a synchronous operation to start the task. This value is only allowed for invocation tasks, and it is not allowed if the parameters relation and parentTaskID are specified.
async
Use a asynchronous operation to start the task.
relation string
Task relationship - must be specified together with the parentTaskID parameter.
ValueDescription
subTask
The new task is a subtask. This value can only be used when the mode parameter is set to async.
parentTaskID string
Task ID of the parent task - must be specified together with the relation parameter.

Request Content

Human task input (optional). The XML Schema for the claimed task's input, that is, the XML Schema type/element used for the WSDL message part definition, is defined as part of the custom task template definition. Data defined by an XML Schema simple type is wrapped in an XML element provided by this REST interface (see Simple-Typed XML Data).

The default content-type is application/xml.

Response Content

The returned response depends on the specified mode parameter and the outcome of a task that is executed synchronously.

MIME Type: application/json

(1) Human task details are returned if the mode parameter is set to createOnly or async.


+ View Schema
{  "description": "HTM Task", 
   "type": "object",
   "properties":
   {  "activationTime": {"type": "string","format": "date-time",
         "description": "Time the task instance is set into the ready state - this also happens when the task is restarted or when a claim is canceled."
      },
      "applicationDefaultsID": {"type": "string",
         "description": "ID of the application component that specifies the defaults for the task."
      },
      "applicationName": {"type": "string",
         "description": "Name of the application the task is part of."
      },
      "autoDeletionMode": {"type": "string",
         "description": "States whether the task instance is automatically or conditionally deleted when it reaches an end execution state."
      },
      "binaryCustomPropertiesMetadata": {"type": "object", "additionalProperties": {"type": "string"},
         "description": "Metadata for binary custom properties associated with this task."
      },
      "calendarName": {"type": "string",
         "description": "Name of the calendar used, for example, for expiration calculations."
      },
      "completionTime": {"type": "string","format": "date-time",
         "description": "Time when the task instance reached an end state."
      },
      "containmentContextID": {"type": "string",
         "description": "ID of the context which embraces the task instance."
      },
      "contextAuthorizationOfOwner": {"type": "string",
         "description": "Authorization rights of the task owner to the associated context."
      },  
      "customProperties": {"type": "object", "additionalProperties": {"type": "string"},
         "description": "List of custom property names and values."
      },
      "definitionName": {"type": "string",
         "description": "Name of the task definition in the TEL."
      },
      "definitionNamespace": {"type": "string",
         "description": "XML schema namespace of the task definition in the TEL."
      },
      "deletionTime":  {"type": "string", "format": "date-time",
         "description": "Time when the task is deleted."
      },
      "description": {"type": "string",
         "description": "Description of the task."
      },
      "displayName": {"type": "string",
         "description": "Display name of the task."
      },
      "dueTime":  {"type": "string", "format": "date-time",
         "description": "Time when the task is due."
      },
      "durationUntilDeleted": {"type": "string",
         "description": "Duration that the task is kept after it has reached an end state."
      },
      "durationUntilDue": {"type": "string",
         "description": "Duration when the task becomes due."
      },
      "durationUntilExpires": {"type": "string",
         "description": "Duration when the task expires once it is activated."
      },
      "eventHandlerName": {"type": "string",
         "description": "Name of the associated event handler."
      },
      "expirationTime": {"type": "string",
         "description": "Time when the task instance will expire or was due to expire."
      },
      "firstActivationTime": {"type": "string","format": "date-time",
         "description": "Time the task instance is set into the ready state for the first time."
      },
      "followOnTaskID": {"type": "string",
         "description": "ID of the next task instance in a sequence."
      },
      "inputMessageTypeName": {"type": "string", 
         "description": "Name of the input message type. The value has the format {namespace}localname."
      },
      "isAdHoc": {"type": "boolean",
         "description": "States whether the task has been created ad-hoc."
      },
      "isBusinessRelevant": {"type": "boolean",
         "description": "States whether the task is a business relevant or an 'auxiliary' step."
      },
      "isChild": {"type": "boolean",
         "description": "States for standalone tasks whether the task instance runs dependently of its parent or not."
      },
      "isEscalated": {"type": "boolean",
         "description": "States whether an escalation occurred."
      },
      "isInline":  {"type": "boolean",
         "description": "States whether the task is an inline task."
      },
      "isSuspended": {"type": "boolean",
         "description": "States whether the task instance is suspended."
      },
      "isWaitingForSubTask": {"type": "boolean",
         "description": "States whether the task is waiting for the completion of a subtask."
      },
      "jndiNameOfCalendar": {"type": "string",
         "description": "JNDI name of a user-defined calendar."
      },
      "jndiNameOfStaffPluginProvider": {"type": "string",
         "description": "JNDI name of a user-defined people directory configuation."
      },
      "kind": {"type": "string",
         "description": "Kind of the task."
      },
      "lastModificationTime":{"type": "string","format": "date-time",
         "description": "Last time a property of the task instance changed."
      },
      "lastStateChangeTime": {"type": "string","format": "date-time",
         "description": "Last time the state of the task instance changed."
      },
      "name": {"type": "string",
         "description": "Name of the task instance."
      },
      "namespace": {"type": "string",
         "description": "Namespace that categorizes the task instance."
      },
      "originator": {"type": "string",
         "description": "ID of the user that created the task instance or on whose behalf the task instance was created."
      },
      "outputMessageTypeName": {"type": "string",
         "description": "Name of the output message type. The value has the format {namespace}localname."
      },
      "owner": {"type": "string",
         "description": "Owner of the task instance."
      },
      "parentContextID": {"type": "string",
         "description": "ID of the parent context of the task instance."
      },
      "positionInHierarchy": {"type": "string", 
         "description": "Position in a possible task instance hierarchy.",
         "enum":
         [
            "HIERARCHY_POSITION_FOLLOW_ON_TASK",
            "HIERARCHY_POSITION_SUB_TASK",
            "HIERARCHY_POSITION_TOP_TASK"
         ]
      },
      "priority": {"type": "integer",
         "description": "Priority of the task instance."
      },
      "resumptionTime": {"type": "string","format": "date-time",
         "description": "Resumption time of the task instance if the task instance is suspended and is to be resumed automatically."
      },
      "starter": {"type": "string",
         "description": "Starter of the task instance."
      },
      "startTime":  {"type": "string", "format": "date-time",
         "description": "Time when the task was claimed or when an invocation task enters the running state."
      },
      "state": {"type": "string",
         "description": "State of the task instance."
      },
      "substitutionPolicy": {"type": "string",
         "description": "Substitution policy that takes place when people assignments are performed."
      },
      "supportsAutomaticClaim": {"type": "boolean",
         "description": "States whether the task is claimed automatically when it becomes ready."
      },
      "supportsClaimIfSuspended": {"type": "boolean",
         "description": "States whether the task can be claimed even if it is suspended."
      },
      "supportsDelegation": {"type": "boolean",
         "description": "States whether the task supports delegation, for example, by transferring work items."
      },
      "supportsFollowOnTasks": {"type": "boolean",
         "description": "States whether the task supports the creation of follow-on tasks."
      },
      "supportsSubTasks": {"type": "boolean",
         "description": "States whether the task supports the creation of subtasks."
      },
      "taskTemplateID": {"type": "string",
         "description": "ID of the task template this instance is derived from."
      },
      "taskTemplateName": {"type": "string",
         "description": "Name of the task template this instance is derived from."
      },
      "tkiid": {"type": "string",
         "description": "Task instance ID."
      },
      "topLevelTaskID": {"type": "string",
         "description": "ID of the topmost task instance in a hierarchy of tasks."
      },
      "type": {"type": "string",
         "description": "Type of the task."
      }
   }
}

MIME Type: application/xml

(2) The human task output is returned if the task is an invocation task, the mode parameter is set to sync, and the task returned with output. The XML Schema for the task output, that is, the XML Schema type/element used for the WSDL message part definition, is defined as part of the custom task template definition. Data defined by an XML Schema simple type is wrapped in an XML element provided by this REST interface (see Simple-Typed XML Data).

MIME Type: application/xml

(3) The human task fault is returned if the task is an invocation task, the mode parameter is set to sync, and the task returned with a fault. An XML wrapper element is returned containing the WSDL fault name and the fault data. The XML Schema for the task fault data, that is, the XML Schema type/element used for the WSDL message part definition, is defined as part of the custom task template definition. Data defined by an XML Schema simple type is wrapped in an XML element provided by this REST interface (see Simple-Typed XML Data).


+ View Schema
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://www.ibm.com/xmlns/prod/websphere/bpm/rest/htm/v1/taskFault" 
   xmlns="http://www.ibm.com/xmlns/prod/websphere/bpm/rest/htm/v1/taskFault" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   elementFormDefault="qualified" 
   attributeFormDefault="unqualified">
   <!--
      HTM Task Fault
   -->
   <xsd:element name="taskFault" type="tTaskFault"/>
   <xsd:complexType name="tTaskFault">
      <xsd:sequence>
         <xsd:element name="faultName" type="xsd:QName"/>
         <xsd:element name="faultData" type="xsd:anyType" nillable="true"/>
      </xsd:sequence>
   </xsd:complexType>
</xsd:schema>

Error Response Content

Detailed error information.

The default content-type is application/json.

MIME Type: application/json


+ View Schema
{  "description": "HTM Error Response", 
   "type": "object",
   "properties":
   {  "errorNumber": {"type": "string",
         "description": "Message ID of the exception."
      },
      "errorMessage": {"type": "string",
         "description": "Message text of the exception."
      },
      "programmersDetails": {"type": "object", "optional": true,
         "description":"Additional, exception details, for example, a stack trace."
      }
   }
} 

Status Codes

The method returns one of the following status codes:
CodeDescription
200 OK
Successful completion (if mode is set to sync).
201 Created
Successful completion (if mode is set to createOnly or async).
400 Bad RequestThe parameters are not valid or they are missing.
401 UnauthorizedThe caller is not authorized for this request.
409 Conflict
The specified task template may be in a stopped state. If this is a request for creating a subtask, the parent task may not be in the claimed state.
500 Internal Server ErrorA severe problem has occurred, programmer's details are provided.

Change History

The following changes have been applied to this method:
ReleaseDescription
6.2
The returned human task details object contains new properties:
  • "binaryCustomPropertiesMetadata"
  • "deletionTime"
  • "isChild"

Available Since

6.1.2

Parent Topic: Task Resource