Get Tasks (Historic) (POST)

Queries for historic tasks that fulfill the given parameters. This method is slightly more powerful than the Get Tasks (Historic) method because it allows filtering by multiple process or task variables of types String, Number or Boolean. The size of the result set can be retrieved by using the Get Task Count (POST) method.

Method

POST /history/task

Parameters

Query Parameters

Name Description
firstResult Pagination of results. Specifies the index of the first result to return.
maxResults Pagination of results. Specifies the maximum number of results to return. Will return less results, if there are no more results left.

Request Body

A JSON object with the following properties:

Name Description
taskId Filter by task id.
taskParentTaskId Filter by parent task id.
processInstanceId Filter by process instance id.
processInstanceBusinessKey Filter by process instance business key.
processInstanceBusinessKeyIn Filter by process instances with one of the give business keys. The keys need to be in a comma-separated list.
processInstanceBusinessKeyLike Filter by process instance business key that has the parameter value as a substring.
executionId Filter by the id of the execution that executed the task.
processDefinitionId Filter by process definition id.
processDefinitionKey Restrict to tasks that belong to a process definition with the given key.
processDefinitionName Restrict to tasks that belong to a process definition with the given name.
caseInstanceId Filter by case instance id.
caseExecutionId Filter by the id of the case execution that executed the task.
caseDefinitionId Filter by case definition id.
caseDefinitionKey Restrict to tasks that belong to a case definition with the given key.
caseDefinitionName Restrict to tasks that belong to a case definition with the given name.
activityInstanceIdIn Only include tasks which belong to one of the passed and comma-separated activity instance ids.
taskName Restrict to tasks that have the given name.
taskNameLike Restrict to tasks that have a name with the given parameter value as substring.
taskDescription Restrict to tasks that have the given description.
taskDescriptionLike Restrict to tasks that have a description that has the parameter value as a substring.
taskDefinitionKey Restrict to tasks that have the given key.
taskDefinitionKeyIn Restrict to tasks that have one of the given key.
taskDeleteReason Restrict to tasks that have the given delete reason.
taskDeleteReasonLike Restrict to tasks that have a delete reason that has the parameter value as a substring.
taskAssignee Restrict to tasks that the given user is assigned to.
taskAssigneeLike Restrict to tasks that are assigned to users with the parameter value as a substring.
taskOwner Restrict to tasks that the given user owns.
taskOwnerLike Restrict to tasks that are owned by users with the parameter value as a substring.
taskPriority Restrict to tasks that have the given priority.
assigned If set to true, restricts the query to all tasks that are assigned.
unassigned If set to true, restricts the query to all tasks that are unassigned.
finished Only include finished tasks. Value may only be true, as false is the default behavior.
unfinished Only include unfinished tasks. Value may only be true, as false is the default behavior.
processFinished Only include tasks of finished processes. Value may only be true, as false is the default behavior.
processUnfinished Only include tasks of unfinished processes. Value may only be true, as false is the default behavior.
taskDueDate Restrict to tasks that are due on the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
taskDueDateBefore Restrict to tasks that are due before the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
taskDueDateAfter Restrict to tasks that are due after the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
withoutTaskDueDate Only include tasks which have no due date. Value may only be true, as false is the default behavior.
taskFollowUpDate Restrict to tasks that have a followUp date on the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
taskFollowUpDateBefore Restrict to tasks that have a followUp date before the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
taskFollowUpDateAfter Restrict to tasks that have a followUp date after the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
startedBefore Restrict to tasks that were started before the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
startedAfter Restrict to tasks that were started after the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
finishedBefore Restrict to tasks that were finished before the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
finishedAfter Restrict to tasks that were finished after the given date. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.000+0200.
tenantIdIn Filter by a list of tenant ids. A task instance must have one of the given tenant ids. Must be a JSON array of Strings.
withoutTenantId Only include historic task instances that belong to no tenant. Value may only be true, as false is the default behavior.
taskVariables A JSON array to only include tasks that have variables with certain values.
The array consists of JSON objects with three properties name, operator and value. name is the variable name, operator is the comparison operator to be used and value the variable value.
value may be of type String, Number or Boolean.

Valid operator values are: eq - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like.
processVariables A JSON array to only include tasks that belong to a process instance with variables with certain values.
The array consists of JSON objects with three properties name, operator and value. name is the variable name, operator is the comparison operator to be used and value the variable value.
value may be of type String, Number or Boolean.

Valid operator values are: eq - equal to; neq - not equal to; gt - greater than; gteq - greater than or equal to; lt - lower than; lteq - lower than or equal to; like;notLike.
variableNamesIgnoreCase Match the variable name provided in taskVariables and processVariables case-insensitively. If set to true variableName and variablename are treated as equal.
variableValuesIgnoreCase Match the variable value provided in taskVariables and processVariables case-insensitively. If set to true variableValue and variablevalue are treated as equal.
taskInvolvedUser Restrict to tasks with a historic identity link to the given user.
taskInvolvedGroup Restrict to tasks with a historic identity link to the given group.
taskHadCandidateUser Restrict to tasks with a historic identity link to the given candidate user.
taskHadCandidateGroup Restrict to tasks with a historic identity link to the given candidate group.
withCandidateGroups Only include tasks which have a candidate group. Value may only be true, as false is the default behavior.
withoutCandidateGroups Only include tasks which have no candidate group. Value may only be true, as false is the default behavior.
sorting A JSON array of criteria to sort the result by. Each element of the array is a JSON object that specifies one ordering. The position in the array identifies the rank of an ordering, i.e., whether it is primary, secondary, etc. The ordering objects have the following properties:
Name Description
sortBy Mandatory. Sort the results lexicographically by a given criterion. Valid values are taskId, activityInstanceId, processDefinitionId, processInstanceId, executionId, duration, endTime, startTime, taskName, taskDescription, assignee, owner, dueDate, followUpDate, deleteReason, taskDefinitionKey, priority, caseDefinitionId, caseInstanceId, and caseExecutionId and tenantId.
sortOrder Mandatory. Sort the results in a given order. Values may be asc for ascending order or desc for descending order.

* For further information, please see the documentation.

Result

A JSON array of historic task objects. Each historic task object has the following properties:

Name Value Description
id String The task id.
processDefinitionKey String The key of the process definition the task belongs to.
processDefinitionId String The id of the process definition the task belongs to.
processInstanceId String The id of the process instance the task belongs to.
executionId String The id of the execution the task belongs to.
caseDefinitionKey String The key of the case definition the task belongs to.
caseDefinitionId String The id of the case definition the task belongs to.
caseInstanceId String The id of the case instance the task belongs to.
caseExecutionId String The id of the case execution the task belongs to.
activityInstanceId String The id of the activity that this object is an instance of.
name String The task name.
description String The task's description.
deleteReason String The task's delete reason.
owner String The owner's id.
assignee String The assignee's id.
startTime String The time the task was started. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
endTime String The time the task ended. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
duration Number The time the task took to finish (in milliseconds).
taskDefinitionKey String The task's key.
priority Number The task's priority.
due String The task's due date. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
parentTaskId String The id of the parent task, if this task is a subtask.
followUp String The follow-up date for the task. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
tenantId String The tenant id of the task instance.
removalTime String The time after which the task should be removed by the History Cleanup job. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
rootProcessInstanceId String The process instance id of the root process instance that initiated the process containing this task.
orQueries A JSON array which contains at least one OR query JSON Object. All previously listed filter criteria can be used inside of this JSON object. See the user guide for more information about OR queries.

The following properties are not supported: sorting, withCandidateGroups, withoutCandidateGroups.

* For further information, please see the documentation.

Response Codes

Code Media type Description
200 application/json Request successful.
400 application/json Returned if some of the query parameters are invalid, for example if a sortOrder parameter is supplied, but no sortBy. See the Introduction for the error response format.

Example

Request

POST /history/task

Request Body:

{"taskVariables":
    [{"name": "varName",
    "value": "varValue",
    "operator": "eq"
    },
    {"name": "anotherVarName",
    "value": 30,
    "operator": "neq"}],
"priority":10,
"sorting":
  [{"sortBy": "priority",
  "sortOrder": "asc"
  },
  {"sortBy": "duration",
  "sortOrder": "desc"
  }]
}

Response

[{"id":"anId",
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "executionId":"anExecution",
 "caseDefinitionId":"aCaseDefId",
 "caseInstanceId":"aCaseInstId",
 "caseExecutionId":"aCaseExecution",
 "activityInstanceId": "anActInstId",
 "name":"aName",
 "description":"aDescription",
 "deleteReason": "aDeleteReason",
 "owner":"anOwner",
 "assignee":"anAssignee",
 "startTime":"2013-01-23T13:42:42.000+0200",
 "endTime":"2013-01-23T13:45:42.000+0200",
 "duration": 2000,
 "taskDefinitionKey":"aTaskDefinitionKey",
 "priority":10,
 "due":"2013-01-23T13:49:42.000+0200",
 "parentTaskId":"aParentId",
 "followUp:":"2013-01-23T13:44:42.000+0200",
 "tenantId":null,
 "removalTime": "2018-02-10T14:33:19.000+0200",
 "rootProcessInstanceId": "aRootProcessInstanceId"
}]

On this Page: