Get Process State

Overview

The GetProcessInstanceStateCommand retrieves the current status, variables, and execution state of a running or completed process instance.

API Endpoint

POST /api/core/cmd

Headers

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

Request Structure

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

Request Fields

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

Sample Requests

1. Check Process Status

{
  "cmd": "GetProcessInstanceStateCommand",
  "data": {
    "instanceGuid": "loan-approval-2024-001"
  }
}

2. Monitor Running Process

{
  "cmd": "GetProcessInstanceStateCommand",
  "data": {
    "instanceGuid": "batch-job-789"
  }
}

Response Structure

Running Process (Unsupervised)

{
  "isSuccessful": true,
  "message": "Process state retrieved successfully",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-approval-2024-001",
    "processDefinitionId": 45,
    "processKey": "LoanApproval_v1",
    "processName": "Loan Approval Workflow",
    "businessKey": "LOAN-2024-001",
    "status": "running",
    "executionMode": "Unsupervised",
    "currentActivityId": "Task_ManagerApproval",
    "startedAt": "2024-12-19T10:00:00Z",
    "lastUpdated": "2024-12-19T10:15:30Z",
    "state": {
      "variables": {
        "loanId": 789,
        "loanAmount": 100000,
        "customerId": 456,
        "customerName": "Jane Smith",
        "creditScore": 750,
        "riskLevel": "Medium",
        "automaticApproval": false
      },
      "currentNode": "Task_ManagerApproval",
      "completedTasks": [
        "StartEvent",
        "Task_ValidateCustomer",
        "Task_CreditCheck",
        "Task_RiskAssessment",
        "Gateway_AutoApprove"
      ]
    },
    "contextType": "Loan",
    "contextId": 789
  }
}

Waiting Process (at UserTask)

{
  "isSuccessful": true,
  "message": "Process is waiting for user action",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-approval-2024-001",
    "processDefinitionId": 45,
    "status": "waiting",
    "executionMode": "Unsupervised",
    "currentActivityId": "Task_ManagerApproval",
    "waiting": true,
    "currentTask": {
      "taskId": "Task_ManagerApproval",
      "taskName": "Manager Approval Required",
      "taskType": "UserTask",
      "assignedTo": "managers",
      "waitingSince": "2024-12-19T10:15:30Z"
    },
    "state": {
      "variables": {
        "loanId": 789,
        "loanAmount": 100000,
        "creditScore": 750,
        "recommendation": "approve"
      },
      "currentNode": "Task_ManagerApproval"
    },
    "nextActions": [
      {
        "action": "approve",
        "label": "Approve Loan",
        "userAction": true
      },
      {
        "action": "reject",
        "label": "Reject Loan",
        "userAction": true
      },
      {
        "action": "requestMoreInfo",
        "label": "Request More Information",
        "userAction": true
      }
    ]
  }
}

Completed Process

{
  "isSuccessful": true,
  "message": "Process completed successfully",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-approval-2024-001",
    "processDefinitionId": 45,
    "status": "completed",
    "executionMode": "Unsupervised",
    "currentActivityId": "EndEvent_Success",
    "startedAt": "2024-12-19T10:00:00Z",
    "completedAt": "2024-12-19T10:45:15Z",
    "duration": "45m 15s",
    "state": {
      "variables": {
        "loanId": 789,
        "loanAmount": 100000,
        "approved": true,
        "approvedAmount": 100000,
        "approvedBy": "manager@bank.com",
        "disbursementScheduled": true,
        "disbursementDate": "2024-12-20"
      },
      "completedTasks": [
        "StartEvent",
        "Task_ValidateCustomer",
        "Task_CreditCheck",
        "Task_RiskAssessment",
        "Gateway_AutoApprove",
        "Task_ManagerApproval",
        "Task_DisburseLoan",
        "EndEvent_Success"
      ]
    },
    "summary": {
      "totalTasks": 6,
      "totalDuration": "45m 15s",
      "outcome": "success"
    }
  }
}

Process in Error State

{
  "isSuccessful": true,
  "message": "Process is in error state",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-approval-2024-002",
    "processDefinitionId": 45,
    "status": "error",
    "executionMode": "Unsupervised",
    "currentActivityId": "Task_CreditCheck",
    "error": {
      "taskId": "Task_CreditCheck",
      "taskName": "Perform Credit Check",
      "errorMessage": "Credit bureau service unavailable",
      "errorDetails": "Connection timeout after 30 seconds",
      "occurredAt": "2024-12-19T10:10:45Z"
    },
    "state": {
      "variables": {
        "loanId": 790,
        "customerId": 457,
        "creditScore": null
      },
      "currentNode": "Task_CreditCheck",
      "completedTasks": [
        "StartEvent",
        "Task_ValidateCustomer"
      ]
    },
    "nextActions": [
      {
        "action": "retry",
        "label": "Retry Failed Task",
        "command": "RetryFailedTaskCommand"
      },
      {
        "action": "skip",
        "label": "Skip Failed Task",
        "command": "SkipFailedTaskCommand"
      },
      {
        "action": "cancel",
        "label": "Cancel Process",
        "command": "CancelProcessInstanceCommand"
      }
    ]
  }
}

Supervised Mode Process

{
  "isSuccessful": true,
  "message": "Supervised process waiting at current task",
  "statusCode": "00",
  "data": {
    "instanceGuid": "test-process-supervised-001",
    "processDefinitionId": 12,
    "status": "waiting",
    "executionMode": "Supervised",
    "currentActivityId": "Task_ProcessData",
    "currentTask": {
      "taskId": "Task_ProcessData",
      "taskName": "Process Customer Data",
      "taskType": "ServiceTask",
      "position": 3,
      "totalTasks": 7
    },
    "state": {
      "variables": {
        "customerId": 123,
        "dataProcessed": false
      },
      "completedTasks": [
        "StartEvent",
        "Task_LoadData",
        "Task_ValidateData"
      ],
      "currentNode": "Task_ProcessData"
    },
    "nextActions": [
      {
        "action": "stepForward",
        "label": "Execute This Task",
        "command": "StepForwardCommand"
      },
      {
        "action": "stepBackward",
        "label": "Go Back",
        "command": "StepBackwardCommand"
      },
      {
        "action": "cancel",
        "label": "Cancel",
        "command": "CancelProcessInstanceCommand"
      }
    ],
    "progress": {
      "current": 3,
      "total": 7,
      "percentage": 42.86
    }
  }
}

Error Responses

Process Not Found

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

Process Status Values

Status	Description	Actions Available
running	Process executing automatically	Monitor, Cancel
waiting	Paused at UserTask	Signal, Get State, Cancel
completed	Successfully finished	View Results
error	Task failed	Retry, Skip, Cancel
cancelled	User terminated	View Final State

Use Cases

1. Monitor Long-Running Process

async function monitorProcess(instanceGuid) {
  const pollInterval = 5000; // 5 seconds
  
  const monitor = setInterval(async () => {
    const response = await getProcessState(instanceGuid);
    
    console.log(`Status: ${response.data.status}`);
    console.log(`Current Task: ${response.data.currentActivityId}`);
    
    if (response.data.status === "completed") {
      console.log("Process completed successfully");
      console.log("Results:", response.data.state.variables);
      clearInterval(monitor);
    } else if (response.data.status === "error") {
      console.error("Process failed:", response.data.error.errorMessage);
      clearInterval(monitor);
    }
  }, pollInterval);
}

2. Check if Process is Waiting

async function checkIfWaiting(instanceGuid) {
  const response = await getProcessState(instanceGuid);
  
  if (response.data.status === "waiting" && response.data.waiting) {
    console.log("Process is waiting at:", response.data.currentTask.taskName);
    console.log("Available actions:", response.data.nextActions);
    
    // Show UI for user to take action
    return {
      waiting: true,
      task: response.data.currentTask,
      actions: response.data.nextActions
    };
  }
  
  return { waiting: false };
}

3. Display Process Progress

async function displayProgress(instanceGuid) {
  const response = await getProcessState(instanceGuid);
  
  const completed = response.data.state.completedTasks.length;
  const total = response.data.progress?.total || 
                response.data.state.completedTasks.length + 1;
  const percentage = ((completed / total) * 100).toFixed(1);
  
  return {
    status: response.data.status,
    currentTask: response.data.currentTask?.taskName,
    completed: completed,
    total: total,
    percentage: percentage,
    duration: calculateDuration(response.data.startedAt)
  };
}

4. Extract Process Variables

async function getProcessVariables(instanceGuid) {
  const response = await getProcessState(instanceGuid);
  
  if (response.isSuccessful) {
    return response.data.state.variables;
  }
  
  throw new Error(`Failed to get variables: ${response.message}`);
}

// Usage
const vars = await getProcessVariables("loan-app-001");
console.log("Loan Amount:", vars.loanAmount);
console.log("Customer ID:", vars.customerId);
console.log("Credit Score:", vars.creditScore);

5. Handle Process Errors

async function handleProcessErrors(instanceGuid) {
  const response = await getProcessState(instanceGuid);
  
  if (response.data.status === "error") {
    const error = response.data.error;
    
    // Log error details
    console.error(`Task ${error.taskName} failed:`, error.errorMessage);
    
    // Notify administrators
    await notifyAdmins({
      instanceGuid,
      taskId: error.taskId,
      errorMessage: error.errorMessage,
      occurredAt: error.occurredAt
    });
    
    // Present recovery options
    return {
      error: true,
      task: error.taskName,
      message: error.errorMessage,
      actions: response.data.nextActions
    };
  }
  
  return { error: false };
}

Best Practices

1. Poll Efficiently

// Use exponential backoff for polling
class ProcessPoller {
  constructor(instanceGuid, maxInterval = 30000) {
    this.instanceGuid = instanceGuid;
    this.interval = 1000; // Start with 1 second
    this.maxInterval = maxInterval;
  }
  
  async poll(callback) {
    const response = await getProcessState(this.instanceGuid);
    callback(response);
    
    if (response.data.status === "running") {
      // Increase interval for running processes
      this.interval = Math.min(this.interval * 1.5, this.maxInterval);
    } else {
      // Use shorter interval for waiting/error states
      this.interval = 2000;
    }
    
    if (!["completed", "cancelled"].includes(response.data.status)) {
      setTimeout(() => this.poll(callback), this.interval);
    }
  }
}

2. Cache State Information

class ProcessStateCache {
  constructor(ttl = 5000) {
    this.cache = new Map();
    this.ttl = ttl;
  }
  
  async get(instanceGuid) {
    const cached = this.cache.get(instanceGuid);
    
    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.data;
    }
    
    const response = await getProcessState(instanceGuid);
    this.cache.set(instanceGuid, {
      data: response,
      timestamp: Date.now()
    });
    
    return response;
  }
}

3. Handle All Status Types

async function processStatusHandler(instanceGuid) {
  const response = await getProcessState(instanceGuid);
  
  switch (response.data.status) {
    case "running":
      return handleRunning(response.data);
    case "waiting":
      return handleWaiting(response.data);
    case "completed":
      return handleCompleted(response.data);
    case "error":
      return handleError(response.data);
    case "cancelled":
      return handleCancelled(response.data);
    default:
      throw new Error(`Unknown status: ${response.data.status}`);
  }
}

Related Commands

• Start Process - Initiate new process instance
• Signal Process - Send data to waiting process
• Cancel Process - Terminate running process
• Step Forward - Execute next task (Supervised)
• Step Backward - Review previous task (Supervised)

Notes

• Can be called at any time during process execution
• Returns current state without modifying the process
• Useful for monitoring and debugging
• nextActions array provides available commands for current state
• Variables reflect the current process context
• Completed tasks list shows execution history
• Duration calculated from start time to current/completion time
• Supervised mode processes show additional navigation information
• Error states include detailed error information and recovery options