CreateProcessDefinitionCommand

Overview

Creates a new process definition from BPMN 2.0 XML.

Purpose

Uploads and validates a BPMN 2.0 workflow definition, making it available for process instance creation.

Command Type

CB.Administration.Api.Commands.BPM.Process.CreateProcessDefinitiionCommand

Request

{
  "cmd": "CreateProcessDefinitiionCommand",
  "data": {
    "name": "Loan Approval Workflow",
    "description": "Multi-stage loan approval process with credit checks",
    "category": "Lending",
    "bpmnXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><definitions xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\">...</definitions>",
    "contextLoaderType": "LoanApplicationContext",
    "triggerEvents": ["OnLoanCreation"],
    "isActive": true,
    "metadata": {
      "version": "1.0",
      "author": "System Admin",
      "tags": ["lending", "approval"]
    }
  }
}

Request Fields (data object)

Field	Type	Required	Default	Description
`name`	string	Yes	-	Unique name for the process definition
`description`	string	No	""	Human-readable description
`category`	string	No	"General"	Logical category for grouping (e.g., "Lending", "Customer Onboarding")
`bpmnXml`	string (XML)	Yes	-	Valid BPMN 2.0 XML definition
`contextLoaderType`	string	No	null	Type of context loader to use for variable initialization
`triggerEvents`	array	No	[]	System events that auto-trigger this process (e.g., `["OnLoanCreation", "OnDepositOpening"]`)
`isActive`	boolean	No	true	Whether process can be instantiated
`metadata`	object	No		Additional metadata (version, author, tags, etc.)

BPMN XML Validation

The system validates the BPMN XML for:

✅ Valid XML structure
✅ BPMN 2.0 schema compliance
✅ Required elements (process, start event, end event)
✅ Valid task types (userTask, serviceTask, scriptTask, etc.)
✅ Valid gateway types (exclusiveGateway, parallelGateway, etc.)
✅ Valid sequence flows
✅ Script task syntax (if using embedded scripts)
✅ Service task configuration (command names, parameters)

Response

{
  "isSuccessful": true,
  "message": "Process definition created successfully",
  "statusCode": "00",
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow",
    "category": "Lending",
    "version": 1,
    "isActive": true,
    "createdDate": "2026-01-06T10:30:00Z",
    "createdBy": "admin@bank.com",
    "triggerEvents": ["OnLoanCreation"],
    "contextLoaderType": "LoanApplicationContext",
    "elementCounts": {
      "totalElements": 15,
      "startEvents": 1,
      "endEvents": 2,
      "userTasks": 5,
      "serviceTasks": 3,
      "scriptTasks": 2,
      "gateways": 2
    }
  }
}

Response Fields

Field	Type	Description
`id`	long	Unique identifier for the process definition
`name`	string	Process definition name
`category`	string	Logical category
`version`	int	Version number (auto-incremented)
`isActive`	boolean	Activation status
`createdDate`	datetime	Creation timestamp
`createdBy`	string	User who created the definition
`triggerEvents`	array	Configured trigger events
`contextLoaderType`	string	Context loader type
`elementCounts`	object	Summary of BPMN elements

Supported BPMN Elements

Events

Start Event (startEvent) - Process entry point
End Event (endEvent) - Process completion point
Intermediate Throw Event (intermediateThrowEvent) - Signal/message throwing
Intermediate Catch Event (intermediateCatchEvent) - Signal/message catching
Timer Event (timerEvent) - Time-based triggers

Tasks

User Task (userTask) - Human interaction task
Service Task (serviceTask) - Automated system task
Script Task (scriptTask) - JavaScript/expression execution
Send Task (sendTask) - Message/notification sending
Receive Task (receiveTask) - Message/signal receiving

Gateways

Exclusive Gateway (exclusiveGateway) - XOR decision point
Parallel Gateway (parallelGateway) - Fork/join parallel flows
Inclusive Gateway (inclusiveGateway) - OR decision point
Event-Based Gateway (eventBasedGateway) - Event-driven routing

Other Elements

Subprocess (subProcess) - Embedded workflow
Call Activity (callActivity) - External workflow reference
Boundary Event (boundaryEvent) - Exception/timer on task
Sequence Flow (sequenceFlow) - Flow connections
Message Flow (messageFlow) - Cross-process communication

Trigger Events

Process definitions can be configured to automatically start when specific system events occur:

Trigger Event	Description	Use Case
`OnLoanCreation`	Fired when a loan account is created	Loan approval workflows
`OnDepositCreation`	Fired when a deposit account is created	Account opening workflows
`OnClientCreation`	Fired when a client is registered	KYC/onboarding workflows
`OnTransactionCreation`	Fired on any transaction	Fraud detection, notifications
`OnCashDeposit`	Fired on cash deposit transactions	Large deposit monitoring
`OnCashWithdrawal`	Fired on cash withdrawal transactions	Withdrawal limit checks
`OnLoanDisbursement`	Fired when loan is disbursed	Post-disbursement tasks
`OnLoanRepayment`	Fired on loan repayment	Repayment tracking

Context Loaders

Context loaders initialize process variables from entity data:

Context Loader	Entity Type	Available Variables
`LoanApplicationContext`	Loan Account	`loanId`, `amount`, `clientId`, `productId`, `branch`, `status`
`DepositAccountContext`	Deposit Account	`accountId`, `accountNumber`, `balance`, `clientId`, `productId`
`ClientContext`	Client	`clientId`, `clientCode`, `firstName`, `lastName`, `email`, `phone`
`TransactionContext`	Transaction	`transactionId`, `amount`, `type`, `accountId`, `reference`

Error Responses

Invalid BPMN XML

{
  "isSuccessful": false,
  "message": "Invalid BPMN XML: Start event 'StartEvent_1' is missing",
  "statusCode": "40",
  "data": {
    "validationErrors": [
      "Start event required",
      "End event 'EndEvent_1' has no incoming sequence flow"
    ]
  }
}

Duplicate Name

{
  "isSuccessful": false,
  "message": "Process definition with name 'Loan Approval Workflow' already exists",
  "statusCode": "40"
}

Example: Creating a Simple Approval Workflow

{
  "cmd": "CreateProcessDefinitiionCommand",
  "data": {
    "name": "Simple Approval",
    "description": "Basic approval workflow with 2 steps",
    "category": "General",
    "bpmnXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<definitions xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"
             xmlns:bpmndi=\"http://www.omg.org/spec/BPMN/20100524/DI\"
             targetNamespace=\"http://banklingo.com/bpmn\">
  <process id=\"SimpleApproval\" name=\"Simple Approval Process\">
    <startEvent id=\"StartEvent_1\" name=\"Start\"/>
    <userTask id=\"Task_Review\" name=\"Review Request\"/>
    <userTask id=\"Task_Approve\" name=\"Approve Request\"/>
    <endEvent id=\"EndEvent_1\" name=\"End\"/>
    
    <sequenceFlow id=\"Flow_1\" sourceRef=\"StartEvent_1\" targetRef=\"Task_Review\"/>
    <sequenceFlow id=\"Flow_2\" sourceRef=\"Task_Review\" targetRef=\"Task_Approve\"/>
    <sequenceFlow id=\"Flow_3\" sourceRef=\"Task_Approve\" targetRef=\"EndEvent_1\"/>
  </process>
</definitions>",
    "isActive": true
  }
}

Best Practices

✅ Do's

Use Descriptive Names: Process names should clearly indicate purpose
```
✅ "Loan Approval Workflow - SME Lending"
❌ "Process1"
```

Add Comprehensive Documentation: Use BPMN documentation elements

<userTask id="Task_1" name="Credit Check">
  <documentation>
    Perform comprehensive credit check including:
    - Credit bureau report
    - Internal scoring
    - Risk assessment
  </documentation>
</userTask>

Version Your Processes: Include version in metadata

{
  "name": "Loan Approval Workflow",
  "metadata": {
    "version": "2.1.0",
    "changelog": "Added automated credit checks"
  }
}

Use Categories: Organize processes logically
- Lending - Loan-related workflows
- Deposits - Deposit account workflows
- Compliance - Regulatory/compliance workflows
- Operations - Operational processes

Test Before Activation: Create as inactive, test thoroughly, then activate

{
  "name": "New Workflow",
  "isActive": false,  // Test first
  "bpmnXml": "..."
}

❌ Don'ts

Don't skip XML validation - Ensure valid BPMN before submission
Don't create duplicate definitions - Check existing processes first
Don't hardcode values - Use variables and context loaders
Don't create overly complex processes - Break into subprocesses
Don't forget error handling - Include boundary events and error flows

UpdateProcessDefinitionCommand - Update existing process
GetProcessDefinitionByIdQuery - View created process
GetContextLoadersQuery - List available context loaders
StartProcessInstanceCommand - Execute the created process

Last Updated: January 6, 2026

Overview​

Purpose​

Command Type​

Request​

Request Fields (data object)​

BPMN XML Validation​

Response​

Response Fields​

Supported BPMN Elements​

Events​

Tasks​

Gateways​

Other Elements​

Trigger Events​

Context Loaders​

Error Responses​

Invalid BPMN XML​

Duplicate Name​

Example: Creating a Simple Approval Workflow​

Best Practices​

✅ Do's​

❌ Don'ts​

Related Commands​