startWorkflow() — Workflow Service

General Description

The startWorkflow operation creates a workflow instance and returns as soon as the run has been accepted, without waiting for the workflow to complete.

Detailed Description

startWorkflow posts the request to /api/workflow/startWorkflow and returns the backend acknowledgement. Like every workflow call, it bypasses request batching and is sent immediately, because starting a workflow is an external side effect.

The started run is a GsbWorkflowInstance bound to a GsbWorkflow. Activities that require a person, a timer, or an external event leave the instance in a waiting state; the caller does not block on them.

Use startWorkflow for approvals, onboarding, batch processing, and anything with a human task. Use runWorkflow only when the caller genuinely needs the result inline.

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 startWorkflow --yes) or an MCP client.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The workflow start 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 start. 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 platform workflow service calls this operation with exactly { workflow_id, data }; any additional field a specific workflow design expects is forwarded unchanged.

Response

Success Response

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

{
    "success": true,
    "instance": {
        "id": "string",
        "workflow_id": "string",
        "activity_id": "string",
        "status": 0,
        "startDate": "2026-01-01T00:00:00Z"
    },
    "status": 200
}

The response acknowledges the start; it does not carry the workflow outcome. Read the outcome later from the GsbWorkflowInstance record.

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
The first activity rejects the supplied data	The validation error raised by that activity
Network or transport failure	The underlying transport error message

Example Usage

Start a workflow and record the instance

const result = await entityService.startWorkflow(
  {
    workflow_id: "workflow-uuid",
    data: { orderId: "order-123" },
  },
  token,
  tenantCode,
);

if (!result.success) {
  throw new Error(result.message);
}

const instanceId = result.instance?.id;

Poll the instance for completion

const instances = new QueryParams<GsbWorkflowInstance>("GsbWorkflowInstance")
  .filter("workflow_id", "workflow-uuid")
  .sortBy("lastUpdateDate", QuerySortType.Descending)
  .select(["id", "status", "result", "lastUpdateDate"])
  .skip(0)
  .take(25);

const page = await entityService.query(instances, token, tenantCode);

Start a workflow from the CLI

gsb call startWorkflow --yes --raw --input '{
  "request": {
    "workflow": { "name": "Employee Onboarding" },
    "data": { "employeeId": "emp-42" }
  }
}'

Additional Information

• The returned instance id is the handle for everything that follows: status polling, task iteration, and audit.
• Advance a waiting human task with iterateTask.
• Starting the same workflow twice creates two instances. Guard against duplicate starts in the caller.
• Never invoke this operation from model-generated code without an explicit user confirmation step.