Start a process instance

POST

/v2/process-instances

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/process-instances"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"processDefinitionId\": \"order-fulfilment\", \"variables\": { \"orderId\": \"A-1042\", \"amount\": 129.5 } }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/process-instances';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"processDefinitionId":"order-fulfilment","variables":{"orderId":"A-1042","amount":129.5}}'
};

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/process-instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "processDefinitionId": "order-fulfilment", "variables": { "orderId": "A-1042", "amount": 129.5 } }'

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires instance:create

Starts an instance of a definition. Name the definition either by processDefinitionKey, or by processDefinitionId with an optional processDefinitionVersion. When the version is absent or -1, the latest version is used. The call returns once the start has been committed.

With awaitCompletion: true the call instead waits until the instance has completed and answers with its variables at completion (only the names in fetchVariables, when given). If the wait (requestTimeout milliseconds; 0 or absent means 30 seconds, at most one hour) runs out first the answer is 504 and the instance keeps running. An instance that is terminated instead of completing is answered with 409.

startInstructions start the instance at the named elements instead of its none start event. Each element gets the embedded or event sub-processes that enclose it; instructions whose elements share an enclosing sub-process share one instance of it. Every named element is activated before any of them continues. A sequence flow, a start event, a boundary event, an event that follows an event-based gateway, an element inside a multi-instance element, an unknown element, and a start whose enclosing sub-process cannot open its event subscriptions with the given variables are all refused with 400, and nothing is created.

The variables document may be at most 4,128,768 bytes of JSON (the 4 MiB record limit less 64 KiB kept for the rest of the creation record); a larger one is refused with 400. The request body itself is limited to 4 MiB (413).

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.

Idempotency-Key

string

>= 1 characters <= 200 characters

Makes a retried command safe. A repeat with the same key and the same body replays the first answer. A repeat with the same key and a different body is refused with 409.

traceparent

string

W3C trace context that is carried into the started instance.

tracestate

string

W3C trace state that accompanies traceparent.

Request Body^required

application/json

object

processDefinitionKey

Any of:

string
integer

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

string

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

processDefinitionId

The BPMN process id.

string

processDefinitionVersion

An exact version. Absent or -1 selects the latest.

integer format: int32

variables

object

key

additional properties

any

startInstructions

Start at these elements instead of the none start event (see the operation description for the elements that can be named).

Array<object>

object

elementId

required

string

tenantId

Must be the caller’s tenant.

string

operationReference

A caller reference for batch-operation bookkeeping. Accepted and not used by this release.

integer format: int64

>= 1

awaitCompletion

Wait until the instance has completed and answer with its variables.

boolean

fetchVariables

With awaitCompletion, answer with only these variables. Empty or absent: all root variables.

Array<string>

requestTimeout

With awaitCompletion, how long to wait in milliseconds. 0 means 30 seconds.

integer format: int64

0 <= 3600000

runtimeInstructions

End the instance once one of the named elements has completed or been terminated. The instance is terminated; the element’s outgoing flows are not taken.

Array<object>

object

type

required

string

Allowed values: TERMINATE_PROCESS_INSTANCE

afterElementId

required

An element of the definition; a sequence flow is refused.

string

tags

Instance tags. Duplicates are dropped; at most 10 distinct tags. Recorded on the creation record and returned in the response.

Array<string>

<= 10 items

businessId

A business identifier (at most 256 characters, not blank). Recorded on the creation record and returned in the response; uniqueness is not enforced by this release.

string

>= 1 characters <= 256 characters

Example

{
  "processDefinitionId": "order-fulfilment",
  "variables": {
    "orderId": "A-1042",
    "amount": 129.5
  }
}

Responses

200

The instance was started.

application/json

object

processDefinitionId

required

string

processDefinitionKey

required

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

string

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

processDefinitionVersion

required

integer format: int32

tenantId

required

string

variables

required

The variables supplied in the request, echoed back; with awaitCompletion, the instance’s variables at completion.

object

key

additional properties

any

processInstanceKey

required

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

string

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

tags

required

The distinct tags of the request

Array<string>

businessId

required

The business id of the request

string | null

Example

{
  "processDefinitionId": "order-fulfilment",
  "processDefinitionKey": "2251799813685249",
  "processDefinitionVersion": 1,
  "tenantId": "default",
  "variables": {
    "orderId": "A-1042",
    "amount": 129.5
  },
  "processInstanceKey": "2251799813685262",
  "tags": [
    "priority"
  ],
  "businessId": "A-1042"
}

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/process-instances"
}

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/process-instances"
}

404

The entity does not exist in the caller’s tenant.

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:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource does not exist",
  "instance": "/v2/process-instances"
}

409

An idempotency-key conflict, or a command the target’s current state does not allow.

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:conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The idempotency key is already associated with another request",
  "instance": "/v2/process-instances"
}

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/process-instances"
}

429

The tenant’s quota is exhausted.

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:quota-exhausted",
  "title": "Quota Exhausted",
  "status": 429,
  "detail": "The tenant active-instance quota is exhausted",
  "instance": "/v2/process-instances"
}

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/process-instances"
}

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/process-instances"
}

504

The request’s own wait ran out before the awaited outcome. The command itself took effect.

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

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "mode": "example"
}

Start a process instance

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

Headers

403

Example

404

Example

409

Example

413

Example

429

Example

500

Example

501

Example

503

Example

504

Examplegenerated

Request Body^required

Example^generated