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. 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	Whether the backend should wait for workflow completion. Normally false for this operation.

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 start 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",
        "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(
  {
    instance: {
      workflow_id: "workflow-uuid",
      entity_id: "order-123",
    },
    awaitFlow: false,
  },
  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": {
    "instance": {
      "workflow_id": "workflow-uuid",
      "entity_id": "emp-42"
    },
    "awaitFlow": false
  }
}'

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