DeleteProcessDefinitionCommand

Overview

Deletes a process definition.

Purpose

Removes a process definition from the system. Only allowed if no active instances exist (unless forced).

Command Type

CB.Administration.Api.Commands.BPM.Process.DeleteProcessDefinitiionCommand

Request

{
  "cmd": "DeleteProcessDefinitiionCommand",
  "data": {
    "id": 456,
    "force": false
  }
}

Request Fields (data object)

Field	Type	Required	Default	Description
`id`	long	Yes	-	ID of process definition to delete
`force`	boolean	No	false	Force deletion even with active instances (use with extreme caution)

Response

{
  "isSuccessful": true,
  "message": "Process definition deleted successfully",
  "statusCode": "00",
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow",
    "deletedInstances": 0,
    "deletedAt": "2026-01-06T15:30:00Z"
  }
}

Response Fields

Field	Type	Description
`id`	long	ID of deleted process definition
`name`	string	Name of deleted process
`deletedInstances`	int	Number of instances deleted (only if force=true)
`deletedAt`	datetime	Deletion timestamp

Error Responses

Has Active Instances

{
  "isSuccessful": false,
  "message": "Cannot delete: Process has 3 active instances",
  "statusCode": "40",
  "data": {
    "activeInstances": 3,
    "instanceIds": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ],
    "instanceDetails": [
      {
        "instanceId": "550e8400-e29b-41d4-a716-446655440001",
        "businessKey": "LOAN-12345",
        "status": "ACTIVE",
        "currentTask": "Manager Approval",
        "startTime": "2026-01-05T10:00:00Z"
      }
    ],
    "suggestion": "Use force=true to delete anyway or wait for instances to complete"
  }
}

Process Not Found

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

Process Used in Call Activities

{
  "isSuccessful": false,
  "message": "Cannot delete: Process is referenced by 2 other processes",
  "statusCode": "40",
  "data": {
    "referencedBy": [
      {
        "processId": 123,
        "processName": "Master Loan Workflow",
        "callActivityId": "CallActivity_CreditCheck"
      },
      {
        "processId": 789,
        "processName": "Account Opening Workflow",
        "callActivityId": "CallActivity_KYCCheck"
      }
    ],
    "suggestion": "Remove call activity references before deleting"
  }
}

Deletion Modes

Safe Delete (Default)

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

Behavior:

✅ Only deletes if NO active instances exist
✅ Prevents orphaned process instances
✅ Prevents data inconsistency
✅ Recommended for production

Force Delete (Dangerous)

{
  "id": 456,
  "force": true
}

Behavior:

⚠️ Deletes even with active instances
⚠️ Active instances become orphaned
⚠️ Orphaned instances cannot be resumed or managed
⚠️ Use only in exceptional circumstances

Pre-Deletion Checklist

Before deleting a process definition, verify:

1. Check Active Instances

# Query active instances
GET /api/process-instances?processDefinitionId=456&status=ACTIVE

# Response
{
  "data": {
    "items": [],
    "totalRecords": 0  // ✅ Safe to delete
  }
}

2. Check Call Activity References

# Search for processes that call this definition
GET /api/process-definitions?searchText="callActivityId:Process_456"

3. Check Scheduled Jobs

# Verify no scheduled executions
GET /api/process-definitions/456

# Response
{
  "data": {
    "schedulingEnabled": false  // ✅ No scheduled jobs
  }
}

4. Check Trigger Events

# Verify no automatic triggers
GET /api/process-definitions/456

# Response
{
  "data": {
    "triggerEvents": []  // ✅ No auto-triggers
  }
}

Deletion Workflow

Recommended Approach

Step 1: Deactivate Process

// Prevent new instances
{
  "id": 456,
  "isActive": false
}

Step 2: Wait for Completion

# Monitor active instances
GET /api/process-instances?processDefinitionId=456&status=ACTIVE

# Wait until totalRecords = 0

Step 3: Cancel Remaining Instances (if needed)

// For each active instance
{
  "instanceId": "guid-here",
  "reason": "Process definition being retired"
}

Step 4: Remove Dependencies

- Remove call activity references in other processes
- Disable scheduled executions
- Remove trigger event configurations

Step 5: Delete

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

Alternative to Deletion: Archival

Instead of deleting, consider deactivating:

{
  "id": 456,
  "isActive": false,
  "metadata": {
    "archived": true,
    "archivedDate": "2026-01-06",
    "archivedReason": "Process no longer used",
    "replacedBy": 789  // ID of replacement process
  }
}

Benefits of Archival:

✅ Preserves historical data
✅ Maintains audit trail
✅ Can be reactivated if needed
✅ Existing instances remain manageable
✅ No orphaned data

Force Delete Use Cases

When to Use `force=true`

Acceptable Scenarios:

🟢 Test/development environments
🟢 Duplicate processes created by mistake
🟢 Corrupted process definitions
🟢 Emergency cleanup after system migration

Unacceptable Scenarios:

🔴 Production processes with customer data
🔴 Processes with active approvals
🔴 Processes with pending transactions
🔴 Audit-required processes

Impact of Force Deletion

What Happens to Active Instances?

When you force delete with active instances:

Before Deletion:
Process Definition #456 "Loan Approval"
├── Instance A (ACTIVE) - at "Manager Approval" task
├── Instance B (ACTIVE) - at "Credit Check" task
└── Instance C (COMPLETED) ✓

Force Delete Process Definition #456

After Deletion:
❌ Process Definition #456 - DELETED
├── Instance A (ORPHANED) - cannot resume/manage
├── Instance B (ORPHANED) - cannot resume/manage
└── Instance C (historical record preserved)

Orphaned Instance Symptoms:

Cannot view process diagram
Cannot step forward/backward
Cannot signal or resume
Cannot see task definitions
Can only view historical data

Recovery from Accidental Deletion

If you accidentally delete a process definition:

Option 1: Restore from Backup

# Restore process definition from database backup
# Requires DBA intervention

Option 2: Recreate Process

// Recreate with same name and BPMN
{
  "name": "Loan Approval Workflow",
  "bpmnXml": "...",  // Use backed-up BPMN
  "category": "Lending"
}
// Note: New ID will be assigned, old instances remain orphaned

Option 3: Instance Migration Script

-- Update orphaned instances to point to new process definition
-- Requires careful data migration
-- Contact support for assistance

Example: Safe Deletion Workflow

# 1. Check current status
GET /api/process-definitions/456

# 2. Deactivate process
PUT /api/process-definitions/456
{
  "cmd": "UpdateProcessDefinitiionCommand",
  "data": {
    "isActive": false
  }
}

# 3. Check active instances
GET /api/process-instances?processDefinitionId=456&status=ACTIVE
# Response: 2 active instances

# 4. Wait for natural completion or cancel instances
POST /api/process-instances/guid1/cancel
POST /api/process-instances/guid2/cancel

# 5. Verify no active instances
GET /api/process-instances?processDefinitionId=456&status=ACTIVE
# Response: 0 active instances ✓

# 6. Safe delete
DELETE /api/process-definitions/456
{
  "cmd": "DeleteProcessDefinitiionCommand",
  "data": {
    "force": false
  }
}

# Success!

Audit and Compliance Considerations

Audit Trail

All deletions are logged with timestamp and user
Deletion reason should be documented in audit system
Completed instance history is preserved

Compliance Requirements

Some industries require process definitions to be preserved:

Banking/Finance: 7-10 years retention
Healthcare: HIPAA requirements
Government: Regulatory compliance

Recommendation: Use archival (deactivation) instead of deletion for compliance-sensitive processes.

Best Practices

✅ Do's

Always check for active instances first

GET /api/process-instances?processDefinitionId=456&status=ACTIVE

Deactivate before deleting

{
  "cmd": "UpdateProcessDefinitiionCommand",
  "data": { "isActive": false }
}  // First
// Wait/verify
{
  "cmd": "DeleteProcessDefinitiionCommand",
  "data": { "id": 456, "force": false }
}  // Then delete

Document deletion reasons

// In audit log or separate tracking system
{
  "processId": 456,
  "deletionReason": "Replaced by Process #789",
  "deletedBy": "admin@bank.com",
  "approvedBy": "manager@bank.com"
}

Backup BPMN XML before deletion

# Export process definition
GET /api/process-definitions/456?includeXml=true
# Save response locally

Prefer archival over deletion

❌ Don'ts

Don't use force=true in production without approval
Don't delete processes with active customer transactions
Don't delete without checking call activity references
Don't delete during business hours - schedule maintenance window
Don't delete without backup - export BPMN first

UpdateProcessDefinitionCommand - Deactivate instead of deleting
GetProcessDefinitionByIdQuery - Check process status before deletion
GetProcessInstanceListQuery - Verify no active instances
CancelProcessInstanceCommand - Cancel instances before deletion

Last Updated: January 6, 2026

Overview​

Purpose​

Command Type​

Request​

Request Fields (data object)​

Response​

Response Fields​

Error Responses​

Has Active Instances​

Process Not Found​

Process Used in Call Activities​

Deletion Modes​

Safe Delete (Default)​

Force Delete (Dangerous)​

Pre-Deletion Checklist​

1. Check Active Instances​

2. Check Call Activity References​

3. Check Scheduled Jobs​

4. Check Trigger Events​

Deletion Workflow​

Recommended Approach​

Alternative to Deletion: Archival​

Force Delete Use Cases​

When to Use force=true​

Impact of Force Deletion​

What Happens to Active Instances?​

Recovery from Accidental Deletion​

Option 1: Restore from Backup​

Option 2: Recreate Process​

Option 3: Instance Migration Script​

Example: Safe Deletion Workflow​

Audit and Compliance Considerations​

Audit Trail​

Compliance Requirements​

Best Practices​

✅ Do's​

❌ Don'ts​

Related Commands​