Skip to main content

Signal Process

Overview​

The SignalProcessInstanceCommand sends data/signals to a waiting process instance. This is used to resume processes that are paused at UserTask nodes or waiting for external events.

API Endpoint​

POST /api/core/cmd

Headers​

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

Request Structure​

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "abc-123-def-456",
    "signalData": "{\"approved\": true, \"comments\": \"Application looks good\"}"
  }
}

Request Fields​

FieldTypeRequiredDescription
instanceGuidstringYesThe unique identifier of the process instance to signal
signalDatastring (JSON)YesData to send to the process as JSON string

When to Use Signal Process​

Completing UserTasks​

When a process reaches a UserTask and waits for human action:

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "loan-approval-123",
    "signalData": "{\"action\": \"approve\", \"officerComments\": \"Credit score acceptable\", \"approvedAmount\": 50000}"
  }
}

Providing External Data​

When a process waits for external system responses or data:

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "kyc-verification-456",
    "signalData": "{\"kycStatus\": \"verified\", \"kycScore\": 95, \"verificationDate\": \"2024-12-19\"}"
  }
}

Resuming After Pause​

When a process is intentionally paused and needs to resume:

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "payment-processing-789",
    "signalData": "{\"resume\": true, \"reason\": \"Manual review completed\"}"
  }
}

Sample Requests​

1. Approve Loan Application​

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "loan-app-2024-001",
    "signalData": "{\"userAction\": \"approve\", \"approvedBy\": \"john.doe@bank.com\", \"approvedAmount\": 75000, \"interestRate\": 5.5, \"term\": 36, \"conditions\": [\"Provide proof of income\", \"Valid ID required\"], \"approvalDate\": \"2024-12-19T14:30:00Z\"}"
  }
}

2. Reject Application​

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "loan-app-2024-002",
    "signalData": "{\"userAction\": \"reject\", \"rejectedBy\": \"jane.smith@bank.com\", \"rejectionReason\": \"Insufficient credit score\", \"creditScore\": 580, \"minimumRequired\": 650}"
  }
}

3. Request More Information​

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "account-opening-789",
    "signalData": "{\"userAction\": \"requestInfo\", \"requiredDocuments\": [\"Utility bill\", \"Employment letter\"], \"requestedBy\": \"cs@bank.com\", \"dueDate\": \"2024-12-25\"}"
  }
}

4. Complete KYC Verification​

{
  "cmd": "SignalProcessInstanceCommand",
  "data": {
    "instanceGuid": "kyc-process-456",
    "signalData": "{\"kycCompleted\": true, \"verificationMethod\": \"Video Call\", \"verifiedBy\": \"compliance@bank.com\", \"documentsVerified\": [\"Passport\", \"Address Proof\"], \"riskLevel\": \"Low\"}"
  }
}

Response Structure​

Successful Signal (Process Continues)​

{
  "isSuccessful": true,
  "message": "Process signaled successfully and continued execution",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-app-2024-001",
    "status": "running",
    "currentActivityId": "Task_DisburseL oan",
    "result": {
      "message": "Signal processed successfully",
      "nextActions": [
        {
          "action": "continue",
          "label": "Process Continuing",
          "currentTask": "Task_DisburseLoan"
        }
      ],
      "waiting": false
    },
    "stateJson": "{...}",
    "nextActions": [...]
  }
}

Successful Signal (Process Waiting Again)​

{
  "isSuccessful": true,
  "message": "Process signaled successfully and is waiting at next UserTask",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-app-2024-001",
    "status": "waiting",
    "currentActivityId": "Task_ManagerApproval",
    "result": {
      "message": "Waiting for manager approval",
      "nextActions": [
        {
          "action": "approve",
          "label": "Approve",
          "userAction": true
        },
        {
          "action": "reject",
          "label": "Reject",
          "userAction": true
        }
      ],
      "waiting": true
    },
    "taskInfo": {
      "taskId": "Task_ManagerApproval",
      "taskName": "Manager Approval Required",
      "taskType": "UserTask",
      "assignedTo": "managers"
    }
  }
}

Successful Signal (Process Completed)​

{
  "isSuccessful": true,
  "message": "Process completed successfully",
  "statusCode": "00",
  "data": {
    "instanceGuid": "loan-app-2024-001",
    "status": "completed",
    "currentActivityId": "EndEvent_Success",
    "result": {
      "message": "Process completed",
      "finalVariables": {
        "loanId": 12345,
        "approvedAmount": 75000,
        "disbursementDate": "2024-12-20"
      },
      "waiting": false
    }
  }
}

Error Responses​

Instance Not Found​

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

Instance Not Waiting​

{
  "isSuccessful": false,
  "message": "Process instance is not in a waiting state. Current status: running",
  "statusCode": "99",
  "data": {
    "currentStatus": "running"
  }
}

Invalid Signal Data​

{
  "isSuccessful": false,
  "message": "Invalid signal data JSON format",
  "statusCode": "99",
  "data": {
    "error": "Unexpected character at position 15"
  }
}

Signal Data Structure​

The signalData must be a JSON string. Variables provided here are merged into the process context:

Before Signal​

{
  "loanAmount": 50000,
  "customerId": 123,
  "status": "pending"
}

Signal Data​

"{\"userAction\": \"approve\", \"approvedAmount\": 75000, \"approvedBy\": \"manager@bank.com\"}"

After Signal (Merged Context)​

{
  "loanAmount": 50000,
  "customerId": 123,
  "status": "pending",
  "userAction": "approve",
  "approvedAmount": 75000,
  "approvedBy": "manager@bank.com"
}

Process Flow with Signals​

Best Practices​

1. Include Context in Signal Data​

Always include relevant context to help downstream tasks:

Good:

{
  "signalData": "{\"action\": \"approve\", \"approvedBy\": \"john@bank.com\", \"timestamp\": \"2024-12-19T10:30:00Z\", \"approvedAmount\": 50000, \"comments\": \"All checks passed\"}"
}

Bad:

{
  "signalData": "{\"action\": \"approve\"}"
}

2. Use Consistent Action Names​

Define standard action names across your processes:

// Standard actions
"userAction": "approve"
"userAction": "reject"
"userAction": "requestMoreInfo"
"userAction": "escalate"

3. Validate State Before Signaling​

Check that the process is in the correct state:

// First, get process state
const state = await getProcessState(instanceGuid);

if (state.status !== 'waiting') {
  console.error('Process is not waiting for signal');
  return;
}

// Then signal
await signalProcess(instanceGuid, signalData);

4. Handle Different Outcomes​

The process may continue, wait again, or complete after signaling:

const response = await signalProcess(instanceGuid, signalData);

switch (response.data.status) {
  case 'waiting':
    // Process is waiting at another UserTask
    showNextTaskForm(response.data.taskInfo);
    break;
    
  case 'running':
    // Process is executing automatically
    showProcessingMessage();
    break;
    
  case 'completed':
    // Process finished
    showCompletionMessage(response.data.result);
    break;
    
  case 'error':
    // Something went wrong
    showErrorMessage(response.message);
    break;
}

Notes​

  • The process must be in "waiting" state to receive signals
  • Signal data is merged with existing process variables
  • If a variable already exists, it will be overwritten by signal data
  • The process automatically continues after receiving the signal
  • If the process encounters another UserTask, it will pause again
  • All signal operations are logged for audit purposes
  • Signal data should be a valid JSON string