Event Context Naming Standards

Overview

This document defines the standardized naming conventions for all event context dictionaries dispatched through the ProcessEventDispatcher service. These standards ensure consistency across all entity types and make BPM process definitions easier to write and maintain.

Last Updated: December 23, 2024
Status: âœ… Fully Implemented (26 dispatch points across 10 handlers)

Why Standardization Matters

Before Standardization âŒ

// Inconsistent field names across entities
if (context.loanStatus === "Active") { }
if (context.rechargeStatus === "SUCCESSFUL") { }
if (context.transferStatus === "Pending") { }
if (context.reconciliationStatus === "Manual") { }

Problems:

BPM developers must remember entity-specific field names
Generic process logic cannot be reused
Documentation becomes entity-specific

After Standardization âœ…

// Consistent field names across ALL entities
if (context.status === 2) { }  // Numeric comparison (fast)
if (context.statusDescription === "SUCCESSFUL") { }  // String for display

Benefits:

Consistent naming across all 26 dispatch points
Generic BPM process templates work across entity types
Type-safe numeric comparisons
Clear documentation with enum mappings

Core Principles

1. Status Field Naming

Rule: All status-related fields must be named status (or accountStatus for account entities), NOT entity-specific names.

âœ… Correct:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

âŒ Incorrect:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Rationale:

Consistent naming across all entities
Simplified BPM condition logic
Easier documentation and training

2. Enum Value Convention

Rule: Always send BOTH the integer enum value AND a human-readable description.

Format:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Example:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Benefits:

Performance: Numeric comparisons faster than string comparisons
Type Safety: BPM conditions use integers (compile-time checking)
Flexibility: Description available for logging, UI display, debugging
Future-Proof: Easy to add new enum values without breaking existing processes

3. Account Number Naming

Rule: Use accountNumber consistently, NOT entity-specific variations.

âœ… Correct:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

âŒ Incorrect:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

4. Transaction Commit Order

Rule: ALWAYS ensure database transaction is committed BEFORE dispatching events.

âœ… Correct:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

âŒ Incorrect:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Rationale:

Processes query database for entity data
Dispatching before commit creates race conditions
Failed commits after dispatch create inconsistent state

Entity-Specific Implementations

1. Contact (Customer) Events

Handler: AdministrationCoreContactCommandHandlers.cs
Event: OnCustomerCreation
Entity Type: Contact (2)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Status Enum: ClientState

Pending = 0 - Awaiting KYC verification
Active = 1 - Fully onboarded
Inactive = 2 - Temporarily disabled
Rejected = 3 - Failed KYC
Blacklisted = 4 - Restricted for fraud/compliance

Type Enum: ClientType.Id (from lookup table)

Individual, Corporate, Government, etc.

Use Cases:

Auto-create deposit account after KYC approval
Trigger welcome email/SMS
Apply customer tier benefits
AML/KYC verification workflows

2. Loan Account Events

Handler: AdministrationCoreLoanCommandHandlers.cs
Event: OnLoanCreation
Entity Type: Loan (3)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Status Enum: LoanState

Pending = 0 - Awaiting approval/disbursement
Active = 1 - Disbursed and repaying
Closed = 2 - Fully repaid
WrittenOff = 3 - Bad debt
Defaulted = 4 - Past due

Use Cases:

Multi-level loan approval workflows
Automated disbursement after final approval
Repayment reminders
Default management processes
Loan restructuring workflows

3. Deposit Account Events

Handler: AdministrationCoreDepositCommandHandlers.cs
Event: OnAccountCreation
Entity Type: Deposit (4)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Account Type Enum: DepositAccountType

Savings = 1 - Standard savings account
Current = 2 - No interest, transaction account
Fixed = 3 - Term deposit with penalty for early withdrawal
Call = 4 - High-value, notice required

Account Status Enum: DepositState

Pending = 0 - Awaiting activation
Active = 1 - Operational
Dormant = 2 - No activity for extended period
Closed = 3 - Permanently closed
Locked = 4 - Frozen for legal/compliance

Use Cases:

Account opening approval workflows
Welcome kit generation
ATM card issuance
Dormancy detection and reactivation
Account closure workflows

4. Teller Transaction Events

Handler: AdministrationCoreTelleringTransactionCommandHandlers.cs
Events: Multiple (9 transaction types)
Entity Type: Teller (13)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Status Enum: CBSTransactionHoldState

Processed = 0 - Transaction completed
Held = 1 - Requires authorization
Released = 2 - Hold released, transaction processed
Reversed = 3 - Transaction reversed

Transaction Types Covered:

Cash Deposit
Cash Withdrawal
Transfer
Balance Inquiry
Check Deposit
Check Withdrawal
Bill Payment
Account Statement
Other

Use Cases:

Large transaction authorization workflows
Fraud alert triggers
Supervisor approval for held transactions
End-of-day reconciliation
Cash position management

5. Reconciliation Events

Handler: ReconcilliationJobCommandHandlers.cs
Events: OnReconciliationDataUpdate, OnReconciliationJobCompletion
Entity Type: Reconciliation (200)

Event 1: OnReconciliationDataUpdate (Manual Reconciliation)

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Event 2: OnReconciliationJobCompletion (Automated Job)

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Status Enums:

ReconciliationStatusEnum: Manual, Automated, Pending, Completed
ReconciliationJobStatusEnum: Running, Completed, Failed, Cancelled

Use Cases:

Exception handling workflows
Email notifications for reconciliation failures
Escalation for unmatched transactions
Performance monitoring and alerts

6. Self-Service Channel Events

All self-service channel events follow the same standardized pattern.

A. Airtime Recharge

Handler: SelfServiceBankingTransactionCommand.cs
Events: OnAirtimeRechargeTransactionInitiated, OnAirtimeRechargeTransactionFailed, OnAirtimeRechargeTransactionCompleted
Entity Type: AirtimeRecharge (104)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

B. Data Recharge

Handler: SelfServiceBankingTransactionCommand.cs
Events: OnDataRechargeTransactionInitiated, OnDataRechargeTransactionFailed, OnDataRechargeTransactionCompleted
Entity Type: DataRecharge (105)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

C. Bills Payment

Handler: SelfServiceBankingTransactionCommand.cs
Events: OnBillsPaymentTransactionInitiated, OnBillsPaymentTransactionFailed, OnBillsPaymentTransactionCompleted
Entity Type: BillsPayment (103)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

D. Funds Transfer

Handler: SelfServiceBankingTransactionCommand.cs
Events: OnTransferInitiated, OnTransferCompleted (used for both success and failure)
Entity Type: Transfer (102)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Transfer Variations:

IntraBank Individual: Same bank, individual account
IntraBank Corporate: Same bank, corporate account with multi-level approval
InterBank: Different bank via NIP
IntraBankLingo: Transfer to another BankLingo tenant

E. Loan Request

Handler: SelfServiceLoanBankingTransactionCommand.cs
Event: OnLoanRequestSubmitted
Entity Type: LoanRequest (101)

Context Fields:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Status Enum: ApprovalState

Pending = 0 - Awaiting review
Approved = 1 - Request approved
Rejected = 2 - Request rejected
Cancelled = 3 - User cancelled

Self-Service Transaction Status Enum

All self-service channel transactions (except Loan Request) use the SelfServiceTransactionStatus enum:

Value	Name	Description	Use Case
0	PENDING	Transaction initiated, awaiting processing	Show "processing" to user
1	PROCESSING	Currently being processed by provider	Real-time status update
2	SUCCESSFUL	Transaction completed successfully	Credit account, send receipt
3	FAILED	Transaction failed (includes failureReason)	Reverse transaction, notify user
4	REVERSED	Transaction was reversed	Refund processing

BPM Condition Example:

// Check if transaction succeeded
if (context.status === 2) {
    // Send success SMS
}

// Check if transaction failed
if (context.status === 3) {
    // Log failure reason: context.failureReason
    // Trigger retry workflow
}

Standard Implementation Pattern

Complete Example

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Key Implementation Points

âœ… Dependency Injection: Inject IProcessEventDispatcher via constructor
âœ… Commit Order: ALWAYS SaveChanges() BEFORE dispatching
âœ… Error Handling: Wrap dispatch in try-catch, log warnings, don't fail transaction
âœ… Status Fields: Use status (not entity-specific names) with integer enum + description
âœ… User Tracking: Include userId and initiatorUserId for channel requests
âœ… Triggered By: Pass username or "System" to track who triggered the process

Implementation Status

âœ… Complete (26 dispatch points across 10 handlers - 100%)

Core Banking Handlers (11 events)

âœ… Contact - 1 event: OnCustomerCreation
âœ… Loan - 1 event: OnLoanCreation
âœ… Deposit - 1 event: OnAccountCreation
âœ… Teller - 9 events: All transaction types (Deposit, Withdrawal, Transfer, etc.)
âœ… Reconciliation - 2 events: Manual update, Job completion

Self-Service Channel Handlers (15 events)

âœ… Airtime Recharge - 3 events: Initiated, Failed, Completed
âœ… Data Recharge - 3 events: Initiated, Failed, Completed
âœ… Bills Payment - 3 events: Initiated, Failed, Completed
âœ… Funds Transfer - 6 events: Initiated, Failed (IntraBank/InterBank), Completed (IntraBank Individual/Corporate/InterBank)
âœ… Loan Request - 1 event: Submitted

Files Modified: 8 handler files
Build Status: âœ… No compilation errors
Documentation: âœ… Complete

BPM Process Examples

Example 1: Large Transfer Approval

// Process Definition Trigger
{
  "event": "onTransferInitiated",
  "entityType": "transfer",
  "condition": "status === 0 && amount > 1000000",  // Pending transfers over 1M
  "variables": {
    "transferAmount": "{{ amount }}",
    "sourceAccount": "{{ sourceAccountNumber }}",
    "destAccount": "{{ destinationAccountNumber }}",
    "transferType": "{{ transferType }}"
  }
}

// Script Task: Check Transfer Limits
if (context.amount > 5000000) {
    // Require CEO approval
    context.approvalLevel = 3;
} else if (context.amount > 1000000) {
    // Require Manager approval
    context.approvalLevel = 2;
}

// Service Task: Update Transfer Status
{
  "serviceType": "updateEntity",
  "entityType": "Transfer",
  "entityId": "{{ entityId }}",
  "updates": {
    "status": 2,  // SUCCESSFUL
    "approvedBy": "{{ approverUsername }}",
    "approvedAt": "{{ now() }}"
  }
}

Example 2: Failed Recharge Retry

// Process Definition Trigger
{
  "event": "onAirtimeRechargeTransactionFailed",
  "entityType": "airtimeRecharge",
  "condition": "status === 3",  // FAILED status
  "variables": {
    "phoneNumber": "{{ phoneNumber }}",
    "amount": "{{ amount }}",
    "provider": "{{ provider }}",
    "failureReason": "{{ failureReason }}"
  }
}

// Script Task: Determine Retry Strategy
if (context.failureReason.includes("timeout")) {
    context.retryCount = 3;
    context.retryDelay = 300;  // 5 minutes
} else if (context.failureReason.includes("insufficient funds")) {
    // Don't retry - notify user
    context.retryCount = 0;
}

// Timer Event: Wait before retry
{
  "duration": "{{ retryDelay }}s"
}

// Service Task: Retry Recharge
{
  "serviceType": "retryTransaction",
  "transactionId": "{{ entityId }}",
  "transactionType": "airtimeRecharge"
}

Migration Guide

For BPM Process Developers

If you have existing process definitions using old field names, update them as follows:

Old Field Names â†’ New Field Names:

loanStatus â†’ status
rechargeStatus â†’ status
paymentStatus â†’ status
transferStatus â†’ status
requestStatus â†’ status
reconciliationStatus â†’ status
holdState â†’ accountStatus (Teller transactions)
loanAccountNumber â†’ accountNumber

String Comparisons â†’ Numeric Comparisons (recommended):

// Old (still works via statusDescription)
if (context.transferStatus === "SUCCESSFUL") { }

// New (recommended - faster, type-safe)
if (context.status === 2) { }  // SelfServiceTransactionStatus.SUCCESSFUL

// Alternative (for readability)
if (context.statusDescription === "SUCCESSFUL") { }

Testing Checklist

When testing event dispatcher integration:

Benefits Summary

For Developers

âœ… Consistent patterns across all handlers
âœ… Type-safe enum values
âœ… Clear documentation and examples
âœ… Reduced cognitive load

For BPM Process Authors

âœ… Predictable field names
âœ… Reusable process templates
âœ… Faster condition evaluation
âœ… Better debugging with statusDescription

For System Performance

âœ… Numeric comparisons faster than strings
âœ… Reduced payload size
âœ… Better database query optimization

For Maintenance

âœ… Single source of truth for enum values
âœ… Easy to add new status values
âœ… Backward compatible via statusDescription

Event-Driven Process Architecture - Overall architecture
Process Engine Overview - Process engine documentation
Service Tasks - Service task implementation
Variables Guide - Process variable handling
DISPATCHER_EVENT_NAMING_STANDARDS.md - Technical implementation details

Version: 2.0
Last Updated: December 23, 2024
Status: âœ… Production Ready
Author: BankLingo Development Team

Overview​

Why Standardization Matters​

Before Standardization âŒ​

After Standardization âœ…​

Core Principles​

1. Status Field Naming​

2. Enum Value Convention​

3. Account Number Naming​

4. Transaction Commit Order​

Entity-Specific Implementations​

1. Contact (Customer) Events​

2. Loan Account Events​

3. Deposit Account Events​

4. Teller Transaction Events​

5. Reconciliation Events​

6. Self-Service Channel Events​

A. Airtime Recharge​

B. Data Recharge​

C. Bills Payment​

D. Funds Transfer​

E. Loan Request​

Self-Service Transaction Status Enum​

Standard Implementation Pattern​

Complete Example​

Key Implementation Points​

Implementation Status​

âœ… Complete (26 dispatch points across 10 handlers - 100%)​

Core Banking Handlers (11 events)​

Self-Service Channel Handlers (15 events)​

BPM Process Examples​

Example 1: Large Transfer Approval​

Example 2: Failed Recharge Retry​

Migration Guide​

For BPM Process Developers​

Testing Checklist​

Benefits Summary​

For Developers​

For BPM Process Authors​

For System Performance​

For Maintenance​

Related Documentation​

Overview

Why Standardization Matters

Before Standardization âŒ

After Standardization âœ…

Core Principles

1. Status Field Naming

2. Enum Value Convention

3. Account Number Naming

4. Transaction Commit Order

Entity-Specific Implementations

1. Contact (Customer) Events

2. Loan Account Events

3. Deposit Account Events

4. Teller Transaction Events

5. Reconciliation Events

6. Self-Service Channel Events

A. Airtime Recharge

B. Data Recharge

C. Bills Payment

D. Funds Transfer

E. Loan Request

Self-Service Transaction Status Enum

Standard Implementation Pattern

Complete Example

Key Implementation Points

Implementation Status

âœ… Complete (26 dispatch points across 10 handlers - 100%)

Core Banking Handlers (11 events)

Self-Service Channel Handlers (15 events)

BPM Process Examples

Example 1: Large Transfer Approval

Example 2: Failed Recharge Retry

Migration Guide

For BPM Process Developers

Testing Checklist

Benefits Summary

For Developers

For BPM Process Authors

For System Performance

For Maintenance

Related Documentation