Step Forward

Overview

The StepForwardCommand executes the next task in a process running in Supervised Mode. This command allows step-by-step execution for debugging, testing, and process inspection.

Supervised Mode Only

This command only works for processes started with executionMode: "Supervised". Unsupervised processes execute automatically and don't require step commands.

API Endpoint

POST /api/core/cmd

Headers

Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-ID: {tenant_id}

Request Structure

{
  "cmd": "StepForwardCommand",
  "data": {
    "instanceGuid": "abc-123-def-456"
  }
}

Request Fields

Field	Type	Required	Description
instanceGuid	string	Yes	The unique identifier of the supervised process instance

When to Use

• Process Development: Test each task individually
• Debugging: Inspect variables after each task execution
• Training: Demonstrate workflow step-by-step
• Validation: Verify task logic before production deployment

Sample Requests

1. Execute Next Task

{
  "cmd": "StepForwardCommand",
  "data": {
    "instanceGuid": "loan-approval-supervised-001"
  }
}

2. Continue After Review

{
  "cmd": "StepForwardCommand",
  "data": {
    "instanceGuid": "test-workflow-789"
  }
}

Response Structure

Task Executed Successfully (More Tasks Remaining)

{
  "isSuccessful": true,
  "message": "Step forward executed successfully. Process waiting at next task.",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-approval-supervised-001",
    "status": "waiting",
    "currentActivityId": "Task_CreditCheck",
    "executionMode": "Supervised",
    "previousTask": {
      "taskId": "Task_ValidateCustomer",
      "taskName": "Validate Customer Information",
      "taskType": "ServiceTask",
      "executionTime": "1.2s",
      "success": true
    },
    "currentTask": {
      "taskId": "Task_CreditCheck",
      "taskName": "Perform Credit Check",
      "taskType": "ServiceTask"
    },
    "state": {
      "variables": {
        "customerId": 123,
        "customerName": "John Doe",
        "validationStatus": "passed",
        "creditScore": null
      },
      "completedTasks": ["StartEvent", "Task_ValidateCustomer"],
      "currentNode": "Task_CreditCheck"
    },
    "nextActions": [
      {
        "action": "stepForward",
        "label": "Execute Credit Check",
        "command": "StepForwardCommand"
      },
      {
        "action": "stepBackward",
        "label": "Go Back",
        "command": "StepBackwardCommand"
      },
      {
        "action": "cancel",
        "label": "Cancel Process",
        "command": "CancelProcessInstanceCommand"
      }
    ]
  }
}

Task Executed Successfully (Process Completed)

{
  "isSuccessful": true,
  "message": "Process completed successfully",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-approval-supervised-001",
    "status": "completed",
    "currentActivityId": "EndEvent_Success",
    "executionMode": "Supervised",
    "previousTask": {
      "taskId": "Task_ApproveLoan",
      "taskName": "Approve Loan",
      "taskType": "ServiceTask",
      "executionTime": "0.8s",
      "success": true
    },
    "state": {
      "variables": {
        "customerId": 123,
        "customerName": "John Doe",
        "loanAmount": 50000,
        "approved": true,
        "loanId": 456
      },
      "completedTasks": [
        "StartEvent",
        "Task_ValidateCustomer",
        "Task_CreditCheck",
        "Task_ApproveLoan",
        "EndEvent_Success"
      ]
    },
    "summary": {
      "totalTasks": 4,
      "successfulTasks": 4,
      "totalExecutionTime": "4.5s",
      "status": "completed"
    }
  }
}

Task Execution Failed

{
  "isSuccessful": false,
  "message": "Task execution failed: Credit service unavailable",
  "statusCode": "99",
  "data": {
    "instanceGuid": "loan-approval-supervised-001",
    "status": "error",
    "currentActivityId": "Task_CreditCheck",
    "error": {
      "taskId": "Task_CreditCheck",
      "taskName": "Perform Credit Check",
      "errorMessage": "Credit service unavailable",
      "errorDetails": "Connection timeout after 30 seconds"
    },
    "nextActions": [
      {
        "action": "retry",
        "label": "Retry This Task",
        "command": "RetryFailedTaskCommand"
      },
      {
        "action": "skip",
        "label": "Skip This Task",
        "command": "SkipFailedTaskCommand"
      },
      {
        "action": "stepBackward",
        "label": "Go Back",
        "command": "StepBackwardCommand"
      },
      {
        "action": "cancel",
        "label": "Cancel Process",
        "command": "CancelProcessInstanceCommand"
      }
    ]
  }
}

Error Responses

Process Not in Supervised Mode

{
  "isSuccessful": false,
  "message": "Process is not running in Supervised mode",
  "statusCode": "99",
  "data": {
    "currentMode": "Unsupervised"
  }
}

Process Not Found

{
  "isSuccessful": false,
  "message": "Process instance 'invalid-guid' not found.",
  "statusCode": "99",
  "data": null
}

Process Already Completed

{
  "isSuccessful": false,
  "message": "Process has already completed. Cannot step forward.",
  "statusCode": "99",
  "data": {
    "status": "completed"
  }
}

Supervised Execution Flow

Use Cases

1. Debugging - Inspect Variables After Each Task

// Step through process and log variables
let instanceGuid = "test-process-001";
let completed = false;

while (!completed) {
  const response = await stepForward(instanceGuid);
  
  console.log("Task Completed:", response.data.previousTask.taskName);
  console.log("Current Variables:", response.data.state.variables);
  console.log("Next Task:", response.data.currentTask?.taskName);
  
  if (response.data.status === "completed") {
    completed = true;
    console.log("Process Summary:", response.data.summary);
  }
}

2. Testing - Verify Task Logic

// Test credit check task
await stepForward(instanceGuid); // Execute ValidateCustomer
const response = await stepForward(instanceGuid); // Execute CreditCheck

// Verify credit check results
const creditScore = response.data.state.variables.creditScore;
assert(creditScore >= 0 && creditScore <= 850, "Invalid credit score");

console.log(`Credit score calculated: ${creditScore}`);

3. Training - Interactive Workflow Demonstration

// Show workflow step-by-step to trainees
function demonstrateWorkflow(instanceGuid) {
  return {
    async nextStep() {
      const response = await stepForward(instanceGuid);
      
      displayTaskInfo(response.data.previousTask);
      displayVariables(response.data.state.variables);
      
      if (response.data.currentTask) {
        showNextTaskPreview(response.data.currentTask);
      } else {
        showCompletionSummary(response.data.summary);
      }
      
      return response;
    }
  };
}

Best Practices

1. Always Check Response Status

const response = await stepForward(instanceGuid);

if (!response.isSuccessful) {
  if (response.data?.status === "error") {
    console.error("Task failed:", response.message);
    // Decide: retry, skip, or cancel
  } else {
    console.error("Step forward failed:", response.message);
  }
  return;
}

// Process response
const nextTask = response.data.currentTask;

2. Track Execution Progress

let completedTasks = [];

while (status !== "completed") {
  const response = await stepForward(instanceGuid);
  
  if (response.data.previousTask) {
    completedTasks.push({
      name: response.data.previousTask.taskName,
      time: response.data.previousTask.executionTime,
      success: response.data.previousTask.success
    });
  }
  
  status = response.data.status;
}

console.log("Execution Report:", completedTasks);

3. Handle Task Failures Gracefully

const response = await stepForward(instanceGuid);

if (response.data?.status === "error") {
  const error = response.data.error;
  
  console.error(`Task ${error.taskName} failed: ${error.errorMessage}`);
  
  // Present options to user
  const action = await promptUserAction([
    "Retry this task",
    "Skip this task",
    "Cancel process"
  ]);
  
  switch (action) {
    case "Retry":
      await retryFailedTask(instanceGuid);
      break;
    case "Skip":
      await skipFailedTask(instanceGuid);
      break;
    case "Cancel":
      await cancelProcess(instanceGuid);
      break;
  }
}

4. Use for Pre-Production Validation

// Validate workflow before deploying to production
async function validateWorkflow(processId, testData) {
  // Start in supervised mode
  const startResponse = await startProcess({
    id: processId,
    runtimeContext: JSON.stringify(testData),
    executionMode: "Supervised"
  });
  
  const instanceGuid = startResponse.data.instanceGuid;
  const validationResults = [];
  
  // Step through entire workflow
  while (true) {
    const response = await stepForward(instanceGuid);
    
    // Validate task execution
    if (response.data.previousTask) {
      validationResults.push({
        task: response.data.previousTask.taskName,
        success: response.data.previousTask.success,
        executionTime: response.data.previousTask.executionTime
      });
    }
    
    if (response.data.status === "completed") break;
    if (response.data.status === "error") {
      validationResults.push({
        task: response.data.error.taskName,
        success: false,
        error: response.data.error.errorMessage
      });
      break;
    }
  }
  
  return {
    processId,
    validated: validationResults.every(r => r.success),
    results: validationResults
  };
}

Related Commands

• Start Process - Start process in Supervised mode
• Step Backward - Go back to previous task
• Get Process State - Check current process status
• Retry Failed Task - Retry a failed task
• Skip Failed Task - Skip a failed task
• Cancel Process - Cancel supervised process

Notes

• Only works with processes started in Supervised mode
• Each call executes exactly ONE task
• Process pauses after each task for inspection
• Returns detailed information about executed task and next task
• Provides nextActions array showing available commands
• Task execution time is tracked and returned
• Variables are updated after each task execution
• If a task fails, process enters "error" state
• Failed tasks can be retried or skipped
• Process can be cancelled at any point
• Completed tasks are tracked in the state