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:

• Camunda Modeler
• BPMN.io

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: application/xml

required

string <xml>

Responses

http://localhost:8080/v1/process-definitions

Request samples

• Payload
• curl

Content type

application/xml

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions>
  <bpmn:process id="loan-application" name="Loan Application Process" isExecutable="true">
    ...
  </bpmn:process>
</bpmn:definitions>

Response samples

• 201
• 400
• 409
• 502

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

Responses

http://localhost:8080/v1/process-definitions

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-definitions

Response samples

• 200
• 500

Content type

application/json

{

• "items": [

  • {

    • "key": "4503599627370498",
    • "version": 1,
    • "bpmnProcessId": "loan-application"

    },
  • {

    • "key": "4503599627370499",
    • "version": 2,
    • "bpmnProcessId": "loan-application"

    },
  • {

    • "key": "4503599627370500",
    • "version": 1,
    • "bpmnProcessId": "credit-check"

    }

  ],
• "offset": 0,
• "size": 10,
• "count": 3

}

Look for your process definition in the response.

ProcessDefinitionSimple Schema

This schema represents an item in the process definitions list:

key required	string^\d{15,20}$
version required	integer
bpmnProcessId required	string

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

string^\d{15,20}$ Example: 4503599627370498

Responses

http://localhost:8080/v1/process-definitions/{processDefinitionKey}

Request samples

• curl

curl -X GET http://localhost:8080/v1/process-definitions/123456789

Response samples

• 200
• 400
• 500

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:

• Start a process instance _TODO
• Query process instances _TODO