submitWorkflowTask() — Workflow Service

General Description

The submitWorkflowTask operation is how a standard user acts on the workflow task assigned to them: approve it, reject it, add a note, or hand it to someone else.

Detailed Description

submitWorkflowTask posts to /api/workflow/submitWorkflowTask. It is the end-user counterpart to the operator and debugging calls:

Operation	Who calls it	What it does
submitWorkflowTask	the task's assignee	Submits a decision on that user's own task and lets the workflow continue
iterateTask	integrations, server functions	Completes a user task programmatically and continues the rest of the workflow
iterateOnce	administrators	Advances exactly one activity and halts, for stepping and debugging

The decision is expressed as a transition choice: selection_id is the id of the GsbTransition leaving the current activity. "Approve" and "Reject" are not statuses — they are two outgoing transitions of the same approval activity, so a client must read the available transitions and present them as the choices.

Reassignment is supported by the same call: instead of choosing a transition, the task is handed to another user or position and the instance stays parked on the same activity.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The task submission, 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

The request carries a task object.

Property	Type	Required	Description
task	object	Yes	The task being submitted.
task.id	string	Yes	Id of the task assigned to the caller.
task.selection_id	string	Yes*	Id of the GsbTransition the user chose. Required for a decision; omitted when reassigning.
task.note	string	No	The user's comment, recorded on the human trail (GsbWfInstanceHistory).

Reassignment fields are part of the same task object. Their exact names are not yet verified against a live tenant and are deliberately not invented here; verify before relying on them.

Response

Success Response

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

When the caller is an administrator, instance is the full envelope described in iterateOnce. A standard user receives the fields their permissions allow.

After a successful submission the instance has either moved on to the next activity, finished, or parked again on the next human task. Read activity_id and status to tell which.

Error Response

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

Condition	message
The task is not assigned to the caller	Authorization error text from the backend
The task was already completed or reassigned	Backend error describing the stale task
selection_id is not a transition leaving the current activity	Backend validation error
Token missing, expired, or issued for another tenant	Authentication error text from the backend

Example Usage

Approve a task

const result = await entityService.submitWorkflowTask(
  {
    task: {
      id: taskId,
      selection_id: approveTransitionId,
      note: "Approved — cover arranged for the period.",
    },
  },
  token,
  tenantCode,
);

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

Offer the real choices, not hardcoded ones

const transitions = new QueryParams<GsbTransition>("GsbTransition")
  .filter("from_id", instance.activity_id)
  .select(["id", "title", "name", "route"])
  .take(20);

const options = await entityService.query(transitions, token, tenantCode);

Each returned transition is one button in the task UI, and its id is the selection_id to submit.

Additional Information

• The note is the only place a human explanation is recorded. Treat it as auditable text, not as a scratch field.
• A task is a decision on one activity. Anything that needs to move a whole run belongs to iterateTask or, for administrators, iterateOnce.
• Never submit a task on a user's behalf from model-generated code without an explicit confirmation step.