Skip to main content

Workflow Orchestration

The workflow orchestration functions allow scripts to trigger other workflows as sub-workflows and look up workflows by name. These functions are injected into the V8 execution context alongside all other script globals.

triggerWorkflow​

Trigger a sub-workflow by dispatching a new message to the Kinesis stream. The sub-workflow receives the full current execution state — all message fields and script variables accumulated so far — automatically.

Signature​

await triggerWorkflow(workflowId)

Parameters​

ParameterTypeRequiredDescription
workflowIdstringYesThe UUID of the workflow to trigger

Returns​

{
  success: boolean;
  workflowId: string;
  sequenceNumber: string;   // Kinesis sequence number for the dispatched record
}

How It Works​

  1. The function captures a snapshot of the entire V8 global scope (all non-function, non-internal globals)
  2. A new Kinesis message is constructed with the captured state plus control fields (type, triggerType, workflowId)
  3. The message is put onto the Kinesis stream
  4. The consumer picks up the message and runs the target workflow with the inherited state

The Kinesis trigger message has this structure:

{
  "organizationId": "org-uuid",
  "environmentId": "env-uuid",
  "type": "workflow_trigger",
  "triggerType": "sub_workflow",
  "workflowId": "target-workflow-uuid",
  "parentTimestamp": "2026-03-31T12:00:00.000Z",
  "payload": { "...inherited from parent..." },
  "promptResponse_1": "...inherited from parent...",
  "customVar": "...any script variable set in the parent..."
}

Examples​

Trigger a known workflow by ID:

const result = await triggerWorkflow("550e8400-e29b-41d4-a716-446655440099");
print("Triggered sub-workflow:", result.workflowId);
print("Kinesis sequence:", result.sequenceNumber);

Trigger a workflow after processing, passing accumulated state:

// Earlier entities have set promptResponse_1 and custom variables
print("Current payload:", JSON.stringify(payload));

// The sub-workflow will receive everything: payload, promptResponse_1, etc.
const result = await triggerWorkflow("abc-123-def");

if (result.success) {
  print("Sub-workflow dispatched successfully");
}

Error Handling​

try {
  await triggerWorkflow("invalid-or-missing-id");
} catch (error) {
  print("Failed to trigger:", error.message);
}

Common errors:

ErrorCause
workflowId is required and must be a non-empty stringMissing or invalid argument
organizationId and environmentId are required in the current contextMessage fields not available in the V8 global scope

getWorkflowByName​

Look up a workflow by its display name within the current organization and environment. Useful when you know the workflow name but not its UUID.

Signature​

await getWorkflowByName(name)

Parameters​

ParameterTypeRequiredDescription
namestringYesThe exact name of the workflow to find (case-sensitive)

Returns​

{
  id: string;     // The workflow's UUID
  name: string;   // The workflow's display name
}

Examples​

Look up a workflow and trigger it:

const orderWorkflow = await getWorkflowByName("Process Order");
print("Found workflow:", orderWorkflow.id);

const result = await triggerWorkflow(orderWorkflow.id);
print("Triggered:", result.sequenceNumber);

Conditional sub-workflow dispatch based on message data:

const workflowName = type === "order.created"
  ? "Process New Order"
  : "Handle General Event";

try {
  const wf = await getWorkflowByName(workflowName);
  await triggerWorkflow(wf.id);
  print("Dispatched to:", workflowName);
} catch (error) {
  print("Workflow not found:", workflowName, error.message);
}

Error Handling​

ErrorCause
name is required and must be a non-empty stringMissing or invalid argument
Workflow not found with name "X" in org ... env ...No workflow with that exact name exists in the current org/env

Sub-Workflow vs. Workflow Nodes​

There are two ways to invoke sub-workflows:

MethodWhen to Use
Workflow node on canvasStatic orchestration — the sub-workflow is a fixed part of the workflow graph and is always triggered when that node is reached
triggerWorkflow() in a scriptDynamic orchestration — trigger sub-workflows conditionally based on runtime data, or dispatch to different workflows based on logic

Both methods propagate the full V8 execution state to the sub-workflow. The key difference is that workflow nodes are visual and validated at design time (including loop detection), while script-based triggers are flexible and determined at runtime.

State Propagation​

When a sub-workflow is triggered (by either method), the following state is captured and sent:

  • All top-level message fields (organizationId, environmentId, type, payload, etc.)
  • All prompt responses (promptResponse_1, promptResponse_2, etc.)
  • All script-defined variables
  • Entity arguments injected earlier in the workflow

Internal/private globals (names starting with __) and functions are excluded.

The sub-workflow's prompt indexing continues from the parent's count. If the parent workflow produced promptResponse_1, the sub-workflow's first prompt will be stored as promptResponse_2.