Definitions and Deployment

This page covers what happens between save and run: how BPMN files are stored as definition versions, what deployment does, how process versioning works, and how to start a new instance once a process is live.

Concepts

Concept	Identifier	What it is
Definition	`definitionsID` (from the BPMN XML's outer `<definitions id="…">`)	The stable identity of a BPMN file across edits. Saving a new revision adds another version under the same `definitionsID`; the ID itself doesn't change
Resource version	`resourceID` (UUID)	One stored revision of a definition. Carries the actual XML body, a name, and a deployed/draft flag
Process	`processID` (the `id` attribute on `<bpmn:process>`)	A single executable flow inside a definition. One definition can contain multiple processes
Process version	`processDefinitionID` (UUID) + `version` (integer)	One deployed iteration of a process. Auto-incremented per `processID` each time the containing definition is deployed

The relationship: a definition has many resource versions; each deployed resource produces one new process version for every process declared inside it.

Lifecycle

A BPMN file moves through three stages:

   ┌──────────────┐    save     ┌──────────────┐   deploy    ┌──────────────┐
   │  In modeler  │ ──────────► │     Draft    │ ──────────► │   Deployed   │
   │ (browser)    │             │  resource    │             │  resource +  │
   │              │             │  (editable)  │             │  new process │
   └──────────────┘             └──────────────┘             │   version(s) │
                                       ▲                     └──────────────┘
                                       │
                              edit / save again

Draft — saved to the project but not yet executable. You can edit drafts, test-run them, and delete them.
Deployed — the resource version is locked and the processes inside it are now runnable.

A deployed resource version is immutable. To change a deployed process you upload a new resource version under the same definitionsID and deploy that.

The Definitions view

Open BPMN Definitions from the BPMN navigation. One row per definitionsID, showing the latest version's metadata:

Column	Description
Definition ID	The stable ID from the BPMN XML
Name	Display name from the latest version
Versions	How many stored revisions exist
Status	Whether the latest version is deployed
Created at	When the latest version was uploaded
Actions	Edit (open the latest version in the modeler) and view history

A New button (visible to project Editors and Admins) opens a fresh modeler tab.

The Versions view

Drill into a definition to see all of its resource versions, oldest to newest:

Column	Description
Version	Sequential ordinal (`v1`, `v2`, …) within this definition
Name	Display name as set when that version was saved
Status	`Deployed` or `Draft`
Created at	Upload timestamp
Created by	The user who saved that version
Actions	View contents, open in modeler, delete (drafts only)

Drafts can be deleted to clean up exploratory revisions. Deployed versions cannot be deleted — they're load-bearing for any running instances and any references from other deployed processes (call activities, business-rule task DMN references). Past instances of a deployed version remain in history regardless.

What deployment does

The Deploy action on a saved draft does three things:

Marks the resource version as deployed. The XML is now immutable.
Registers a new process version for every <process> inside the resource. Each process's version number is auto-incremented per processID, starting at 1 the first time. Different processes inside the same resource can be at different version numbers.
Activates typed start events on the new version. Message, signal, and timer start events register so an inbound message, signal, or scheduled tick can start an instance of the new version.

Deployment is one-way per resource version. You can't "undeploy" — to retire a process, deploy a new version that does nothing or stop sending traffic to it.

What re-deployment does

When you deploy a new version of a definition that's already been deployed before:

What happens	Notes
The new resource version is registered	Same as a first deploy
Each process inside gets a new process version	`version` column bumps for that `processID`
Typed start-event registrations from the previous version are deactivated	Inbound messages, signals, and timer fires now create instances of the new version, not the old one
Running instances of the previous version keep running	They continue under the version they were started with — re-deploying does not automatically migrate them
The previous version remains "deployed"	It can still be the source/target of an explicit instance migration. Call activities and business-rule tasks pointing at the old version still resolve

If you need to move running instances over to the new version, use instance migration — the API supports migration plans that map nodes between versions.

The Processes view

The Processes view aggregates by processID across all of its deployed versions. One row per process:

Column	Description
Process ID	The BPMN `id` attribute on `<bpmn:process>`
Name	Process name from the most recent version
Versions	Count of deployed versions for this `processID`
Running	Instances with status `RUNNING` across all versions
Total	All instances across all statuses

Use this view when thinking about a process as a long-lived unit, regardless of which version is deployed today.

The Process Versions view

Drill into a process to see each deployed version and its instance counts:

Column	Description
Version	Version number, starting at `v1`
Name	Process name from that version
Resource	The resource version this process came from
Running	Instances of this version with status `RUNNING`
Total	All instances of this version, across statuses
Created at	When the version was deployed

This is the place to pick the source/target version when migrating running instances, or to see how traffic is distributed if you've shipped multiple versions over time.

Starting an instance

There are two paths.

Production instance (deployed only)

POST /projects/{projectID}/bpmn/instances

Field	Required	Notes
`processDefinitionID`	yes	UUID of a deployed process version (the `id` of a process version)
`variables`	no	Initial variables. Available to FEEL expressions and service tasks from the first activity onward

Returns 201 Created with the new instance's workflowID, which you'll use to fetch state, send signals/messages, complete user tasks, and so on.

curl -X POST "$API/projects/$PROJECT/bpmn/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "processDefinitionID": "f8a3…",
    "variables": { "orderId": "ORD-123", "amount": 49.95 }
  }'

If you want to target a specific version, pass the processDefinitionID of that version. To always run the latest, look up the most recent version via the Process Versions view (or GET /processes/{processID}/versions) and pass its UUID.

Test instance (drafts and deployed)

The modeler's Run button uses a different endpoint that works against a resource version directly — drafts included:

POST /projects/{projectID}/bpmn/resources/{resourceID}/test

Field	Required	Notes
`processID`	no	BPMN process ID inside the resource. Defaults to the first executable process
`variables`	no	Initial variables

Test instances run on the same engine as production but are flagged so dashboards can filter them out. Use them to try out an in-progress design before deploying.

From the UI

The first-class start-from-UI path today is the modeler's Run button — see Testing from the modeler. For production starts, use the API directly or have an upstream system (typed start event, signal, timer) trigger them.

API reference

Endpoint	Use
`GET /projects/{projectID}/bpmn/resources/latest`	List the latest version of each definition (drives the Definitions view)
`GET /projects/{projectID}/bpmn/resources/by-definitions-id/{definitionsID}`	List every version of a definition, oldest to newest
`POST /projects/{projectID}/bpmn/resources`	Create a new draft resource (first save)
`PUT /projects/{projectID}/bpmn/resources/{resourceID}`	Update a draft's XML (drafts only — deployed versions are immutable)
`DELETE /projects/{projectID}/bpmn/resources/{resourceID}`	Delete a draft resource version
`POST /projects/{projectID}/bpmn/resources/{resourceID}/deploy`	Deploy a draft, locking it and creating new process versions
`POST /projects/{projectID}/bpmn/validate`	Validate BPMN XML without saving — same checks the modeler runs at save time
`POST /projects/{projectID}/bpmn/resources/{resourceID}/test`	Start a test instance against any resource version
`POST /projects/{projectID}/bpmn/instances`	Start a production instance against a deployed process version
`GET /projects/{projectID}/bpmn/processes`	List one entry per process with aggregate instance counts
`GET /projects/{projectID}/bpmn/processes/{processID}/versions`	List deployed versions of one process with per-version instance counts

Concepts​

Lifecycle​

The Definitions view​

The Versions view​

What deployment does​

What re-deployment does​

The Processes view​

The Process Versions view​

Starting an instance​

Production instance (deployed only)​

Test instance (drafts and deployed)​

From the UI​

API reference​