Skip to main content

How to Deploy a Process Definition

This guide explains how to deploy a BPMN process definition to ZenBPM.

Prerequisites​

  • ZenBPM server is running and accessible
  • A valid BPMN 2.0 process definition file

Steps​

1. Prepare Your BPMN File​

Ensure your BPMN file follows the BPMN 2.0 specification. You can create BPMN files using tools like:

Save your BPMN file with a .bpmn extension.

2. Deploy Using REST API​

You can deploy your process definition using the REST API:

Deploy a new process definition

Request Body schema: multipart/form-data
required
resource
required
string <binary>

BPMN process definition file (.bpmn format only, max 4MB)

Responses

Response samples

Content type
application/json
{
  • "processDefinitionKey": 4503599627370498
}

The response will include a processDefinitionKey that you can use to reference this process definition.

3. Verify Deployment​

To verify that your process definition was deployed successfully, you can list all process definitions:

Get list of process definitions

query Parameters
onlyLatest
boolean
Default: false

If true, returns only the latest version of each process definition grouped by bpmnProcessId

sortBy
string
Enum: "name" "bpmnProcessId" "bpmnProcessName" "version" "key"

Sort field

sortOrder
string
Enum: "asc" "desc"

Sort direction

bpmnProcessId
string

Filter by BPMN process ID to get all versions of a specific process

page
integer <int32> >= 1
Default: 1
Example: page=1

Page number (1-based indexing)

size
integer <int32> [ 1 .. 100 ]
Default: 10
Example: size=10

Number of items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 1,
  • "size": 10,
  • "count": 3,
  • "totalCount": 3
}

Look for your process definition in the response.

ProcessDefinitionSimple Schema​

This schema represents an item in the process definitions list:

key
required
integer <int64>
version
required
integer
bpmnProcessId
required
string
bpmnProcessName
string

Process name from BPMN

4. Get Process Definition Details​

Once you have deployed your process definition, you can retrieve its details using the process definition key:

Get process definition

path Parameters
processDefinitionKey
required
integer <int64>
Example: 4503599627370498

Responses

Response samples

Content type
application/json
{
  • "key": "4503599627370498",
  • "version": 1,
  • "bpmnProcessId": "loan-application",
  • "bpmnData": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions>\n <bpmn:process id=\"loan-application\" name=\"Loan Application Process\" isExecutable=\"true\">\n ...\n </bpmn:process>\n</bpmn:definitions>\n"
}

Troubleshooting​

Invalid BPMN Format​

If you receive an error about invalid BPMN format, check that:

  • Your BPMN file is valid XML
  • The BPMN file follows the BPMN 2.0 specification
  • All referenced elements (like message definitions) are properly defined

Connection Issues​

If you can't connect to the ZenBPM server:

  1. Verify the server is running
  2. Check that you're using the correct host and port
  3. Ensure there are no network issues or firewalls blocking the connection

Next Steps​

After deploying your process definition, you can: