Activate jobs for a worker

POST

/v2/jobs/activation

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/jobs/activation"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"type\": \"payment-capture\", \"worker\": \"payments-worker-1\", \"timeout\": 30000, \"maxJobsToActivate\": 10, \"requestTimeout\": 20000 }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/jobs/activation';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"type":"payment-capture","worker":"payments-worker-1","timeout":30000,"maxJobsToActivate":10,"requestTimeout":20000}'
};

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/jobs/activation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "payment-capture", "worker": "payments-worker-1", "timeout": 30000, "maxJobsToActivate": 10, "requestTimeout": 20000 }'

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires job:activate

Locks up to maxJobsToActivate open jobs of the given type for the calling worker for timeout milliseconds. When no job is ready, the call long-polls for up to requestTimeout milliseconds. The answer is an empty jobs array when nothing arrives in that time.

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^required

application/json

object

type

required

The job type to activate.

string

worker

Worker name recorded on the lease.

string

timeout

required

Lease duration in milliseconds.

integer format: int64

requestTimeout

Long-poll wait in milliseconds. 0 uses the engine’s configured default, and a negative value returns immediately.

integer format: int64

maxJobsToActivate

required

integer format: int32

fetchVariable

Variable names to include. When absent, all visible variables are included.

Array<string> | null

tenantIds

When given, each entry must be the caller’s tenant.

Array<string>

tenantFilter

Only PROVIDED is accepted.

string

Allowed values: PROVIDED

withLease

Leased activation is not implemented yet. true is rejected with 400.

boolean

Example

{
  "type": "payment-capture",
  "worker": "payments-worker-1",
  "timeout": 30000,
  "maxJobsToActivate": 10,
  "requestTimeout": 20000
}

Responses

200

The activated jobs. The array is empty when no job became available in time.

application/json

object

jobs

required

Array<object>

object

type

required

string

processDefinitionId

required

The BPMN process id.

string

processDefinitionVersion

required

integer format: int32

elementId

required

string

customHeaders

required

The task headers from the model, exactly as written there.

object

key

additional properties

string

worker

required

string

retries

required

integer format: int32

deadline

required

Lease expiry in epoch milliseconds.

integer format: int64

variables

required

object

key

additional properties

any

tenantId

required

string

physicalTenantId

required

Always equal to tenantId.

string

jobKey

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]*$/

processDefinitionKey

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]*$/

kind

required

string

Allowed value: BPMN_ELEMENT

listenerEventType

required

string

Allowed value: UNSPECIFIED

userTask

required

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

null

tags

required

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

Array<string>

rootProcessInstanceKey

required

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

null

businessId

required

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

null

priority

required

integer

leaseToken

required

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

null

Example

{
  "jobs": [
    {
      "jobKey": "2251799813685249",
      "processInstanceKey": "2251799813685249",
      "processDefinitionKey": "2251799813685249",
      "elementInstanceKey": "2251799813685249",
      "kind": "BPMN_ELEMENT",
      "listenerEventType": "UNSPECIFIED",
      "priority": 0
    }
  ]
}

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/jobs/activation"
}

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/jobs/activation"
}

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/jobs/activation"
}

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/jobs/activation"
}

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/jobs/activation"
}

Activate jobs for a worker

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

Headers

403

Example

413

Example

500

Example

501

Example

503

Example

Request Body^required