Process Administration Commands

Overview

Process Administration Commands manage the lifecycle of process definitions (BPMN workflows) in the BankLingo BPM Engine. These commands handle creating, updating, deleting, querying, and configuring workflows. This is separate from Process Execution Commands which manage running process instances.

Each command has its own dedicated documentation page with complete request/response examples, use cases, and best practices.

Command Categories

📝 Process Definition Management

Commands for creating, updating, and managing process definitions.

CreateProcessDefinitionCommand - Create a new process definition from BPMN XML
UpdateProcessDefinitionCommand - Update an existing process definition with versioning
DeleteProcessDefinitionCommand - Delete a process definition
RenameProcessDefinitionCommand - Rename a process without versioning

🔍 Process Definition Queries

Commands for retrieving process definition information.

GetProcessDefinitionByIdQuery - Get a single process definition with full details
GetProcessDefinitionListQuery - Get paginated list of process definitions with filtering
GetProcessBundleQuery - Get complete process package with dependencies

🔧 Configuration & Setup

Commands for process configuration and context management.

GetContextLoadersQuery - List available context loaders for variable initialization
UpdateSchedulingInformationCommand - Configure scheduled process execution

Command Matrix

Quick reference for when to use each command:

Task	Command	Frequency
Create new workflow	CreateProcessDefinitionCommand	As needed
Update workflow logic	UpdateProcessDefinitionCommand	Monthly
Just rename workflow	RenameProcessDefinitionCommand	As needed
Delete workflow	DeleteProcessDefinitionCommand	Rarely
View single workflow	GetProcessDefinitionByIdQuery	Very frequently
List all workflows	GetProcessDefinitionListQuery	Very frequently
Export workflow	GetProcessBundleQuery	As needed
Schedule workflow	UpdateSchedulingInformationCommand	As needed
See available contexts	GetContextLoadersQuery	During design

Typical Workflows

Creating a New Process

GetContextLoadersQuery - Determine available variables
Design BPMN using available variables
CreateProcessDefinitionCommand - Upload process
GetProcessDefinitionByIdQuery - Verify creation
Test process in development
Update isActive: true to enable

Updating an Existing Process

GetProcessDefinitionByIdQuery - Get current version
GetProcessInstanceListQuery - Check active instances
Update BPMN XML
UpdateProcessDefinitionCommand - Deploy new version
Monitor active instances on old version
Wait for completion or gracefully migrate

Deleting a Process

GetProcessDefinitionByIdQuery - Check status
UpdateProcessDefinitionCommand - Set isActive: false
GetProcessInstanceListQuery - Verify no active instances
Cancel/complete any remaining instances
DeleteProcessDefinitionCommand - Delete safely

Scheduling a Process

GetProcessDefinitionByIdQuery - Get process details
Design cron expression for schedule
UpdateSchedulingInformationCommand - Configure schedule
GetProcessInstanceListQuery - Monitor scheduled executions

Best Practices Summary

✅ Process Definition Do's

Use clear, descriptive names - "SME Loan Approval Workflow" not "Process1"
Add comprehensive documentation - Use BPMN documentation elements
Version your processes - Include version in metadata
Test before activating - Create as isActive: false, test thoroughly
Use categories wisely - Group related processes (Lending, Deposits, Compliance)
Include context loaders - Auto-initialize variables from entities
Configure triggers appropriately - Auto-start on relevant events
Monitor active instances - Before updating or deleting
Use scheduling for batch jobs - Automate recurring processes
Export/backup definitions - Use GetProcessBundleQuery regularly

❌ Process Definition Don'ts

Don't force delete with active instances - Cancel instances first
Don't update without versioning - Track changes properly
Don't create duplicate definitions - Check existing first
Don't skip BPMN validation - Ensure valid BPMN 2.0
Don't ignore breaking changes - Review impact on running instances
Don't over-schedule - Avoid too many concurrent scheduled jobs
Don't hardcode values - Use variables and context loaders
Don't create overly complex processes - Break into subprocesses
Don't skip testing - Test with real data before production
Don't forget error handling - Include boundary events and error flows

Process Execution Commands - Managing running process instances
Event-Driven Process Architecture - Trigger events and context loaders
BPMN Process Modeling Guide - Creating BPMN workflows
Process Engine Architecture - Understanding the BPM engine

Support & Troubleshooting

Common Issues

Process Won't Start:

Check isActive: true
Verify BPMN has start event
Check trigger event configuration
Verify context loader setup

Process Update Failed:

Validate BPMN XML
Check for breaking changes
Verify no active instances (if needed)
Check permissions

Schedule Not Triggering:

Verify schedulingEnabled: true
Check cron expression validity
Verify timezone configuration
Check Hangfire background server status

Process Deletion Blocked:

Check for active instances
Look for call activity references
Verify no scheduled executions
Check trigger event configurations

Last Updated: January 6, 2026
Version: 1.0

Request

{
  "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

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

{
  "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

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": "..."
}

UpdateProcessDefinitiionCommand

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.

Request

{
  "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

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

Response

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

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",
  "data": {
    "breakingChanges": [
      "Start event 'StartEvent_1' removed",
      "User task 'Task_Approve' references removed"
    ]
  }
}

DeleteProcessDefinitiionCommand

Deletes a process definition.

Purpose

Removes a process definition from the system. Only allowed if no active instances exist.

Request

{
  "id": 456,
  "force": false  // Set true to force deletion even with active instances
}

Request Fields

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 caution)

Response

{
  "isSuccessful": true,
  "message": "Process definition deleted successfully",
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow",
    "instancesDeleted": 0
  }
}

Error Responses

Has Active Instances

{
  "isSuccessful": false,
  "message": "Cannot delete: Process has 3 active instances",
  "statusCode": "40",
  "data": {
    "activeInstances": 3,
    "instanceIds": ["guid1", "guid2", "guid3"],
    "suggestion": "Use force=true to delete anyway or wait for instances to complete"
  }
}

Safety Notes

⚠️ Use force=true with extreme caution:

Deleting a definition with active instances will orphan those instances
Orphaned instances cannot be resumed or managed
Consider canceling instances first using CancelProcessInstanceCommand

RenameProcessDefinitiionCommand

Renames a process definition without creating a new version.

Purpose

Changes the display name of a process definition while keeping the same ID and version.

Request

{
  "id": 456,
  "newName": "SME Loan Approval Workflow"
}

Request Fields

Field	Type	Required	Description
`id`	long	Yes	ID of process definition to rename
`newName`	string	Yes	New name for the process

Response

{
  "isSuccessful": true,
  "message": "Process definition renamed successfully",
  "data": {
    "id": 456,
    "oldName": "Loan Approval Workflow",
    "newName": "SME Loan Approval Workflow",
    "version": 2  // Version unchanged
  }
}

Use Case

Use this instead of UpdateProcessDefinitiionCommand when you only want to change the display name without creating a new version:

✅ Renaming for clarity without functional changes
❌ Changing BPMN logic (use UpdateProcessDefinitiionCommand)

GetProcessDefinitiionByIdQuery

Retrieves a single process definition by ID.

Purpose

Gets complete details of a specific process definition including BPMN XML and metadata.

Request

{
  "id": 456,
  "includeXml": true,  // Include full BPMN XML in response
  "includeStatistics": true  // Include instance statistics
}

Request Fields

Field	Type	Required	Default	Description
`id`	long	Yes	-	ID of process definition to retrieve
`includeXml`	boolean	No	false	Include full BPMN XML in response
`includeStatistics`	boolean	No	false	Include instance count statistics

Response

{
  "isSuccessful": true,
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow",
    "description": "Multi-stage loan approval process",
    "category": "Lending",
    "version": 2,
    "isActive": true,
    "createdDate": "2026-01-06T10:30:00Z",
    "updatedDate": "2026-01-10T15:45:00Z",
    "createdBy": "admin@bank.com",
    "updatedBy": "manager@bank.com",
    "triggerEvents": ["OnLoanCreation"],
    "contextLoaderType": "LoanApplicationContext",
    "bpmnXml": "<?xml version=\"1.0\"...",  // Only if includeXml=true
    "statistics": {  // Only if includeStatistics=true
      "totalInstances": 150,
      "activeInstances": 12,
      "completedInstances": 135,
      "failedInstances": 3,
      "averageDurationMinutes": 180
    },
    "elementCounts": {
      "totalElements": 15,
      "userTasks": 5,
      "serviceTasks": 3,
      "scriptTasks": 2,
      "gateways": 2
    }
  }
}

GetProcessDefinitiionListQuery

Retrieves paginated list of process definitions.

Purpose

Lists all process definitions with filtering, searching, and pagination.

Request

{
  "pageNumber": 1,
  "pageSize": 20,
  "searchText": "loan",  // Search in name/description
  "category": "Lending",  // Filter by category
  "isActive": true,  // Filter by active status
  "sortBy": "name",  // Sort field
  "sortDirection": "asc"  // Sort direction
}

Request Fields

Field	Type	Required	Default	Description
`pageNumber`	int	No	1	Page number (1-based)
`pageSize`	int	No	20	Items per page (max 100)
`searchText`	string	No	null	Search in name/description
`category`	string	No	null	Filter by category
`isActive`	boolean	No	null	Filter by active status (null = all)
`sortBy`	string	No	"name"	Sort field: `name`, `category`, `createdDate`, `version`
`sortDirection`	string	No	"asc"	Sort direction: `asc` or `desc`

Response

{
  "isSuccessful": true,
  "data": {
    "items": [
      {
        "id": 456,
        "name": "Loan Approval Workflow",
        "category": "Lending",
        "version": 2,
        "isActive": true,
        "createdDate": "2026-01-06T10:30:00Z",
        "triggerEvents": ["OnLoanCreation"],
        "activeInstanceCount": 5
      },
      {
        "id": 789,
        "name": "SME Loan Processing",
        "category": "Lending",
        "version": 1,
        "isActive": true,
        "createdDate": "2026-01-08T14:20:00Z",
        "triggerEvents": [],
        "activeInstanceCount": 0
      }
    ],
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 3,
    "totalRecords": 45
  }
}

Filtering Examples

Get all active processes:

{
  "isActive": true,
  "pageSize": 100
}

Get processes by category:

{
  "category": "Compliance",
  "sortBy": "createdDate",
  "sortDirection": "desc"
}

Search for specific processes:

{
  "searchText": "approval",
  "isActive": true
}

GetProcessBundleQuery

Retrieves complete process definition package with all metadata and dependencies.

Purpose

Gets a comprehensive "bundle" of process definition information including BPMN, context loaders, trigger configurations, and related metadata.

Request

{
  "processDefinitionId": 456,
  "includeInstances": true,  // Include sample instances
  "includeRelatedDefinitions": true  // Include related/called processes
}

Request Fields

Field	Type	Required	Default	Description
`processDefinitionId`	long	Yes	-	ID of process definition
`includeInstances`	boolean	No	false	Include recent process instances
`includeRelatedDefinitions`	boolean	No	false	Include definitions called by this process

Response

{
  "isSuccessful": true,
  "data": {
    "processDefinition": {
      "id": 456,
      "name": "Loan Approval Workflow",
      "version": 2,
      "bpmnXml": "<?xml version...\"",
      "category": "Lending"
    },
    "contextLoader": {
      "type": "LoanApplicationContext",
      "availableVariables": [
        { "name": "loanId", "type": "long", "description": "Loan account ID" },
        { "name": "amount", "type": "decimal", "description": "Loan amount" },
        { "name": "clientId", "type": "long", "description": "Client ID" }
      ]
    },
    "triggerConfiguration": {
      "events": ["OnLoanCreation"],
      "autoStart": true,
      "conditions": "loanAmount > 50000"  // Optional trigger condition
    },
    "recentInstances": [  // Only if includeInstances=true
      {
        "instanceId": "guid1",
        "businessKey": "LOAN-001",
        "status": "COMPLETED",
        "startTime": "2026-01-10T09:00:00Z",
        "endTime": "2026-01-10T12:30:00Z"
      }
    ],
    "relatedDefinitions": [  // Only if includeRelatedDefinitions=true
      {
        "id": 123,
        "name": "Credit Check Subprocess",
        "relationship": "CallActivity"
      }
    ]
  }
}

Use Cases

Export/Import: Get complete process package for backup or migration
Documentation: Generate comprehensive process documentation
Debugging: Understand all process dependencies and configurations
Deployment: Bundle all required components for deployment

GetContextLoadersQuery

Retrieves list of available context loaders for process variable initialization.

Purpose

Lists all context loader types that can be used to automatically initialize process variables from entity data.

Request

{
  "category": "Lending"  // Optional: filter by category
}

Response

{
  "isSuccessful": true,
  "data": {
    "contextLoaders": [
      {
        "type": "LoanApplicationContext",
        "category": "Lending",
        "description": "Loads loan account data into process variables",
        "entityType": "LoanAccount",
        "requiredFields": ["loanId"],
        "variables": [
          {
            "name": "loanId",
            "type": "long",
            "description": "Loan account ID",
            "required": true
          },
          {
            "name": "amount",
            "type": "decimal",
            "description": "Loan amount requested"
          },
          {
            "name": "clientId",
            "type": "long",
            "description": "Associated client ID"
          },
          {
            "name": "productId",
            "type": "long",
            "description": "Loan product ID"
          },
          {
            "name": "branch",
            "type": "object",
            "description": "Branch information"
          },
          {
            "name": "status",
            "type": "string",
            "description": "Loan application status"
          }
        ]
      },
      {
        "type": "DepositAccountContext",
        "category": "Deposits",
        "description": "Loads deposit account data",
        "entityType": "DepositAccount",
        "requiredFields": ["accountId"],
        "variables": [
          {
            "name": "accountId",
            "type": "long",
            "description": "Deposit account ID",
            "required": true
          },
          {
            "name": "accountNumber",
            "type": "string",
            "description": "Account number"
          },
          {
            "name": "balance",
            "type": "decimal",
            "description": "Current account balance"
          }
        ]
      }
    ]
  }
}

Use Case

When creating a process definition, query available context loaders to determine what variables will be available:

// 1. Get available context loaders
const loaders = await getContextLoaders({ category: "Lending" });

// 2. Choose appropriate loader
const loanLoader = loaders.contextLoaders.find(l => l.type === "LoanApplicationContext");

// 3. Use loader's variables in BPMN process
// Now you know you have access to: loanId, amount, clientId, productId, etc.

// 4. Create process definition with chosen loader
await createProcessDefinition({
  name: "My Loan Process",
  contextLoaderType: "LoanApplicationContext",
  bpmnXml: "..." // Can reference ${loanId}, ${amount}, etc.
});

UpdateSchedulingInformationCommand

Configures scheduled execution of a process definition.

Purpose

Sets up recurring or scheduled automatic execution of a process, useful for batch jobs, periodic reports, or maintenance workflows.

Request

{
  "processDefinitionId": 456,
  "schedulingEnabled": true,
  "cronExpression": "0 0 2 * * ?",  // Every day at 2 AM
  "timezone": "Africa/Lagos",
  "variables": {
    "reportDate": "${today}",
    "batchSize": 100
  },
  "maxConcurrentInstances": 1,  // Prevent overlapping runs
  "description": "Daily loan portfolio report generation"
}

Request Fields

Field	Type	Required	Default	Description
`processDefinitionId`	long	Yes	-	ID of process definition to schedule
`schedulingEnabled`	boolean	No	false	Enable/disable scheduling
`cronExpression`	string	Yes (if enabled)	-	Cron expression for schedule
`timezone`	string	No	"UTC"	Timezone for schedule
`variables`	object	No		Default variables for scheduled instances
`maxConcurrentInstances`	int	No	1	Maximum concurrent instances allowed
`description`	string	No	""	Description of schedule purpose

Cron Expression Format

Standard cron format: second minute hour day month dayOfWeek

Examples:

"0 0 2 * * ?"        // Every day at 2:00 AM
"0 */15 * * * ?"     // Every 15 minutes
"0 0 9 * * MON-FRI"  // Every weekday at 9:00 AM
"0 0 0 1 * ?"        // First day of every month at midnight
"0 30 23 * * SUN"    // Every Sunday at 11:30 PM

Response

{
  "isSuccessful": true,
  "message": "Scheduling configured successfully",
  "data": {
    "processDefinitionId": 456,
    "schedulingEnabled": true,
    "cronExpression": "0 0 2 * * ?",
    "nextRunTime": "2026-01-07T02:00:00Z",
    "timezone": "Africa/Lagos",
    "jobId": "recurring_job_456"
  }
}

Response Fields

Field	Type	Description
`processDefinitionId`	long	ID of scheduled process
`schedulingEnabled`	boolean	Whether scheduling is active
`cronExpression`	string	Configured cron expression
`nextRunTime`	datetime	Next scheduled execution time
`timezone`	string	Timezone used
`jobId`	string	Hangfire job ID for monitoring

Use Cases

Daily Reports: Generate end-of-day reports

{
  "cronExpression": "0 0 23 * * ?",  // 11 PM daily
  "variables": { "reportType": "daily_summary" }
}

Monthly Processing: Run month-end procedures

{
  "cronExpression": "0 0 1 1 * ?",  // 1 AM on 1st of month
  "variables": { "processType": "month_end" }
}

Periodic Maintenance: Regular cleanup tasks

{
  "cronExpression": "0 0 3 * * SUN",  // 3 AM every Sunday
  "variables": { "retentionDays": 90 }
}

Real-time Monitoring: Frequent checks

{
  "cronExpression": "0 */5 * * * ?",  // Every 5 minutes
  "maxConcurrentInstances": 3
}

Disabling Scheduled Execution

To stop scheduled execution without deleting the configuration:

{
  "processDefinitionId": 456,
  "schedulingEnabled": false
}

The configuration is preserved and can be re-enabled later.

Summary: Command Usage Matrix

Task	Command	Typical Frequency
Create new workflow	`CreateProcessDefinitiionCommand`	As needed
Update workflow logic	`UpdateProcessDefinitiionCommand`	Monthly
Just rename workflow	`RenameProcessDefinitiionCommand`	As needed
Delete workflow	`DeleteProcessDefinitiionCommand`	Rarely
View single workflow	`GetProcessDefinitiionByIdQuery`	Frequently
List all workflows	`GetProcessDefinitiionListQuery`	Very frequently
Export workflow	`GetProcessBundleQuery`	As needed
Schedule workflow	`UpdateSchedulingInformationCommand`	As needed
See available contexts	`GetContextLoadersQuery`	During design

Process Execution Commands - Managing running process instances
Event-Driven Process Architecture - Trigger events and context loaders
BPMN Process Modeling Guide - Creating BPMN workflows

Best Practices Summary

✅ Do's

Use clear, descriptive names - "Loan Approval - SME" not "Process1"
Add comprehensive documentation - Use BPMN documentation elements
Version your processes - Include version info in metadata
Test before activating - Create as inactive, test thoroughly
Use categories wisely - Group related processes logically
Include context loaders - Auto-initialize variables from entities
Configure triggers appropriately - Auto-start on relevant events
Monitor active instances - Before updating or deleting
Use scheduling for batch jobs - Automate recurring processes
Export/backup definitions - Use GetProcessBundleQuery regularly

❌ Don'ts

Don't force delete with active instances - Cancel instances first
Don't update without versioning - Track changes properly
Don't create duplicate definitions - Check existing first
Don't skip XML validation - Ensure valid BPMN
Don't ignore breaking changes - Review impact on running instances
Don't over-schedule - Avoid too many concurrent scheduled jobs
Don't hardcode values - Use variables and context loaders
Don't create overly complex processes - Break into subprocesses
Don't skip testing - Test with real data before production
Don't forget error handling - Include boundary events and error flows

Last Updated: January 6, 2026
Version: 1.0

Overview​

Quick Navigation​

Command Categories​

📝 Process Definition Management​

🔍 Process Definition Queries​

🔧 Configuration & Setup​

Command Matrix​

Typical Workflows​

Creating a New Process​

Updating an Existing Process​

Deleting a Process​

Scheduling a Process​

Best Practices Summary​

✅ Process Definition Do's​

❌ Process Definition Don'ts​

Related Documentation​

Support & Troubleshooting​

Common Issues​

Request​

Request Fields​

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​

UpdateProcessDefinitiionCommand​

Purpose​

Request​

Request Fields​

Versioning Behavior​

Response​

Error Responses​

Process Definition Not Found​

Invalid Update (Breaking Change)​

DeleteProcessDefinitiionCommand​

Purpose​

Request​

Request Fields​

Response​

Error Responses​

Has Active Instances​

Safety Notes​

RenameProcessDefinitiionCommand​

Purpose​

Request​

Request Fields​

Response​

Use Case​

GetProcessDefinitiionByIdQuery​

Purpose​

Request​

Request Fields​

Response​

GetProcessDefinitiionListQuery​

Purpose​

Request​

Request Fields​

Response​

Filtering Examples​

GetProcessBundleQuery​

Purpose​

Request​

Request Fields​

Response​

Use Cases​

GetContextLoadersQuery​

Purpose​

Request​

Response​

Use Case​

Overview

Quick Navigation

Command Categories

📝 Process Definition Management

🔍 Process Definition Queries

🔧 Configuration & Setup

Command Matrix

Typical Workflows

Creating a New Process

Updating an Existing Process

Deleting a Process

Scheduling a Process

Best Practices Summary

✅ Process Definition Do's

❌ Process Definition Don'ts

Related Documentation

Support & Troubleshooting

Common Issues

Request

Request Fields

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

UpdateProcessDefinitiionCommand

Purpose

Request

Request Fields

Versioning Behavior

Response

Error Responses

Process Definition Not Found

Invalid Update (Breaking Change)

DeleteProcessDefinitiionCommand

Purpose

Request

Request Fields

Response

Error Responses

Has Active Instances

Safety Notes

RenameProcessDefinitiionCommand

Purpose

Request

Request Fields

Response

Use Case

GetProcessDefinitiionByIdQuery

Purpose

Request

Request Fields

Response

GetProcessDefinitiionListQuery

Purpose

Request

Request Fields

Response

Filtering Examples

GetProcessBundleQuery

Purpose

Request

Request Fields

Response

Use Cases

GetContextLoadersQuery

Purpose

Request

Response

Use Case