Process Trigger Commands Reference

Overview

Process Trigger Commands manage automatic process initiation based on business events. Triggers allow processes to start automatically when specific events occur in the system (e.g., loan created, customer updated, account closed).

What are Process Triggers?

Process Triggers are event-based automation rules that:

• Monitor System Events - Watch for specific business events
• Evaluate Conditions - Check if conditions are met before starting process
• Auto-Start Processes - Automatically initiate workflow processes
• Priority-Based Execution - Execute triggers in order of priority

Common Use Cases

• ✅ Loan Approval Workflow - Auto-start when loan application created
• ✅ Customer Onboarding - Start KYC process when new customer registered
• ✅ Account Monitoring - Trigger fraud check when suspicious transaction detected
• ✅ Compliance Workflows - Auto-start audit process when threshold exceeded
• ✅ Notification Processes - Send notifications on status changes

---

Commands Reference

AddProcessTriggerCommand

Add a new trigger to a Process Definition.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "processDefinitionId": 15,
  "entityType": 3,
  "eventType": 1,
  "condition": "loan.amount > 1000000 && loan.currency === 'NGN'",
  "name": "High Value Loan Trigger",
  "description": "Auto-start approval workflow for loans above 1M NGN",
  "priority": 10
}

Request Fields

Field	Type	Required	Default	Description
processDefinitionId	long	Yes	-	ID of process to trigger
entityType	int	Yes	-	Entity type (see Entity Types Reference below)
eventType	int	Yes	-	Event type (see Event Types table)
condition	string	No	null	JavaScript expression for conditional triggering
name	string	No	null	Display name for the trigger
description	string	No	null	Description of trigger purpose
priority	int	No	0	Execution priority (higher = earlier)

Single entity type rule: All triggers on a process definition must share the same entity type. If the process already has at least one active trigger with a different entity type, the request is rejected. This ensures the process engine loads consistent entity context and that ConflictPolicy checks (which are scoped to a single entity type) behave correctly.

Entity Type Conflict Error

If you attempt to add a trigger whose entityType differs from the entity type already established by existing triggers on that process:

{
  "isSuccessful": false,
  "message": "Cannot add a trigger for entity type 'Core Banking - Loan'. This process already has triggers for 'Contact'. All triggers on a process definition must share the same entity type."
}

To add triggers for a different entity type, either remove the existing triggers first or create a separate process definition for the new entity type.

Event Types

Type	Value	Description
Created	1	Entity created
Updated	2	Entity updated
Deleted	3	Entity deleted
Approved	4	Entity approved
Rejected	5	Entity rejected
Submitted	6	Entity submitted
Closed	7	Entity closed
Reopened	8	Entity reopened
Suspended	9	Entity suspended
Activated	10	Entity activated

Response

Success:

{
  "isSuccessful": true,
  "message": "Process trigger added successfully",
  "data": {
    "id": 123,
    "processDefinitionId": 15,
    "processDefinitionName": "High Value Loan Approval",
    "entityType": 3,
    "entityTypeName": "Loan",
    "eventType": 1,
    "eventTypeName": "Created",
    "condition": "loan.amount > 1000000 && loan.currency === 'NGN'",
    "name": "High Value Loan Trigger",
    "description": "Auto-start approval workflow for loans above 1M NGN",
    "priority": 10,
    "isActive": true,
    "createdAt": "2026-01-19T10:30:00Z"
  }
}

Error - Duplicate Trigger:

{
  "isSuccessful": false,
  "message": "A trigger with the same EntityType, EventType, and Condition already exists for this process."
}

---

RemoveProcessTriggerCommand

Remove a trigger from a Process Definition.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "id": 123
}

Response

Success:

{
  "isSuccessful": true,
  "message": "Process trigger removed successfully"
}

---

EnableProcessTriggerCommand

Enable a trigger (sets IsActive = true).

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "id": 123
}

Response

Success:

{
  "isSuccessful": true,
  "message": "Process trigger enabled successfully",
  "data": {
    "id": 123,
    "isActive": true,
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

---

DisableProcessTriggerCommand

Disable a trigger (sets IsActive = false).

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "id": 123
}

Response

Success:

{
  "isSuccessful": true,
  "message": "Process trigger disabled successfully",
  "data": {
    "id": 123,
    "isActive": false,
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

---

UpdateProcessTriggerCommand

Update an existing Process Trigger.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "id": 123,
  "entityType": 3,
  "eventType": 4,
  "condition": "loan.amount > 500000",
  "name": "Updated High Value Loan Trigger",
  "description": "Lowered threshold to 500K",
  "priority": 20
}

Request Fields

Field	Type	Required	Description
id	long	Yes	ID of trigger to update
entityType	int	No	Updated entity type
eventType	int	No	Updated event type
condition	string	No	Updated condition
name	string	No	Updated name
description	string	No	Updated description
priority	int	No	Updated priority

Response

Success:

{
  "isSuccessful": true,
  "message": "Process trigger updated successfully",
  "data": {
    "id": 123,
    "condition": "loan.amount > 500000",
    "name": "Updated High Value Loan Trigger",
    "priority": 20,
    "updatedAt": "2026-01-19T12:00:00Z"
  }
}

---

GetProcessTriggersQuery

Get all triggers for a specific Process Definition.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "processDefinitionId": 15,
  "includeInactive": false
}

Request Fields

Field	Type	Required	Default	Description
processDefinitionId	long	Yes	-	ID of process definition
includeInactive	bool	No	false	Include disabled triggers

Response

Success:

{
  "isSuccessful": true,
  "message": "Process triggers retrieved successfully",
  "data": [
    {
      "id": 123,
      "processDefinitionId": 15,
      "entityType": 3,
      "entityTypeName": "Loan",
      "eventType": 1,
      "eventTypeName": "Created",
      "condition": "loan.amount > 1000000",
      "name": "High Value Loan Trigger",
      "priority": 10,
      "isActive": true
    },
    {
      "id": 124,
      "processDefinitionId": 15,
      "entityType": 3,
      "entityTypeName": "Loan",
      "eventType": 4,
      "eventTypeName": "Approved",
      "condition": null,
      "name": "Loan Approved Trigger",
      "priority": 5,
      "isActive": true
    }
  ]
}

---

GetTriggersByEventTypeQuery

Get triggers by event type and optionally entity type.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "eventType": 1,
  "entityType": 3,
  "includeInactive": false
}

Request Fields

Field	Type	Required	Default	Description
eventType	int	Yes	-	Event type to filter by
entityType	int	No	null	Entity type to filter by
includeInactive	bool	No	false	Include disabled triggers

Response

Success:

{
  "isSuccessful": true,
  "message": "Triggers retrieved successfully",
  "data": [
    {
      "id": 123,
      "processDefinitionId": 15,
      "processDefinitionName": "High Value Loan Approval",
      "entityType": 3,
      "entityTypeName": "Loan",
      "eventType": 1,
      "eventTypeName": "Created",
      "condition": "loan.amount > 1000000",
      "priority": 10,
      "isActive": true
    },
    {
      "id": 125,
      "processDefinitionId": 18,
      "processDefinitionName": "Customer Onboarding",
      "entityType": 3,
      "entityTypeName": "Loan",
      "eventType": 1,
      "eventTypeName": "Created",
      "condition": null,
      "priority": 5,
      "isActive": true
    }
  ]
}

---

GetProcessTriggerByIdQuery

Get a single trigger by ID.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{
  "id": 123
}

Response

Success:

{
  "isSuccessful": true,
  "message": "Process trigger retrieved successfully",
  "data": {
    "id": 123,
    "processDefinitionId": 15,
    "processDefinitionName": "High Value Loan Approval",
    "processDefinitionCode": "high_value_loan_approval",
    "entityType": 3,
    "entityTypeName": "Loan",
    "eventType": 1,
    "eventTypeName": "Created",
    "condition": "loan.amount > 1000000 && loan.currency === 'NGN'",
    "name": "High Value Loan Trigger",
    "description": "Auto-start approval workflow for loans above 1M NGN",
    "priority": 10,
    "isActive": true,
    "createdAt": "2026-01-19T10:30:00Z",
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

---

GetEntityEventMappingsQuery

Get all entity types and their associated event types.

File: CB.Administration.Api/Commands/BPM/Process/ProcessDefinitionTriggerCommands.cs

Request

{}

No parameters required.

Response

Success:

{
  "isSuccessful": true,
  "message": "Entity-Event mappings retrieved successfully",
  "data": {
    "entityTypes": [
      {
        "value": 1,
        "name": "Customer",
        "availableEvents": [1, 2, 3, 9, 10]
      },
      {
        "value": 2,
        "name": "Account",
        "availableEvents": [1, 2, 3, 7, 8, 9, 10]
      },
      {
        "value": 3,
        "name": "Loan",
        "availableEvents": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
      },
      {
        "value": 4,
        "name": "Transaction",
        "availableEvents": [1, 4, 5]
      }
    ],
    "eventTypes": [
      {"value": 1, "name": "Created"},
      {"value": 2, "name": "Updated"},
      {"value": 3, "name": "Deleted"},
      {"value": 4, "name": "Approved"},
      {"value": 5, "name": "Rejected"},
      {"value": 6, "name": "Submitted"},
      {"value": 7, "name": "Closed"},
      {"value": 8, "name": "Reopened"},
      {"value": 9, "name": "Suspended"},
      {"value": 10, "name": "Activated"}
    ]
  }
}

---

Entity Types

Type	Value	Description	Common Events
Customer	1	Customer/Client entities	Created, Updated, Deleted, Suspended, Activated
Account	2	Account entities	Created, Updated, Closed, Reopened, Suspended, Activated
Loan	3	Loan applications	Created, Updated, Submitted, Approved, Rejected, Closed
Transaction	4	Transactions	Created, Approved, Rejected

---

Conditional Triggering

Triggers can have conditions that must evaluate to true before the process starts.

Condition Syntax

Conditions use JavaScript expression syntax:

// Simple comparison
loan.amount > 1000000

// Multiple conditions
loan.amount > 1000000 && loan.currency === 'NGN'

// Complex logic
(loan.amount > 1000000 || loan.loanType === 'corporate') && loan.status === 'pending'

// Property checks
customer.creditScore < 600 && customer.accountAge < 12

// Null checks
loan.collateral !== null && loan.collateral.value > 500000

Available Context

The entity object is available in the condition:

// For Loan triggers
loan.amount
loan.currency
loan.loanType
loan.status
loan.customerId
loan.productCode

// For Customer triggers
customer.firstName
customer.lastName
customer.email
customer.creditScore
customer.kycStatus

// For Account triggers
account.accountNumber
account.balance
account.accountType
account.status
account.customerId

// For Transaction triggers
transaction.amount
transaction.transactionType
transaction.accountId
transaction.status

---

Priority-Based Execution

When multiple triggers match an event, they execute in priority order (highest first).

Example

[
  {
    "name": "Critical Alert Trigger",
    "priority": 100,
    "condition": "loan.amount > 10000000"
  },
  {
    "name": "High Value Trigger",
    "priority": 50,
    "condition": "loan.amount > 1000000"
  },
  {
    "name": "Standard Trigger",
    "priority": 10,
    "condition": "loan.amount > 0"
  }
]

Execution Order:

1. Critical Alert Trigger (priority 100) - if condition matches
2. High Value Trigger (priority 50) - if condition matches
3. Standard Trigger (priority 10) - if condition matches

---

Best Practices

1. Use Descriptive Names

✅ GOOD:

{
  "name": "High Value Loan Approval Trigger",
  "description": "Auto-start executive approval for loans over 1M NGN"
}

❌ BAD:

{
  "name": "Trigger 1",
  "description": null
}

2. Keep Conditions Simple

✅ GOOD:

loan.amount > 1000000 && loan.currency === 'NGN'

❌ BAD:

((loan.amount > 1000000 && loan.currency === 'NGN') || (loan.amount > 50000 && loan.loanType === 'personal' && customer.creditScore < 600)) && loan.status !== 'rejected' && loan.collateral !== null

3. Set Appropriate Priorities

• 100+ Critical/Emergency processes
• 50-99 High priority processes
• 10-49 Normal priority processes
• 1-9 Low priority/background processes
• 0 Default priority

4. Test Conditions Thoroughly

Before deploying:

• Test with edge cases
• Verify null handling
• Check performance impact
• Validate against actual data

5. Document Trigger Logic

Always provide clear description:

{
  "name": "Fraud Detection Trigger",
  "description": "Auto-start fraud investigation process when transaction amount exceeds 100K or is from blacklisted IP",
  "condition": "transaction.amount > 100000 || transaction.ipBlacklisted === true"
}

---

Integration Examples

Example 1: Loan Approval Workflow

Automatically start approval workflow when high-value loan is created:

POST /api/commands/execute
{
  "commandName": "AddProcessTriggerCommand",
  "data": {
    "processDefinitionId": 15,
    "entityType": 3,
    "eventType": 1,
    "condition": "loan.amount > 1000000",
    "name": "High Value Loan Approval",
    "description": "Requires executive approval",
    "priority": 50
  }
}

Example 2: Customer KYC Process

Start KYC verification when new customer is created:

POST /api/commands/execute
{
  "commandName": "AddProcessTriggerCommand",
  "data": {
    "processDefinitionId": 22,
    "entityType": 1,
    "eventType": 1,
    "condition": "customer.kycStatus === 'pending'",
    "name": "Customer KYC Verification",
    "priority": 80
  }
}

Example 3: Account Closure Notification

Send notifications when account is closed:

POST /api/commands/execute
{
  "commandName": "AddProcessTriggerCommand",
  "data": {
    "processDefinitionId": 8,
    "entityType": 2,
    "eventType": 7,
    "condition": "account.balance === 0",
    "name": "Account Closure Notification",
    "priority": 10
  }
}

---

Error Handling

Common Errors

Process Definition Not Found:

{
  "isSuccessful": false,
  "message": "ProcessDefinition with ID 15 not found."
}

Duplicate Trigger:

{
  "isSuccessful": false,
  "message": "A trigger with the same EntityType, EventType, and Condition already exists for this process."
}

Invalid Entity Type:

{
  "isSuccessful": false,
  "message": "Invalid entity type: 99. Valid values are 1-4."
}

Invalid Event Type:

{
  "isSuccessful": false,
  "message": "Invalid event type: 99 for entity type 3."
}

Invalid Condition Syntax:

{
  "isSuccessful": false,
  "message": "Condition syntax error: Unexpected token"
}

---

Entity Types Reference

The entityType field determines which business entity a process trigger watches for events. Use the integer value when creating or filtering triggers.

Core Banking Entities

Value	Alias	Description	Common Events
0	none	Not Associated	System events
1	entity	Generic Entity	Generic operations
2	contact	Contact	Contact.Created, Contact.Updated
3	loan	Loan	Loan.Created, Loan.Approved, Loan.Disbursed
4	deposit	Deposit	Deposit.Created, Deposit.Activated
5	insurancePolicy	Insurance Policy	Policy.Created, Policy.Renewed
6	insuranceClaim	Insurance Claims	Claim.Submitted, Claim.Approved
11	transaction	Transaction	Transaction.Posted, Transaction.Reversed

Channel Entities

Value	Alias	Description	Common Events
100	customerRegistration	Customer	Customer.Registered, Customer.Verified
101	loanRequest	Loan Request	LoanRequest.Submitted, LoanRequest.Approved
102	transferRequest	Transfer Request	Transfer.Initiated, Transfer.Completed
103	billsPaymentRequest	Bills Payment Request	BillPayment.Submitted
104	airtimeRechargeRequest	Airtime Recharge Request	Recharge.Completed
105	dataRechargeRequest	Data Recharge Request	DataRecharge.Completed

Operations Entities

Value	Alias	Description	Common Events
200	reconciliation	Reconciliation	Reconciliation.Started, Reconciliation.Completed
13	teller	Teller Transaction	Teller.Transaction.Posted
14	inwardTransaction	Inward Transaction	InwardTx.Received

System Entities

Value	Alias	Description	Common Events
15	scheduledProcess	Scheduled Process	Schedule.Triggered

Examples

Trigger on High-Value Loan Creation:

{
  "processDefinitionId": 15,
  "entityType": 3,  // Loan entity
  "eventType": 1,   // Created event
  "condition": "loan.amount > 1000000",
  "name": "High Value Loan Review Trigger"
}

Trigger on Customer Registration:

{
  "processDefinitionId": 22,
  "entityType": 100,  // Customer entity
  "eventType": 1,     // Created event
  "name": "Customer Onboarding Trigger"
}

Trigger on Transfer Request Completion:

{
  "processDefinitionId": 18,
  "entityType": 102,  // Transfer Request entity
  "eventType": 3,     // Completed event
  "condition": "transfer.amount > 100000",
  "name": "Large Transfer Notification"
}

---

Monitoring and Debugging

Check Trigger Execution

Monitor trigger execution in process instance data:

{
  "processInstanceId": 5678,
  "triggerId": 123,
  "triggerName": "High Value Loan Trigger",
  "triggeredAt": "2026-01-19T14:30:00Z",
  "entityId": 12345,
  "entityType": "Loan"
}

Trigger Logs

Check system logs for trigger evaluation:

[INFO] Evaluating trigger 123 for Loan 12345
[INFO] Condition: loan.amount > 1000000
[INFO] Result: true
[INFO] Starting process definition 15 for entity 12345

---

See Also

• Process Administration Commands - Process definition management
• Process Execution Commands - Process instance lifecycle
• Event Context Standards - Event data structure
• Variables Guide - Working with process variables

---

Last Updated: January 19, 2026
Version: 1.0