runWorkflow() — Workflow Service

General Description

The runWorkflow operation executes a workflow and waits for the backend to finish processing before returning.

Detailed Description

runWorkflow posts the request to the workflow endpoint /api/workflow/runWorkflow and returns the backend response to the caller. Unlike entity reads and writes, workflow calls are never batched: the transport sends them immediately rather than folding them into a bulk request, because a workflow can trigger external side effects.

A workflow is a GsbWorkflow record in the tenant, composed of GsbActivity nodes and GsbTransition edges. Executing it creates a GsbWorkflowInstance that records the run.

Use runWorkflow when the caller needs the outcome of the run. Use startWorkflow when the workflow contains human tasks, long waits, or anything else the caller should not block on.

In the tool registry this operation is classified external-side-effect. It is disabled by default and requires explicit approval before it can be invoked through the CLI (gsb call runWorkflow --yes) or an MCP client.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The workflow execution request, forwarded to the backend without transformation.
token	string	No	Authentication token for the request. The MCP/CLI runtime injects the verified session token when it invokes this operation; direct service callers must provide or configure credentials.
tenantCode	string	No	Tenant context for the request. The MCP/CLI runtime injects the verified session tenant; direct service callers must provide or resolve tenant context from their verified session.

Request Object Structure

Property	Type	Required	Description
instance	object	Yes	The GsbWorkflowInstance execution envelope.
awaitFlow	boolean	Yes	Wait for completion when true.

The instance requires workflow_id. It can also contain entity, entity_id, entityDefinition_id, serialized parameters, and other workflow-instance fields. When both entity and entityDefinition_id are supplied, the platform saves the entity with the instance.

Set instance.delay, measured in seconds, or instance.scheduledTime to defer a one-off run without a process trigger. For reusable process metadata, set instance.trigger to an inline GsbProcessTrigger, or set instance.trigger_id to the id of a saved trigger. The trigger supports ProcessTiming.Immediately, ProcessTiming.Delayed with delay in seconds, and ProcessTiming.Scheduled with scheduledTime.

Response

Success Response

The backend response is returned with success: true merged in.

{
    "success": true,
    "instance": {
        "id": "string",
        "workflow_id": "string",
        "status": 0,
        "result": "string"
    },
    "status": 200
}

The exact payload depends on the workflow design. The fields that are always meaningful come from GsbWorkflowInstance: id, workflow_id, activity_id, entity_id, status, result, responseStr, startDate, and lastUpdateDate.

Error Response

Every failure is normalised to the same shape; the operation does not throw across the tool boundary.

{
    "success": false,
    "message": "Error message describing what went wrong"
}

Condition	message
No workflow matches the supplied id or name	Backend error text describing the missing workflow
Caller lacks permission on the workflow or tenant	Authorization error text from the backend
Token missing, expired, or issued for another tenant	Authentication error text from the backend
An activity function throws during the run	The error raised by that function
Network or transport failure	The underlying transport error message

Example Usage

Run a workflow by ID

const result = await entityService.runWorkflow(
  {
    instance: {
      workflow_id: "workflow-uuid",
      entity_id: "order-123",
      parameters: JSON.stringify({ reason: "manual reprocess" }),
    },
    awaitFlow: true,
  },
  token,
  tenantCode,
);

if (result.success) {
  console.log("Instance:", result.instance?.id);
} else {
  console.error("Workflow failed:", result.message);
}

Run a workflow by name from the CLI

gsb call runWorkflow --yes --raw --input '{
  "request": {
    "instance": {
      "workflow_id": "workflow-uuid",
      "entity_id": "order-123",
      "parameters": "{\"reason\":\"manual reprocess\"}"
    },
    "awaitFlow": true
  }
}'

--yes is required: the tool is registered as an external side effect and is otherwise refused.

Additional Information

• A deferred response contains an instance with scheduleId. Pass that value as jobId to POST /api/task/getJobStatus or POST /api/task/cancelTask.
• Prefer startWorkflow for anything that waits on a human. A synchronous run holds the connection open for the whole duration.
• Inspect a run afterwards by querying GsbWorkflowInstance with query, filtering on workflow_id and sorting by lastUpdateDate.
• Advance a task that the run left waiting with iterateTask.
• Never invoke this operation from model-generated code without an explicit user confirmation step.