Search user tasks

POST

/v2/user-tasks/search

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/user-tasks/search"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"filter\": { \"state\": \"CREATED\", \"candidateGroup\": \"approvers\", \"priority\": { \"$gte\": 60 } }, \"sort\": [ { \"field\": \"priority\", \"order\": \"DESC\" } ], \"page\": { \"limit\": 20 } }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/user-tasks/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"filter":{"state":"CREATED","candidateGroup":"approvers","priority":{"$gte":60}},"sort":[{"field":"priority","order":"DESC"}],"page":{"limit":20}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8080/v2/user-tasks/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "state": "CREATED", "candidateGroup": "approvers", "priority": { "$gte": 60 } }, "sort": [ { "field": "priority", "order": "DESC" } ], "page": { "limit": 20 } }'

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires task:read

The task list of the caller. The answer holds only the tasks the principal may see (docs/task-authorization.md): the tasks assigned to them, the tasks naming them or one of their groups as candidates, the unassigned tasks without any candidates, and the tasks or processes a stored task:read or task:admin grant names. A tenant-wide task:admin sees every task of the tenant.

Each filter property takes a plain value (an exact match) or an object of operators: $eq, $neq, $exists, $in, $notIn, $like (text: * any run, ? one character, \ escapes), and $gt, $gte, $lt, $lte for priority and the dates. localVariables and processInstanceVariables match variables of the task’s own scope and of its process instance; their value is compared with the variable’s JSON text. $or takes a list of filter objects, one of which must match. tags and businessId are refused with 400, since tasks carry neither.

Sort fields are creationDate, completionDate, followUpDate, dueDate, priority and name; absent values sort last, and ties are broken by userTaskKey. Page with from (an offset), after (the endCursor of the previous page) or before (the startCursor of the next one). totalItems counts every match. A search that would consider more than 10000 tasks after the exact filters is refused with 400; narrow the filter.

Authorizations

Parameters

Header Parameters

x-tenant-id

string

>= 1 characters

Tenant selection. A principal bound to one tenant may omit it; if sent, it must equal that tenant (403 otherwise). A principal that may act in several tenants must send it on every request: without it the request is refused with 400, and a tenant it may not act in is refused with 403.

Request Body

application/json

object

filter

object

state

Any of:

string

assignee

Any of:

string

priority

Any of:

string

elementId

Any of:

string

name

Any of:

string

candidateGroup

Any of:

string

candidateUser

Any of:

string

tenantId

Any of:

string

processDefinitionId

Any of:

string

creationDate

Any of:

string

completionDate

Any of:

string

followUpDate

Any of:

string

dueDate

Any of:

string

userTaskKey

Any of:

string

processDefinitionKey

Any of:

string

processInstanceKey

Any of:

string

elementInstanceKey

Any of:

string

localVariables

Array<object>

object

name

required

string

>= 1 characters

value

required

Any of:

string

processInstanceVariables

Array<object>

object

name

required

string

>= 1 characters

value

required

Any of:

string

tags

Refused with 400; tasks carry no tags.

businessId

Refused with 400; tasks carry no business id.

$or

One of these filter objects must match (they may not nest $or).

Array<object>

object

sort

Array

object

field

required

string

order

string

Allowed values: ASC DESC

field

required

Allowed values: creationDate completionDate followUpDate dueDate priority name

page

Use at most one of from, after and before.

object

limit

integer

default: 100 >= 1 <= 1000

from

An offset into the sorted matches.

integer

after

The endCursor of the previous page.

string

before

The startCursor of the following page.

string

Example

{
  "filter": {
    "state": "CREATED",
    "candidateGroup": "approvers",
    "priority": {
      "$gte": 60
    }
  },
  "sort": [
    {
      "field": "priority",
      "order": "DESC"
    }
  ],
  "page": {
    "limit": 20
  }
}

Responses

200

One page of user tasks.

application/json

object

items

required

Array<object>

object

name

required

The name of the task’s BPMN element.

string | null

state

required

string

Allowed values: CREATED COMPLETED CANCELED

assignee

required

string | null

elementId

required

string

candidateGroups

required

Array<string>

candidateUsers

required

Array<string>

processDefinitionId

required

string

creationDate

required

An RFC 3339 timestamp.

string format: date-time

completionDate

required

Any of:

string
null

An RFC 3339 timestamp.

string format: date-time

followUpDate

required

Any of:

string
null

An RFC 3339 timestamp.

string format: date-time

dueDate

required

Any of:

string
null

An RFC 3339 timestamp.

string format: date-time

tenantId

required

string

externalFormReference

required

The form reference an application resolves itself.

string | null

processDefinitionVersion

required

integer format: int32

customHeaders

required

The task headers of the model, as text.

object

key

additional properties

string

priority

required

0 to 100, higher is more important. The model sets it with the priorityDefinition extension element (a literal or an expression); 50 when the model sets none. An update or a task listener correction may change it.

integer

<= 100

userTaskKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

elementInstanceKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

processName

required

Part of the wire shape. This release always sends null.

null

processDefinitionKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

processInstanceKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

rootProcessInstanceKey

required

Any of:

string
null

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

businessId

required

Part of the wire shape. This release always sends null.

null

formKey

required

Any of:

string
null

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

tags

required

Part of the wire shape. This release always sends an empty array.

Array<string>

page

required

totalItems counts every match; hasMoreTotalItems is always false. startCursor and endCursor locate the first and last item of this page (null for an empty page).

object

totalItems

required

integer format: int64

hasMoreTotalItems

required

boolean

startCursor

required

Opaque, base64. Set on every page with items; null only on an empty page.

string | null format: base64

endCursor

required

Opaque, base64. Set on every page with items; pass it as page.after for the next page, which is empty once every item was seen. null only on an empty page.

string | null format: base64

Example

{
  "items": [
    {
      "state": "CREATED",
      "userTaskKey": "2251799813685249",
      "elementInstanceKey": "2251799813685249",
      "processDefinitionKey": "2251799813685249",
      "processInstanceKey": "2251799813685249",
      "rootProcessInstanceKey": "2251799813685249",
      "formKey": "2251799813685249"
    }
  ]
}

400

The request is malformed, or it uses a property or filter this release does not support.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:invalid-argument",
  "title": "Bad Request",
  "status": 400,
  "detail": "entity key must be a positive int64 string",
  "instance": "/v2/process-instances/0"
}

401

No valid credential was presented.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid bearer credential is required",
  "instance": "/v2/user-tasks/search"
}

Headers

WWW-Authenticate

string

Allowed value: Bearer

403

The caller lacks the required permission, a tenant named in the request is not the caller’s tenant, or a cookie write has no valid CSRF token.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The principal lacks the action this route requires",
  "instance": "/v2/user-tasks/search"
}

413

The body exceeds the configured request-size bound.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "The request exceeds the configured size limit",
  "instance": "/v2/user-tasks/search"
}

500

An internal failure. The details are never exposed.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:internal",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The request could not be completed",
  "instance": "/v2/user-tasks/search"
}

501

The operation is not offered in the engine’s current deployment mode.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:mode-not-supported",
  "title": "Mode Not Supported",
  "status": 501,
  "detail": "/v2/clock is not supported in bundled mode: the deterministic virtual clock and the storage-free reset exist only for the Embedded engine; Bundled and Cluster run on the system clock over durable history, which cannot be pinned, rewound or discarded",
  "instance": "/v2/clock",
  "mode": "bundled"
}

503

Backpressure, or a dependency is not ready. Retry with the same idempotency key.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The required engine service is not ready",
  "instance": "/v2/user-tasks/search"
}