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:

Process reaches ReceiveTask/CallActivity and sets correlation key
Process pauses and stores correlation key in CallbackRegistry
External system (webhook, API) calls ReturnCallbackCommand with correlation key
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.

Last Updated: January 11, 2026

Overview​

Base Endpoint​

Start Process​

StartProcessInstanceCommand​

Signal Process (Resume)​

SignalProcessInstanceCommand​

Return Callback​

ReturnCallbackCommand​

Query Process Instance​

GetProcessInstanceByIdQuery​

List Process Instances​

GetProcessInstanceListQuery​

Cancel Process​

CancelProcessInstanceCommand​

Error Handling​

Common Errors​

Complete Example: Loan Application Flow​

Step 1: Start Loan Process​

Step 2: Approve Loan​

Step 3: Payment Callback​

Best Practices​

1. Use Correlation Keys​

2. Handle Execution Modes​

3. Pass Minimal Variables​

4. Check Process Status​

5. Use Meaningful Variable Names​

Related Documentation​

Overview

Base Endpoint

Start Process

StartProcessInstanceCommand

Signal Process (Resume)

SignalProcessInstanceCommand

Return Callback

ReturnCallbackCommand

Query Process Instance

GetProcessInstanceByIdQuery

List Process Instances

GetProcessInstanceListQuery

Cancel Process

CancelProcessInstanceCommand

Error Handling

Common Errors

Complete Example: Loan Application Flow

Step 1: Start Loan Process

Step 2: Approve Loan

Step 3: Payment Callback

Best Practices

1. Use Correlation Keys

2. Handle Execution Modes

3. Pass Minimal Variables

4. Check Process Status

5. Use Meaningful Variable Names

Related Documentation