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. Falls back to the configured credentials when omitted.
tenantCode	string	No	Tenant whose data to operate on. Falls back to the tenant encoded in the token or the configured tenant.

Request Object Structure

Property	Type	Required	Description
workflow_id	string	Yes*	ID of the GsbWorkflow to execute. Required when workflow is not supplied.
workflow	object	Yes*	Workflow reference carrying id and/or name. Required when workflow_id is not supplied.
entity_id	string	No	ID of the entity the run operates on. Recorded on the resulting workflow instance.
data	object	No	Payload made available to the workflow activities and their functions.

The request object is forwarded verbatim, so any additional field a specific workflow design expects is passed through unchanged.

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(
  {
    workflow_id: "workflow-uuid",
    data: { orderId: "order-123", reason: "manual reprocess" },
  },
  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": {
    "workflow": { "name": "Order Approval" },
    "entity_id": "order-123",
    "data": { "reason": "manual reprocess" }
  }
}'

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

Additional Information

• 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.