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": {
    "processDefinitionId": 15,
    "status": "WAITING",
    "pageIndex": 0,
    "pageSize": 20
  }
}

Parameters:

Field	Type	Required	Description
processDefinitionId	number	No	Filter by process definition
status	string	No	Filter by status (RUNNING, WAITING, COMPLETED, ERROR)
pageIndex	number	No	Page index (default: 0)
pageSize	number	No	Page size (default: 20)

Response:

{
  "isSuccessful": true,
  "message": "20/150 records",
  "count": 150,
  "pages": 8,
  "size": 20,
  "hasNext": true,
  "hasPrevious": false,
  "data": [
    {
      "instanceId": "abc123",
      "processKey": "LoanApplicationProcess",
      "status": "WAITING",
      "currentTaskName": "Approve Loan",
      "createdAt": "2026-01-11T09:00:00Z"
    }
  ]
}

---

Cancel Process

Cancel a running or waiting process instance.

CancelProcessInstanceCommand

Request:

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