Get Tasks
Queries for tasks that fulfill a given filter. The size of the result set can be retrieved by using the Get Task Count method.
Security Consideration
There are several query parameters (such as assigneeExpression) for specifying an EL expression. These are disabled by default to prevent remote code execution. See the section on security considerations for custom code in the user guide for details.
Method
GET /task
Parameters
Query Parameters
| Name | Description |
|---|---|
| processInstanceId | Restrict to tasks that belong to process instances with the given id. |
| 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 a comma-separated list. |
| 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 and comma-separated activity instance ids. |
| tenantIdIn | Only include tasks which belong to one of the passed and comma-separated tenant ids. |
| 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. |
| 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. |
| 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.546+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.435+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.243+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.
|
| followUpDate | 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.342+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.542+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.234+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.
By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.432+0200.
The typical use case is to query all "active" tasks for a user for a given date. |
| 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.324+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.342+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. By default*, the date must have the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g., 2013-01-23T14:42:45.332+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.
|
| 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 comma-separated list 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.
|
| 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 users. Value may only be true,
as false is the default behavior. |
| 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 | Only include tasks that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value.
key is the variable name, operator is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.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.key and value may not contain underscore or comma characters.
|
| processVariables | Only include tasks that belong to process instances that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value.
key is the variable name, operator is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.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.key and value may not contain underscore or comma characters.
|
| caseInstanceVariables | Only include tasks that belong to case instances that have variables with certain values.
Variable filtering expressions are comma-separated and are structured as follows: A valid parameter value has the form key_operator_value.
key is the variable name, operator is the comparison operator to be used and value the variable value.Note: Values are always treated as String objects on server side.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.key and value may not contain underscore or comma characters.
|
| parentTaskId | Restrict query to all tasks that are sub tasks of the given task. Takes a task id. |
| sortBy | Sort the results lexicographically by a given criterion. Valid values are
instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created,
description, id, name, nameCaseInsensitive and priority.
Must be used in conjunction with the sortOrder parameter. |
| sortOrder | Sort the results in a given order. Values may be asc for ascending order or desc for descending order.
Must be used in conjunction with the sortBy parameter. |
| 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. |
* For further information, please see the documentation.
Result
A JSON array of task objects. Each task object has the following properties:
| Name | Value | 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. |
| 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. |
| tenantId | String | If not null, the tenant id of the task. |
* For further information, please see the documentation.
Response Codes
| Code | Media type | Description |
|---|---|---|
| 200 | application/json | Request successful. |
| 200 | application/hal+json | Request successful. In case of an expected HAL response. |
| 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
GET /task?assignee=anAssignee&delegationState=RESOLVED&maxPriority=50
Response
[{"id":"anId",
"name":"aName",
"assignee":"anAssignee",
"created":"2013-01-23T13:42:42.657+0200",
"due":"2013-01-23T13:49:42.323+0200",
"followUp:":"2013-01-23T13:44:42.987+0200",
"delegationState":"RESOLVED",
"description":"aDescription",
"executionId":"anExecution",
"owner":"anOwner",
"parentTaskId":"aParentId",
"priority":42,
"processDefinitionId":"aProcDefId",
"processInstanceId":"aProcInstId",
"caseDefinitionId":"aCaseDefId",
"caseInstanceId":"aCaseInstId",
"caseExecutionId":"aCaseExecution",
"taskDefinitionKey":"aTaskDefinitionKey",
"suspended": false,
"formKey":"aFormKey",
"tenantId": "aTenantId" }]