Trigger Workflow Action — Action System

How It Works

When the Trigger Workflow action executes, App Studio calls:

POST /api/workflows/{processId}/execute
Content-Type: application/json
Authorization: Bearer {userToken}

{
  "input": {
    "leadId": "lead-123",
    "approvedBy": "user-jane",
    "tenantId": "tenant-001"
  }
}

This is handled by WorkflowTriggerActionHandler.cs on the backend, which calls the Flow Studio execution API. The action resolves all token expressions in the input before making the call.

Trigger Workflow Action Config

// TriggerWorkflowActionConfig
{
  "type": "trigger-workflow",
  "processId": "lead-approval-process",   // Flow Studio process definition ID
  "input": {
    "leadId": "{{ route.id }}",
    "requestedBy": "{{ context.userId }}",
    "priority": "{{ variables.selectedPriority }}"
  },
  "waitForCompletion": false,             // default: fire-and-forget
  "onSuccess": {
    "type": "navigate",
    "target": "/leads",
    "params": { "msg": "Workflow started" }
  },
  "onError": {
    "type": "set-variable",
    "variable": "errorMessage",
    "value": "Failed to start workflow. Please retry."
  }
}

Fire-and-Forget vs. Wait for Completion

Mode	`waitForCompletion`	Behavior	Use Case
Fire-and-forget	false (default)	Action starts the workflow and immediately runs `onSuccess`. Does not wait for the workflow to finish.	Long-running processes (approval chains, batch jobs)
Wait	true	Action starts the workflow and waits for it to complete. `onSuccess` receives the workflow output.	Short synchronous processes (data validation, quick lookups)

Accessing Workflow Output (When Waiting)

// Wait mode — workflow output available in onSuccess
{
  "type": "trigger-workflow",
  "processId": "validate-lead-data",
  "waitForCompletion": true,
  "input": { "leadId": "{{ route.id }}" },
  "onSuccess": {
    "type": "chain",
    "actions": [
      {
        "type": "set-variable",
        "variable": "validationResult",
        "value": "{{ workflowOutput.isValid }}"
      },
      {
        "type": "navigate",
        "target": "/leads/{{ route.id }}/confirm"
      }
    ]
  }
}
// workflowOutput.* contains the fields returned by the workflow's terminal node

Authentication Context

The workflow trigger call includes the current user's Passport JWT token. The Flow Studio process engine validates this token and uses it for IAM checks within the workflow. This means the workflow runs in the context of the triggering user — not a service account.

← Submit Form Next: Open Modal →