Deploy BPMN, DMN and form resources

POST

/v2/deployments

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/deployments"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
    .method("POST", HttpRequest.BodyPublishers.ofString("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resources\"\r\nContent-Type: text/plain\r\n\r\nexample\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"tenantId\"\r\nContent-Type: text/plain\r\n\r\nexample\r\n-----011000010111000001101001--\r\n"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/deployments';
const form = new FormData();
form.append('resources', 'example');
form.append('tenantId', 'example');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

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/deployments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form resources=example \
  --form tenantId=example

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires process:deploy

Deploys one or more resources (.bpmn, .dmn, .form) as a single deployment. Each decision of a DMN resource is listed as one decisionDefinition entry, followed by one decisionRequirements entry for the resource’s decision requirements graph. A byte-identical resource that is deployed again reuses the existing version. Cluster mode does not yet deploy DMN through this route: a deployment with a DMN resource answers 409 there before anything is deployed (POST /v1/deployments deploys decisions in every mode). A deployment whose user tasks lack the user-task implementation marker succeeds, and the answer lists each of those tasks in warnings.

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.

Request Body^required

multipart/form-data

Multipart form. Each file part is one resource, and its file name (ending in .bpmn or .form) is the resource name. An optional text part named tenantId must be the caller’s tenant.

object

resources

required

Array<string>

>= 1 items

tenantId

string

Responses

200

The deployment was committed.

application/json

object

deploymentKey

required

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

string

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

tenantId

required

string

deployments

required

Array<object>

Exactly one of processDefinition, decisionDefinition, decisionRequirements and form is set. The other members are null.

object

processDefinition

required

Any of:

object
null

object

processDefinitionId

required

string

processDefinitionVersion

required

integer format: int32

>= 1

resourceName

required

string

tenantId

required

string

processDefinitionKey

required

Any of:

string
null

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

string

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

decisionDefinition

required

Any of:

object
null

object

decisionDefinitionId

required

string

version

required

integer format: int32

>= 1

name

required

The decision’s DMN name; empty when it has none.

string

tenantId

required

string

decisionRequirementsId

required

string

decisionDefinitionKey

required

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

string

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

decisionRequirementsKey

required

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

string

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

decisionRequirements

required

Any of:

object
null

object

decisionRequirementsId

required

string

decisionRequirementsName

required

The graph’s DMN name; empty when it has none.

string

version

required

integer format: int32

>= 1

resourceName

required

string

tenantId

required

string

decisionRequirementsKey

required

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

string

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

form

required

Any of:

object
null

object

formId

required

string

formKey

required

Any of:

string
null

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

string

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

resourceName

required

string

tenantId

required

string

version

required

integer format: int32

>= 1

resource

required

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

null

warnings

Present only when the deployment succeeded with warnings. Each entry names one element; the same warnings are written to the engine log.

Array<object>

object

code

required

USER_TASK_WITHOUT_MARKER: a user task without the user-task implementation marker. It still runs as a native user task, with the task-list lifecycle and API; no job is created for it, so a job worker waiting for one would wait forever.

string

Allowed values: USER_TASK_WITHOUT_MARKER

message

required

string

resourceName

required

string

processDefinitionId

required

string

elementId

required

string

Example

{
  "deploymentKey": "2251799813685249",
  "deployments": [
    {
      "processDefinition": {
        "processDefinitionKey": "2251799813685249"
      },
      "decisionDefinition": {
        "decisionDefinitionKey": "2251799813685249",
        "decisionRequirementsKey": "2251799813685249"
      },
      "decisionRequirements": {
        "decisionRequirementsKey": "2251799813685249"
      },
      "form": {
        "formKey": "2251799813685249"
      }
    }
  ],
  "warnings": [
    {
      "code": "USER_TASK_WITHOUT_MARKER"
    }
  ]
}

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/deployments"
}

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/deployments"
}

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/deployments"
}

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/deployments"
}

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/deployments"
}

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/deployments"
}

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/deployments"
}

Deploy BPMN, DMN and form resources

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

Headers

403

Example

409

Example

413

Example

429

Example

500

Example

501

Example

503

Example

Request Body^required