Process Engine APIs

Complete API reference for BankLingo's Process Engine (BPMN workflow execution).

Overview

The Process Engine enables workflow automation through BPMN 2.0 processes. These APIs allow you to create, start, control, and monitor process instances.

Base Endpoint

POST /api/v1/execute
Content-Type: application/json
Authorization: Bearer {token}

---

Start Process

Start a new BPMN process instance.

StartProcessInstanceCommand

Request:

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "processDefinitionId": 15,
    "variables": {
      "customerId": "12345",
      "amount": 50000,
      "loanType": "PERSONAL"
    },
    "executionMode": "Supervised"
  }
}

Parameters:

Field	Type	Required	Description
processDefinitionId	number	Yes	ID of the process definition to start
variables	object	No	Initial process variables (key-value pairs)
executionMode	string	No	Execution mode: "Supervised" (default) or "FireAndForget"

Execution Modes:

• Supervised (Default): Synchronous execution, waits for completion or user task
• FireAndForget: Asynchronous execution, returns immediately with job ID

Response (Supervised Mode):

{
  "isSuccessful": true,
  "message": "Process completed successfully",
  "data": {
    "instanceId": "abc123-def456",
    "status": "COMPLETED",
    "variables": {
      "customerId": "12345",
      "loanId": "LOAN-9876",
      "approvalStatus": "APPROVED"
    },
    "currentTaskId": null,
    "currentTaskName": null
  }
}

Response (FireAndForget Mode):

{
  "isSuccessful": true,
  "message": "Process started in background",
  "data": {
    "jobId": "job-xyz-789",
    "instanceId": "abc123-def456",
    "status": "RUNNING"
  }
}

Process Status Values:

• RUNNING - Process is executing
• WAITING - Process paused at user task or receive task
• COMPLETED - Process finished successfully
• ERROR - Process encountered an error
• CANCELLED - Process was cancelled

---

Signal Process (Resume)

Resume a waiting process instance (user task or receive task).

SignalProcessInstanceCommand

Request:

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceId": "abc123-def456",
    "taskId": "UserTask_Approval",
    "variables": {
      "approvalDecision": "APPROVED",
      "approverComments": "Loan approved with standard terms"
    }
  }
}

Parameters:

Field	Type	Required	Description
instanceId	string	Yes	Process instance ID (from StartProcessInstanceCommand)
taskId	string	Yes	ID of the waiting task to signal
variables	object	No	Variables to merge into process context

Response:

{
  "isSuccessful": true,
  "message": "Process resumed successfully",
  "data": {
    "instanceId": "abc123-def456",
    "status": "COMPLETED",
    "variables": {
      "customerId": "12345",
      "loanId": "LOAN-9876",
      "approvalDecision": "APPROVED",
      "approverComments": "Loan approved with standard terms"
    }
  }
}

---

Return Callback

Resume a process waiting on a callback (ReceiveTask or CallActivity).

ReturnCallbackCommand

Request:

{
  "cmd": "ReturnCallbackCommand",
  "data": {
    "correlationKey": "PAYMENT-REF-12345",
    "callbackData": {
      "transactionId": "TXN-987654",
      "status": "SUCCESS",
      "amount": 50000,
      "timestamp": "2026-01-11T10:30:00Z"
    },
    "isSuccess": true
  }
}

Parameters:

Field	Type	Required	Description
correlationKey	string	Yes	Correlation key set in ReceiveTask/CallActivity
callbackData	object	Yes	Data to pass back to the waiting process
isSuccess	boolean	No	Whether callback represents success (default: true)

How It Works:

1. Process reaches ReceiveTask/CallActivity and sets correlation key
2. Process pauses and stores correlation key in CallbackRegistry
3. External system (webhook, API) calls ReturnCallbackCommand with correlation key
4. Process resumes with callback data merged into variables

Response:

{
  "isSuccessful": true,
  "message": "Process resumed successfully",
  "data": {
    "instanceId": "abc123-def456",
    "status": "COMPLETED",
    "callbackData": {
      "transactionId": "TXN-987654",
      "status": "SUCCESS",
      "amount": 50000
    }
  }
}

Use Cases:

• Payment gateway callbacks (Paystack, Flutterwave)
• NIBSS transaction responses
• Third-party API async responses
• Email approval links
• Mobile app confirmations

---

Query Process Instance

Get details of a process instance.

GetProcessInstanceByIdQuery

Request:

{
  "cmd": "GetProcessInstanceByIdQuery",
  "data": {
    "instanceId": "abc123-def456"
  }
}

Response:

{
  "isSuccessful": true,
  "message": "Process instance retrieved successfully",
  "data": {
    "instanceId": "abc123-def456",
    "processDefinitionId": 15,
    "processKey": "LoanApplicationProcess",
    "status": "WAITING",
    "currentTaskId": "UserTask_Approval",
    "currentTaskName": "Approve Loan Application",
    "currentActivityType": "UserTask",
    "variables": {
      "customerId": "12345",
      "amount": 50000,
      "loanType": "PERSONAL"
    },
    "createdAt": "2026-01-11T09:00:00Z",
    "updatedAt": "2026-01-11T09:15:00Z",
    "tenantId": 1
  }
}

---

List Process Instances

List process instances with filtering.

GetProcessInstanceListQuery

Request:

{
  "cmd": "GetProcessInstanceListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "processDefinitionId": 15,
    "status": null,
    "isTestMode": null,
    "isOwnedProcesses": false,
    "searchText": null,
    "entityType": null,
    "entityReferenceId": null,
    "hasErrorsOnly": false,
    "showClosedProcesses": null,
    "filters": [],
    "searchFields": []
  }
}

Parameters:

Field	Type	Required	Description
pageNumber	number	No	Page number, 1-based (default: 1)
pageSize	number	No	Page size (default: 20)
processDefinitionId	number	No	Filter by process definition ID
status	number	No	Filter by ProcessRunStatus enum integer
isTestMode	boolean	No	true = test only, false = production only, null = all
isOwnedProcesses	boolean	No	When true, returns only the caller's own instances
searchText	string	No	Free-text search across context, initiatedBy, currentTaskName, instanceGuid
entityType	number	No	Filter by ProcessEntityType enum integer
entityReferenceId	number	No	Filter by associated entity ID
hasErrorsOnly	boolean	No	When true, returns only instances with errors
showClosedProcesses	boolean	No	When false, excludes COMPLETED/CANCELLED/EXPIRED instances

Response:

{
  "isSuccessful": true,
  "message": "20/150 records.",
  "count": 150,
  "pages": 8,
  "size": 20,
  "hasNext": true,
  "hasPrevious": false,
  "data": {
    "ProcessDefinition": {
      "id": 15,
      "name": "Loan Approval",
      "description": "...",
      "permission": "LOAN_ADMIN"
    },
    "Instances": [
      {
        "id": 101,
        "instanceGuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "context": "LOAN-2024-001",
        "processDefinitionId": 15,
        "processDefinitionName": "Loan Approval",
        "processRunStatus": 2,
        "processRunStatusDesc": "Waiting for User Input",
        "currentTaskName": "Manager Approval",
        "currentActivityType": "bpmn:UserTask",
        "initiatedBy": "john.doe",
        "startedAt": "2026-01-11T09:00:00Z",
        "hasError": false,
        "canView": true,
        "canOpen": true,
        "canRetry": false,
        "canCancel": true,
        "isSupervised": false
      }
    ]
  }
}

ProcessDefinition is only present when processDefinitionId is set in the request. processDefinitionXml is not returned in list responses — use GetProcessDefinitiionByIdQuery for the BPMN XML.

---

## Cancel Process

Cancel a running or waiting process instance.

### CancelProcessInstanceCommand

**Request**:
```json
{
  "cmd": "CancelProcessInstanceCommand",
  "data": {
    "instanceId": "abc123-def456",
    "reason": "Customer requested cancellation"
  }
}

Response:

{
  "isSuccessful": true,
  "message": "Process instance cancelled successfully",
  "data": {
    "instanceId": "abc123-def456",
    "status": "CANCELLED"
  }
}

---

Error Handling

Common Errors

Process Not Found:

{
  "isSuccessful": false,
  "message": "Process instance with ID 'abc123' not found"
}

Invalid Task ID:

{
  "isSuccessful": false,
  "message": "Task 'InvalidTaskId' not found in process instance"
}

Process Already Completed:

{
  "isSuccessful": false,
  "message": "Cannot signal completed process instance"
}

Correlation Key Not Found:

{
  "isSuccessful": false,
  "message": "No process found waiting for correlation key 'PAYMENT-REF-12345'"
}

---

Complete Example: Loan Application Flow

Step 1: Start Loan Process

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "processDefinitionId": 15,
    "variables": {
      "customerId": "12345",
      "amount": 100000,
      "loanType": "PERSONAL",
      "email": "customer@example.com"
    },
    "executionMode": "Supervised"
  }
}

Response:

{
  "isSuccessful": true,
  "data": {
    "instanceId": "loan-abc123",
    "status": "WAITING",
    "currentTaskId": "UserTask_Approval",
    "currentTaskName": "Credit Officer Approval"
  }
}

Step 2: Approve Loan

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceId": "loan-abc123",
    "taskId": "UserTask_Approval",
    "variables": {
      "approvalDecision": "APPROVED",
      "approverName": "John Doe"
    }
  }
}

Response:

{
  "isSuccessful": true,
  "data": {
    "instanceId": "loan-abc123",
    "status": "WAITING",
    "currentTaskId": "ReceiveTask_Payment",
    "currentTaskName": "Wait for Paystack Payment"
  }
}

Step 3: Payment Callback

{
  "cmd": "ReturnCallbackCommand",
  "data": {
    "correlationKey": "loan-abc123-payment",
    "callbackData": {
      "transactionId": "TXN-987654",
      "status": "success",
      "amount": 100000
    },
    "isSuccess": true
  }
}

Response:

{
  "isSuccessful": true,
  "data": {
    "instanceId": "loan-abc123",
    "status": "COMPLETED",
    "variables": {
      "loanId": "LOAN-9876",
      "disbursementStatus": "COMPLETED"
    }
  }
}

---

Best Practices

1. Use Correlation Keys

Always set unique correlation keys for callbacks:

<bpmn:receiveTask id="WaitForPayment" name="Wait for Payment">
  <bpmn:extensionElements>
    <bankLingo:correlationKey>${instanceId}-payment</bankLingo:correlationKey>
  </bpmn:extensionElements>
</bpmn:receiveTask>

2. Handle Execution Modes

Use appropriate execution mode:

• Supervised: For user-facing operations (return results immediately)
• FireAndForget: For background jobs (large datasets, bulk operations)

3. Pass Minimal Variables

Only pass variables needed for the process to reduce payload size.

4. Check Process Status

Always check process status before signaling:

{
  "cmd": "GetProcessInstanceByIdQuery",
  "data": {
    "instanceId": "abc123"
  }
}

5. Use Meaningful Variable Names

Use clear, descriptive variable names that match your business domain.

---

Related Documentation

• Process Engine Overview
• BPMN Task Types
• Webhook APIs
• Recurring Job APIs
• Callback Patterns

---

Last Updated: January 11, 2026