Execution Modes

The BankLingo Process Engine supports two execution modes that control how processes run: Unsupervised Mode (automatic) and Supervised Mode (step-by-step).

Unsupervised Mode (Default)

Unsupervised Mode is the default execution mode where processes run automatically from start to completion without manual intervention.

Behavior

• Process executes continuously
• Tasks execute sequentially
• Only pauses at UserTask (waiting for human action)
• Continues automatically after user completes task
• Runs until completion or error

When to Use

• ✅ Production workflows
• ✅ Fully automated processes
• ✅ Normal business operations
• ✅ Background jobs

Starting in Unsupervised Mode

POST /api/process-instances/start
Content-Type: application/json

{
  "processKey": "LoanApproval_v1",
  "businessKey": "LOAN-2025-001",
  "variables": {
    "loanAmount": 50000,
    "customerName": "John Doe"
  },
  "executionMode": "Unsupervised"
}

Or simply omit the executionMode (defaults to Unsupervised):

{
  "processKey": "LoanApproval_v1",
  "businessKey": "LOAN-2025-001",
  "variables": { ... }
}

Execution Flow

Start → Task1 → Task2 → UserTask (PAUSE) → [User completes] → Task3 → Task4 → End
        ↓        ↓                ↓                             ↓        ↓      ↓
    Auto     Auto            Waiting                        Auto     Auto  Done

Supervised Mode

Supervised Mode executes one task at a time, pausing after each task for manual control. This enables step-by-step debugging and process inspection.

Behavior

• Process executes ONE task at a time
• Pauses after EVERY task (not just UserTasks)
• Requires manual command to continue (step-forward)
• Can move backwards (step-backward) to review previous tasks
• Execution history is tracked

When to Use

• 🔍 Process development and testing
• 🐛 Debugging complex workflows
• 📊 Training and demonstrations
• 🔬 Process inspection and analysis

Starting in Supervised Mode

POST /api/process-instances/start
Content-Type: application/json

{
  "processKey": "LoanApproval_v1",
  "businessKey": "LOAN-2025-TEST-001",
  "variables": {
    "loanAmount": 50000,
    "customerName": "John Doe"
  },
  "executionMode": "Supervised"
}

Response After Each Task

{
  "success": true,
  "data": {
    "instanceGuid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PausedAfterTask",
    "executionMode": "Supervised",
    "currentTaskId": "Task_ValidateApplication",
    "currentTaskName": "Validate Application Data",
    "currentTaskType": "ScriptTask",
    "executionHistory": [
      {
        "taskId": "StartEvent_1",
        "taskName": "Application Received",
        "taskType": "StartEvent",
        "executedAt": "2025-12-18T10:00:00Z",
        "status": "Completed"
      },
      {
        "taskId": "Task_ValidateApplication",
        "taskName": "Validate Application Data",
        "taskType": "ScriptTask",
        "executedAt": "2025-12-18T10:00:01Z",
        "status": "Completed"
      }
    ],
    "nextTaskId": "Task_ReviewApplication",
    "nextTaskName": "Review Loan Application"
  }
}

Execution Flow

Start → [PAUSE] → Task1 → [PAUSE] → Task2 → [PAUSE] → UserTask → [PAUSE] → Task3 → [PAUSE] → End
        ↓          ↓        ↓          ↓        ↓          ↓         ↓          ↓        ↓          ↓
      Manual    Manual   Manual    Manual   Manual    Manual     Manual    Manual   Manual    Done

Step Forward

Move execution forward by one task.

API Request

POST /api/process-instances/{instanceGuid}/step-forward
Authorization: Bearer YOUR_API_TOKEN

Example

curl -X POST https://your-instance.banklingo.com/api/process-instances/123e4567-e89b-12d3-a456-426614174000/step-forward \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": {
    "instanceGuid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PausedAfterTask",
    "executedTaskId": "Task_ReviewApplication",
    "executedTaskName": "Review Loan Application",
    "executionMode": "Supervised",
    "nextTaskId": "Gateway_ApprovalDecision",
    "variables": {
      "loanAmount": 50000,
      "userAction": "Approve",
      "approverName": "Jane Smith"
    }
  }
}

Step Backward

Move the execution pointer backward to review previous tasks.

Important Notes

• Does NOT undo execution - only moves the pointer
• Variables remain unchanged
• Use for inspection and debugging only
• Cannot step backward before the start

API Request

POST /api/process-instances/{instanceGuid}/step-backward
Authorization: Bearer YOUR_API_TOKEN

Example

curl -X POST https://your-instance.banklingo.com/api/process-instances/123e4567-e89b-12d3-a456-426614174000/step-backward \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": {
    "instanceGuid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PausedAfterTask",
    "currentTaskId": "Task_ValidateApplication",
    "currentTaskName": "Validate Application Data",
    "message": "Moved backward to previous task (pointer only, execution not undone)",
    "executionHistory": [ ... ]
  }
}

Switching Modes

You can change execution mode for a running process.

Switch to Supervised Mode

Useful when you want to debug a running process:

POST /api/process-instances/{instanceGuid}/set-execution-mode
Content-Type: application/json

{
  "executionMode": "Supervised"
}

Switch to Unsupervised Mode

Resume normal automatic execution:

POST /api/process-instances/{instanceGuid}/set-execution-mode
Content-Type: application/json

{
  "executionMode": "Unsupervised"
}

Complete Supervised Mode Example

1. Start Process in Supervised Mode

POST /api/process-instances/start

{
  "processKey": "LoanApproval_v1",
  "businessKey": "DEBUG-001",
  "variables": { "loanAmount": 75000 },
  "executionMode": "Supervised"
}

Response: Paused after StartEvent

2. Step Forward (Execute Task_ValidateApplication)

POST /api/process-instances/{guid}/step-forward

Response: Paused after Task_ValidateApplication

Variables Now Include: validationStatus, validationDate

3. Step Forward (Execute Task_ReviewApplication)

POST /api/process-instances/{guid}/step-forward

Response: Paused after Task_ReviewApplication (UserTask)

Status: WaitingForUserAction

4. Complete UserTask

POST /api/user-tasks/complete

{
  "instanceGuid": "{guid}",
  "taskId": "Task_ReviewApplication",
  "userAction": "Approve",
  "variables": { "approverName": "Jane" }
}

Response: Still paused (supervised mode)

5. Step Forward (Execute Gateway)

POST /api/process-instances/{guid}/step-forward

Response: Paused after Gateway_ApprovalDecision

Gateway took: Flow_Approved based on condition

6. Step Backward (Review Gateway Decision)

POST /api/process-instances/{guid}/step-backward

Response: Pointer moved back to Gateway

Can inspect: Which flow was taken and why

7. Step Forward (Re-execute Gateway - Already Done)

POST /api/process-instances/{guid}/step-forward

Response: Moves to next task

8. Continue to Completion

Keep calling step-forward until process completes.

Execution History

Both modes track execution history:

{
  "executionHistory": [
    {
      "sequence": 1,
      "taskId": "StartEvent_1",
      "taskName": "Application Received",
      "taskType": "StartEvent",
      "executedAt": "2025-12-18T10:00:00Z",
      "duration": "00:00:00",
      "status": "Completed"
    },
    {
      "sequence": 2,
      "taskId": "Task_ValidateApplication",
      "taskName": "Validate Application Data",
      "taskType": "ScriptTask",
      "executedAt": "2025-12-18T10:00:01Z",
      "duration": "00:00:00.150",
      "status": "Completed",
      "variablesSet": ["validationStatus", "validationDate"]
    },
    {
      "sequence": 3,
      "taskId": "Task_ReviewApplication",
      "taskName": "Review Loan Application",
      "taskType": "UserTask",
      "executedAt": "2025-12-18T10:00:02Z",
      "completedAt": "2025-12-18T10:15:00Z",
      "duration": "00:14:58",
      "completedBy": "jane.smith@bank.com",
      "userAction": "Approve",
      "status": "Completed"
    },
    {
      "sequence": 4,
      "taskId": "Gateway_ApprovalDecision",
      "taskName": "Approved?",
      "taskType": "ExclusiveGateway",
      "executedAt": "2025-12-18T10:15:00Z",
      "duration": "00:00:00.050",
      "takenFlow": "Flow_Approved",
      "status": "Completed"
    }
  ]
}

Use Cases

Development & Testing

// Test each task individually
await startProcess({ executionMode: 'Supervised' });
await stepForward(); // Test Task 1
await stepForward(); // Test Task 2
// ... continue

Debugging Production Issues

// Start problematic scenario in supervised mode
await startProcess({
  processKey: 'LoanApproval_v1',
  variables: { ...productionData },
  executionMode: 'Supervised'
});

// Step through to find where it fails
while (status !== 'Completed') {
  const result = await stepForward();
  console.log('Executed:', result.executedTaskId);
  console.log('Variables:', result.variables);
  
  if (result.error) {
    console.error('Failed at:', result.executedTaskId);
    break;
  }
}

Training & Demonstrations

// Show process flow step-by-step
async function demonstrateProcess() {
  const instance = await startProcess({ 
    executionMode: 'Supervised' 
  });
  
  while (instance.status !== 'Completed') {
    console.log(`\n=== Step ${instance.executionHistory.length} ===`);
    console.log(`Task: ${instance.nextTaskName}`);
    console.log(`Type: ${instance.nextTaskType}`);
    
    await waitForUserInput(); // Wait for presenter to continue
    await stepForward();
  }
}

Best Practices

1. Use Unsupervised for Production

// Production
startProcess({ executionMode: 'Unsupervised' });

// Development
startProcess({ executionMode: 'Supervised' });

2. Enable Logging in Supervised Mode

Detailed logs help with debugging:

{
  "processKey": "LoanApproval_v1",
  "executionMode": "Supervised",
  "enableDetailedLogging": true
}

3. Use Step Backward for Inspection Only

Don't rely on backward steps for process logic:

// Good: Inspect previous task
await stepBackward();
console.log('Previous task was:', currentTaskId);
await stepForward(); // Move forward again

// Bad: Don't use backward as undo
await stepBackward();
// Expecting variables to be reset - WRONG!

4. Switch Modes Dynamically

// Start in unsupervised mode
const instance = await startProcess({ 
  executionMode: 'Unsupervised' 
});

// Switch to supervised if error occurs
if (instance.status === 'Error') {
  await setExecutionMode(instance.guid, 'Supervised');
  // Now step through to find issue
}

Performance Considerations

Unsupervised Mode

• ✅ Fast execution
• ✅ Low overhead
• ✅ Scales well
• ✅ Production-ready

Supervised Mode

• ⚠️ Slower (requires manual steps)
• ⚠️ More state management
• ⚠️ Higher memory usage
• ⚠️ Development/testing only

Next Steps

• API Reference - Complete API documentation
• Examples - Supervised mode examples
• Task Types - Learn about all task types