UpdateProcessDefinitionCommand

Overview

Updates an existing process definition.

Purpose

Modifies the BPMN XML, configuration, or metadata of an existing process definition. Creates a new version while preserving existing instances.

Command Type

CB.Administration.Api.Commands.BPM.Process.UpdateProcessDefinitiionCommand

Request

{
  "cmd": "UpdateProcessDefinitiionCommand",
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow v2",
    "description": "Updated with automated checks",
    "bpmnXml": "<?xml version=\"1.0\"...",
    "isActive": true,
    "metadata": {
      "version": "2.0",
      "changelog": "Added automated fraud detection"
    }
  }
}

Request Fields (data object)

Field	Type	Required	Default	Description
`id`	long	Yes	-	ID of process definition to update
`name`	string	No	(unchanged)	Updated name
`description`	string	No	(unchanged)	Updated description
`bpmnXml`	string	No	(unchanged)	Updated BPMN XML
`category`	string	No	(unchanged)	Updated category
`isActive`	boolean	No	(unchanged)	Activation status
`metadata`	object	No	(unchanged)	Updated metadata

Versioning Behavior

When updating a process definition:

New Version Created: A new version number is assigned
Existing Instances Preserved: Running instances continue with old version
New Instances Use New Version: Future instances use updated definition

Version Strategy

Version 1 (Original)
├── Instance A (running) ─── continues with V1
├── Instance B (running) ─── continues with V1
└── Instance C (completed) ─ remains V1

Update Process Definition ➜ Version 2 Created

Version 2 (Updated)
├── Instance D (new) ─────── uses V2
└── Instance E (new) ─────── uses V2

Version 1
├── Instance A (still running V1)
└── Instance B (still running V1)

Response

{
  "isSuccessful": true,
  "message": "Process definition updated successfully",
  "statusCode": "00",
  "data": {
    "id": 456,
    "version": 2,
    "previousVersion": 1,
    "activeInstances": 5,
    "warningMessage": "5 active instances still running version 1"
  }
}

Response Fields

Field	Type	Description
`id`	long	Process definition ID
`version`	int	New version number
`previousVersion`	int	Previous version number
`activeInstances`	int	Number of instances still running old version
`warningMessage`	string	Warning about active instances on old version

Error Responses

Process Definition Not Found

{
  "isSuccessful": false,
  "message": "Process definition with ID 456 not found",
  "statusCode": "404"
}

Invalid Update (Breaking Change)

{
  "isSuccessful": false,
  "message": "Cannot update: Breaking changes detected",
  "statusCode": "40",
  "data": {
    "breakingChanges": [
      "Start event 'StartEvent_1' removed",
      "User task 'Task_Approve' references removed"
    ]
  }
}

Invalid BPMN XML

{
  "isSuccessful": false,
  "message": "Invalid BPMN XML: Missing end event",
  "statusCode": "40",
  "data": {
    "validationErrors": [
      "At least one end event required",
      "Sequence flow 'Flow_5' has invalid target"
    ]
  }
}

Update Scenarios

1. Update BPMN Logic Only

{
  "id": 456,
  "bpmnXml": "<?xml version=\"1.0\"...>"
}

2. Update Metadata Only

{
  "id": 456,
  "description": "Updated description",
  "metadata": {
    "version": "2.1",
    "changelog": "Fixed approval task configuration"
  }
}

3. Deactivate Process

{
  "id": 456,
  "isActive": false
}

4. Comprehensive Update

{
  "id": 456,
  "name": "Loan Approval Workflow v3",
  "description": "Complete redesign with parallel approval",
  "category": "Lending",
  "bpmnXml": "<?xml version=\"1.0\"...>",
  "isActive": true,
  "metadata": {
    "version": "3.0.0",
    "author": "Process Team",
    "changelog": "Redesigned with parallel gateway for concurrent approvals",
    "breakingChanges": ["Removed sequential approval", "Added parallel approval tasks"]
  }
}

Best Practices

✅ Do's

Document Changes: Always update metadata with changelog

{
  "metadata": {
    "version": "2.1.0",
    "changelog": "Added timeout handling to credit check task"
  }
}

Test New Version: Create test instance before activating

{
  "id": 456,
  "bpmnXml": "...",
  "isActive": false  // Test first
}

Monitor Active Instances: Check running instances before major updates

// First: Check active instances
GET /api/process-instances?processDefinitionId=456&status=ACTIVE

// Then: Update if safe
PUT /api/process-definitions/456

Use Semantic Versioning: Follow semver in metadata

1.0.0 → 1.1.0 (minor changes)
1.1.0 → 2.0.0 (breaking changes)

Incremental Updates: Make small, testable changes

✅ Update one task → test → update another
❌ Rewrite entire process at once

❌ Don'ts

Don't update production without testing
Don't ignore breaking change warnings
Don't remove tasks referenced by active instances
Don't change critical task IDs without migration plan
Don't update during peak hours - Schedule maintenance windows

Version Migration Strategy

Handling Active Instances

When you update a process with active instances:

Option 1: Let Them Complete (Recommended)

Update to V2
Wait for V1 instances to complete naturally
Monitor completion in GetProcessInstanceListQuery

Option 2: Graceful Migration

Update to V2 with isActive=false
Signal all V1 instances to reach completion
Activate V2 after V1 instances complete

Option 3: Force Migration (Use with caution)

Cancel all V1 instances
Restart them with V2
Only for non-critical processes

Breaking Changes Detection

The system detects potentially breaking changes:

Structural Changes

❌ Removing start/end events
❌ Removing user tasks referenced in active instances
❌ Changing task IDs that active instances depend on
❌ Removing variables used by active instances

Safe Changes

✅ Adding new tasks
✅ Adding new variables
✅ Updating task descriptions
✅ Adding parallel paths
✅ Modifying metadata

Example: Adding Parallel Approval

Version 1 (Sequential):

<process>
  <startEvent id="start"/>
  <userTask id="manager_approval" name="Manager Approval"/>
  <userTask id="director_approval" name="Director Approval"/>
  <endEvent id="end"/>
  
  <sequenceFlow sourceRef="start" targetRef="manager_approval"/>
  <sequenceFlow sourceRef="manager_approval" targetRef="director_approval"/>
  <sequenceFlow sourceRef="director_approval" targetRef="end"/>
</process>

Version 2 (Parallel):

<process>
  <startEvent id="start"/>
  <parallelGateway id="fork"/>
  <userTask id="manager_approval" name="Manager Approval"/>
  <userTask id="director_approval" name="Director Approval"/>
  <parallelGateway id="join"/>
  <endEvent id="end"/>
  
  <sequenceFlow sourceRef="start" targetRef="fork"/>
  <sequenceFlow sourceRef="fork" targetRef="manager_approval"/>
  <sequenceFlow sourceRef="fork" targetRef="director_approval"/>
  <sequenceFlow sourceRef="manager_approval" targetRef="join"/>
  <sequenceFlow sourceRef="director_approval" targetRef="join"/>
  <sequenceFlow sourceRef="join" targetRef="end"/>
</process>

Update Command:

{
  "cmd": "UpdateProcessDefinitiionCommand",
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow - Parallel",
    "bpmnXml": "<?xml version=\"1.0\"...>",
    "metadata": {
      "version": "2.0.0",
      "changelog": "Changed from sequential to parallel approval to reduce processing time"
    }
  }
}

CreateProcessDefinitionCommand - Create new process
GetProcessDefinitionByIdQuery - View current version
RenameProcessDefinitionCommand - Rename without versioning
GetProcessInstanceListQuery - Check active instances

Last Updated: January 6, 2026

Overview​

Purpose​

Command Type​

Request​

Request Fields (data object)​

Versioning Behavior​

Version Strategy​

Response​

Response Fields​

Error Responses​

Process Definition Not Found​

Invalid Update (Breaking Change)​

Invalid BPMN XML​

Update Scenarios​

1. Update BPMN Logic Only​

2. Update Metadata Only​

3. Deactivate Process​

4. Comprehensive Update​

Best Practices​

✅ Do's​

❌ Don'ts​

Version Migration Strategy​

Handling Active Instances​

Breaking Changes Detection​

Structural Changes​

Safe Changes​

Example: Adding Parallel Approval​

Related Commands​