Skip to main content

Start Process

Overview​

The StartProcessInstanceCommand initiates a new process instance from a saved process definition. This command is used for both Unsupervised (automatic) and Supervised (step-by-step) execution modes.

API Endpoint​

POST /api/core/cmd

Headers​

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

Request Structure​

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "id": 123,
    "runtimeContext": "{\"loanId\": 456, \"customerId\": 789}",
    "contextTypeId": 1,
    "contextId": 456,
    "executionMode": "Unsupervised"
  }
}

Request Fields​

FieldTypeRequiredDescriptionDefault
idlongYesThe process definition ID to execute-
runtimeContextstring (JSON)YesInitial variables/data for the process as JSON string-
contextTypeIdlongNoOptional context type identifier for tracking-
contextIdlongNoOptional context ID (e.g., loan ID, application ID)-
executionModestringNo"Unsupervised" or "Supervised""Unsupervised"

Execution Modes​

Unsupervised Mode (Default)​

Process runs automatically from start to end, only pausing at UserTask nodes.

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "id": 123,
    "runtimeContext": "{\"amount\": 50000, \"applicantName\": \"John Doe\"}",
    "executionMode": "Unsupervised"
  }
}

Use Cases:

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

Supervised Mode​

Process executes one task at a time, pausing after EVERY task for manual control.

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "id": 123,
    "runtimeContext": "{\"amount\": 50000, \"applicantName\": \"John Doe\"}",
    "executionMode": "Supervised"
  }
}

Use Cases:

  • Process development and testing
  • Debugging complex workflows
  • Training and demonstrations
  • Process inspection

Runtime Context​

The runtimeContext field must be a JSON string containing the initial variables for your process:

{
  "runtimeContext": "{\"loanAmount\": 50000, \"customerId\": 12345, \"branch\": \"Main Branch\", \"currency\": \"USD\"}"
}

These variables are accessible throughout the process in tasks and gateways.

Sample Requests​

1. Start Loan Approval Process (Unsupervised)​

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "id": 45,
    "runtimeContext": "{\"loanId\": 789, \"loanAmount\": 100000, \"customerId\": 456, \"customerName\": \"Jane Smith\", \"loanType\": \"Personal\", \"requestedTerm\": 24}",
    "contextTypeId": 1,
    "contextId": 789,
    "executionMode": "Unsupervised"
  }
}

2. Start Account Opening Process (Supervised for Testing)​

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "id": 67,
    "runtimeContext": "{\"accountType\": \"Savings\", \"customerId\": 123, \"initialDeposit\": 5000, \"branch\": \"Downtown\"}",
    "executionMode": "Supervised"
  }
}

3. Start Simple Workflow​

{
  "cmd": "StartProcessInstanceCommand",
  "data": {
    "id": 12,
    "runtimeContext": "{\"status\": \"New\", \"priority\": \"High\"}"
  }
}

Response Structure​

Successful Start (Unsupervised Mode)​

{
  "isSuccessful": true,
  "message": "Process started successfully",
  "statusCode": "00",
  "data": {
    "instanceGuid": "abc-123-def-456",
    "status": "running",
    "currentActivityId": "Task_VerifyDocuments",
    "processDefinitiionId": 45,
    "state": {
      "variables": {
        "loanAmount": 100000,
        "customerId": 456,
        "customerName": "Jane Smith",
        "creditScore": 750
      },
      "currentNode": "Task_VerifyDocuments"
    }
  }
}

Successful Start (Supervised Mode)​

In Supervised mode, the response includes next available actions:

{
  "isSuccessful": true,
  "message": "Process started in Supervised mode. Use StepForwardCommand to proceed.",
  "statusCode": "00",
  "data": {
    "instanceGuid": "xyz-789-abc-123",
    "status": "waiting",
    "currentActivityId": "Task_ValidateCustomer",
    "executionMode": "Supervised",
    "state": {
      "variables": {
        "accountType": "Savings",
        "customerId": 123,
        "initialDeposit": 5000
      },
      "currentNode": "Task_ValidateCustomer"
    },
    "nextActions": [
      {
        "action": "stepForward",
        "label": "Execute Next Task",
        "command": "StepForwardCommand"
      },
      {
        "action": "cancel",
        "label": "Cancel Process",
        "command": "CancelProcessInstanceCommand"
      }
    ],
    "taskInfo": {
      "taskId": "Task_ValidateCustomer",
      "taskName": "Validate Customer Information",
      "taskType": "ServiceTask"
    }
  }
}

Error Responses​

Process Definition Not Found​

{
  "isSuccessful": false,
  "message": "Process definition with ID '999' not found.",
  "statusCode": "99",
  "data": null
}

Invalid Runtime Context​

{
  "isSuccessful": false,
  "message": "Invalid runtimeContext JSON format.",
  "statusCode": "99",
  "data": null
}

Invalid BPMN XML​

{
  "isSuccessful": false,
  "message": "Process definition has invalid BPMN XML.",
  "statusCode": "99",
  "data": {
    "error": "XML validation failed"
  }
}

Process Lifecycle​

Best Practices​

1. Runtime Context Design​

Good Practice:

{
  "runtimeContext": "{\"entityId\": 123, \"entityType\": \"Loan\", \"workflowData\": {\"amount\": 50000, \"term\": 24}, \"metadata\": {\"initiatedBy\": \"user@bank.com\", \"timestamp\": \"2024-12-19T10:30:00Z\"}}"
}

Why: Structured data with clear entity references and metadata for auditing.

2. Use Supervised Mode Appropriately​

  • ✅ DO use Supervised mode for:

    • Development and testing
    • Debugging issues
    • Training sessions
    • Process demonstrations

  • ❌ DON'T use Supervised mode for:

    • Production workflows
    • Batch processing
    • Scheduled jobs
    • High-volume operations

3. Context IDs for Tracking​

Always provide contextTypeId and contextId to link the process instance to your business entity:

{
  "id": 45,
  "runtimeContext": "{...}",
  "contextTypeId": 1,
  "contextId": 789
}

This enables querying process instances by entity later.

4. Error Handling​

Always check the isSuccessful flag and handle errors appropriately:

const response = await startProcess(data);

if (!response.isSuccessful) {
  console.error(`Process start failed: ${response.message}`);
  // Handle error - log, retry, notify user
  return;
}

const instanceGuid = response.data.instanceGuid;
// Continue with instanceGuid

Notes​

  • The process definition must exist and have valid BPMN XML
  • Process definition must have isExecutable="true" attribute
  • The engine automatically validates and normalizes the BPMN XML before execution
  • Each process instance gets a unique instanceGuid for tracking
  • Runtime context variables are available to all tasks via the context
  • In Supervised mode, use StepForwardCommand to execute each task
  • Process execution is asynchronous but returns immediately with status