Queries for tasks that fulfill a given filter. This method is slightly more powerful than the Get Tasks 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 /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	Restrict to task with the given id.
taskIdIn	Restrict to tasks with any of the given ids.
processInstanceId	Restrict to tasks that belong to process instances with the given id.
processInstanceIdIn	Restrict to tasks that belong to process instances with the given ids.
processInstanceBusinessKey	Restrict to tasks that belong to process instances with the given business key.
processInstanceBusinessKeyExpression	Restrict to tasks that belong to process instances with the given business key which is described by an expression. See the user guide for more information on available functions.
processInstanceBusinessKeyIn	Restrict to tasks that belong to process instances with one of the give business keys. The keys need to be in an array.
processInstanceBusinessKeyLike	Restrict to tasks that have a process instance business key that has the parameter value as a substring.
processInstanceBusinessKeyLikeExpression	Restrict to tasks that have a process instance business key that has the parameter value as a substring and is described by an expression. See the user guide for more information on available functions.
processDefinitionId	Restrict to tasks that belong to a process definition with the given id.
processDefinitionKey	Restrict to tasks that belong to a process definition with the given key.
processDefinitionKeyIn	Restrict to tasks that belong to a process definition with one of the given keys. The keys need to be in a comma-separated list.
processDefinitionName	Restrict to tasks that belong to a process definition with the given name.
processDefinitionNameLike	Restrict to tasks that have a process definition name that has the parameter value as a substring.
executionId	Restrict to tasks that belong to an execution with the given id.
caseInstanceId	Restrict to tasks that belong to case instances with the given id.
caseInstanceBusinessKey	Restrict to tasks that belong to case instances with the given business key.
caseInstanceBusinessKeyLike	Restrict to tasks that have a case instance business key that has the parameter value as a substring.
caseDefinitionId	Restrict to tasks that belong to a case definition with the given 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.
caseDefinitionNameLike	Restrict to tasks that have a case definition name that has the parameter value as a substring.
caseExecutionId	Restrict to tasks that belong to a case execution with the given id.
activityInstanceIdIn	Only include tasks which belong to one of the passed activity instance ids.
tenantIdIn	Restrict to tasks that belong to one of the given tenant ids. The ids need to be in a comma-separated list.
withoutTenantId	Only include tasks which belong to no tenant. Value may only be true, as false is the default behavior.
assignee	Restrict to tasks that the given user is assigned to.
assigneeExpression	Restrict to tasks that the user described by the given expression is assigned to. See the user guide for more information on available functions.
assigneeLike	Restrict to tasks that have an assignee that has the parameter value as a substring.
assigneeLikeExpression	Restrict to tasks that have an assignee that has the parameter value described by the given expression as a substring. See the user guide for more information on available functions.
assigneeIn	Only include tasks which are assigned to one of the user ids passed in the array
assigneeNotIn	Only include tasks which are not assigned to one of the user ids passed in the array.
owner	Restrict to tasks that the given user owns.
ownerExpression	Restrict to tasks that the user described by the given expression owns. See the user guide for more information on available functions.
candidateGroup	Only include tasks that are offered to the given group.
candidateGroupExpression	Only include tasks that are offered to the group described by the given expression. See the user guide for more information on available functions.
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.
withCandidateUsers	Only include tasks which have a candidate user. Value may only be true, as false is the default behavior.
withoutCandidateUsers	Only include tasks which have no candidate user. Value may only be true, as false is the default behavior.
candidateUser	Only include tasks that are offered to the given user or to one of his groups.
candidateUserExpression	Only include tasks that are offered to the user described by the given expression. See the user guide for more information on available functions.
includeAssignedTasks	Also include tasks that are assigned to users in candidate queries. Default is to only include tasks that are not assigned to any user if you query by candidate user or group(s).
involvedUser	Only include tasks that the given user is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee).
involvedUserExpression	Only include tasks that the user described by the given expression is involved in. A user is involved in a task if an identity link exists between task and user (e.g., the user is the assignee). See the user guide for more information on available functions.
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.
taskDefinitionKey	Restrict to tasks that have the given key.
taskDefinitionKeyIn	Restrict to tasks that have one of the given keys. The keys need to be in a comma-separated list.
taskDefinitionKeyLike	Restrict to tasks that have a key that has the parameter value as a substring.
name	Restrict to tasks that have the given name.
nameNotEqual	Restrict to tasks that do not have the given name.
nameLike	Restrict to tasks that have a name with the given parameter value as substring.
nameNotLike	Restrict to tasks that do not have a name with the given parameter value as substring.
description	Restrict to tasks that have the given description.
descriptionLike	Restrict to tasks that have a description that has the parameter value as a substring.
priority	Restrict to tasks that have the given priority.
maxPriority	Restrict to tasks that have a lower or equal priority.
minPriority	Restrict to tasks that have a higher or equal priority.
dueDate	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.234+0200.
dueDateExpression	Restrict to tasks that are due on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueAfter	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.453+0200.
dueAfterExpression	Restrict to tasks that are due after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
dueBefore	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.667+0200.
dueBeforeExpression	Restrict to tasks that are due before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
withoutDueDate	Only include tasks which have no due date. Value may only be true, as false is the default behavior.
followUpDate	Restrict to tasks that have a followUp date on the given date. By defalut*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.384+0200.
followUpDateExpression	Restrict to tasks that have a followUp date on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpAfter	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.343+0200.
followUpAfterExpression	Restrict to tasks that have a followUp date after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBefore	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.736+0200.
followUpBeforeExpression	Restrict to tasks that have a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistent	Restrict to tasks that have no followUp date or a followUp date before the given date. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
followUpBeforeOrNotExistentExpression	Restrict to tasks that have no followUp date or a followUp date before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdOn	Restrict to tasks that were created 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.038+0200.
createdOnExpression	Restrict to tasks that were created on the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdAfter	Restrict to tasks that were created 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.654+0200.
createdAfterExpression	Restrict to tasks that were created after the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
createdBefore	Restrict to tasks that were created before the given date. The date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.324+0200.
createdBeforeExpression	Restrict to tasks that were created before the date described by the given expression. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
updatedAfter	Restrict to tasks that were updated after the given date. Every action that fires a task update event is considered as updating the task. By default*, the given date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.332+0200.
updatedAfterExpression	Restrict to tasks that were updated after the date described by the given expression. Every action that fires a task update event is considered as updating the task. See the user guide for more information on available functions. The expression must evaluate to a java.util.Date or org.joda.time.DateTime object.
delegationState	Restrict to tasks that are in the given delegation state. Valid values are PENDING and RESOLVED.
candidateGroups	Restrict to tasks that are offered to any of the given candidate groups. Takes a JSON array of group names, so for example ["developers", "support", "sales"].
candidateGroupsExpression	Restrict to tasks that are offered to any of the candidate groups described by the given expression. See the user guide for more information on available functions. The expression must evaluate to java.util.List of Strings.
active	Only include active tasks. Value may only be true, as false is the default behavior.
suspended	Only include suspended tasks. 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.
caseInstanceVariables	A JSON array to only include tasks that belong to a case 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.
variableNamesIgnoreCase	Match all variable names in this query case-insensitively. If set to true variableName and variablename are treated as equal.
variableValuesIgnoreCase	Match all variable values in this query case-insensitively. If set to true variableValue and variablevalue are treated as equal.
parentTaskId	Restrict query to all tasks that are sub tasks of the given task. Takes a task id.
orQueries	A JSON array of nested task queries with OR semantics. A task matches a nested query if it fulfills at least one of the query's predicates. With multiple nested queries, a task must fulfill at least one predicate of each query (Conjunctive Normal Form). All task query properties can be used except for: sorting, withCandidateGroups, withoutCandidateGroups, withCandidateUsers, withoutCandidateUsers See the user guide for more information about OR queries.
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 instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, lastUpdated, description, id, name, nameCaseInsensitive, priority, processVariable, executionVariable, taskVariable, caseExecutionVariable, and caseInstanceVariable. sortOrder Mandatory. Sort the results in a given order. Values may be asc for ascending order or desc for descending order. parameters Mandatory when sortBy is either processVariable, executionVariable, taskVariable, caseExecutionVariable, or caseInstanceVariable. Must be a JSON object with the properties variable and type where variable is a variable name and type is the name of a variable value type.

* For further information, please see the documentation.

Result

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

Name	Type	Description
id	String	The task id.
name	String	The task name.
assignee	String	The assignee's id.
owner	String	The owner's id.
created	String	The date the task was created on. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
due	String	The task's due date. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
followUp	String	The follow-up date for the task. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ.
lastUpdated	String	The date/time when the task was last updated. Default format* yyyy-MM-dd'T'HH:mm:ss.SSSZ. Every action that fires a task update event is considered as an update to the task. Has the value null if the task was never updated.
delegationState	String	The task's delegation state. Possible values are PENDING and RESOLVED
description	String	The task's description.
executionId	String	The id of the execution the task belongs to.
parentTaskId	String	The id the parent task, if this task is a subtask.
priority	Number	The task's priority.
processDefinitionId	String	The id of the process definition the task belongs to.
processInstanceId	String	The id of the process instance the task belongs to.
caseExecutionId	String	The id of the case execution 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.
taskDefinitionKey	String	The task's key.
suspended	Boolean	Whether the task belongs to a process instance that is suspended.
formKey	String	If not null, the form key for the task.
camundaFormRef	String	If not null, the form binding for the Camunda Form with the following properties. Name Type Description key String The key of the linked Camunda Form. binding String The binding type. Can be one of latest, deployment or version. version Integer The concrete version of the linked Camunda Form. Only non-null when binding is version.
tenantId	String	If not null, the tenant id for the task.

* 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, or if an invalid operator for variable comparison is used. See the Introduction for the error response format.

Example

Request

POST /task

Request Body:

{"taskVariables":
    [{"name": "varName",
    "value": "varValue",
    "operator": "eq"
    },
    {"name": "anotherVarName",
    "value": 30,
    "operator": "neq"}],
"processInstanceBusinessKeyIn": ["aBusinessKey", "anotherBusinessKey"],
"assigneeIn": ["anAssignee", "anotherAssignee"],
"priority":10,
"sorting":
    [{"sortBy": "dueDate",
    "sortOrder": "asc"
    },
    {"sortBy": "processVariable",
    "sortOrder": "desc",
    "parameters": {
      "variable": "orderId",
      "type": "String"
    }}]
}

Response

[{"id":"anId",
 "name":"aName",
 "assignee":"anAssignee",
 "created":"2013-01-23T13:42:42.453+0200",
 "due":"2013-01-23T13:49:42.342+0200",
 "followUp:":"2013-01-23T13:44:42.546+0200",
 "lastUpdated:":"2013-01-23T13:44:42.546+0200",
 "delegationState":"RESOLVED",
 "description":"aDescription",
 "executionId":"anExecution",
 "owner":"anOwner",
 "parentTaskId":"aParentId",
 "priority":10,
 "processDefinitionId":"aProcDefId",
 "processInstanceId":"aProcInstId",
 "caseDefinitionId":"aCaseDefId",
 "caseInstanceId":"aCaseInstId",
 "caseExecutionId":"aCaseExecution",
 "taskDefinitionKey":"aTaskDefinitionKey",
 "suspended": false,
 "formKey":"aFormKey",
 "camundaFormRef": {
   "key": "aCamundaForm",
   "binding": "version",
   "version": 3
 },
 "tenantId":"aTenantId"}]

Request with OR queries

POST /task

Logical query: assignee = "John Munda" AND (name = "Approve Invoice" OR priority = 5) AND (suspended = false OR taskDefinitionKey = "approveInvoice")

Request Body:

{
  "assignee": "John Munda",
  "orQueries": [
    {
      "name": "Approve Invoice",
      "priority": 5
    },
    {
      "suspended": false,
      "taskDefinitionKey": "approveInvoice"
    }
  ]
}

Response

[
  {
    "id": "349fffa8-6571-11e7-9a44-d6940f5ef88d",
    "name": "Approve Invoice",
    "assignee": "John Munda",
    "created": "2017-07-10T15:10:54.670+0200",
    "due": "2017-07-17T15:10:54.670+0200",
    "lastUpdated": "2017-07-17T15:10:54.670+0200",
    "followUp": null,
    "delegationState": null,
    "description": "Approve the invoice (or not).",
    "executionId": "349f8a5c-6571-11e7-9a44-d6940f5ef88d",
    "owner": null,
    "parentTaskId": null,
    "priority": 50,
    "processDefinitionId": "invoice:1:2c8d8057-6571-11e7-9a44-d6940f5ef88d",
    "processInstanceId": "349f8a5c-6571-11e7-9a44-d6940f5ef88d",
    "taskDefinitionKey": "approveInvoice",
    "caseExecutionId": null,
    "caseInstanceId": null,
    "caseDefinitionId": null,
    "suspended": false,
    "formKey": "embedded:app:develop/invoice-forms/approve-invoice.html",
    "tenantId": null
  }
]