ballerina/workflow.management Ballerina library

Requests graceful cancellation of a running workflow. The workflow can handle the cancellation and perform cleanup before stopping.

Completes a pending human task by sending the result back to the waiting workflow. This is the preferred API location; workflow:completeHumanTask delegates here.

Completes a pending review activity by sending the human's decision back to the waiting workflow. The taskWorkflowId is the child workflow ID of the review activity, available via listPendingReviewActivities or listAllReviewActivities.

Classifies a management error into its ErrorCode reason.

Executes a management operation. Parameters per operation are listed in the comment above.

This function authenticates nothing: command.identity is trusted as given, and only the role checks the operations themselves perform apply. A caller accepting commands from a remote channel must authenticate that channel and populate identity from a verified credential.

Moves a live task's or review's deadline: milliseconds from now, or () to let it wait indefinitely. Only an administrator of the task may ask.

Fails (rejects) a pending human task with a reason and optional structured details. Internally sends a rejection payload to the waiting workflow so it can handle the rejection case. The caller's roles are validated against the task's userRoles.

Parses the workflow execution history and returns a flat ordered list of activity, child-workflow, timer, and signal nodes with their status, timing, and I/O. Human-task and retry-task child workflows are classified with their specific types.

Gets the latest response produced by a durable agent (a workflow:DurableAgent). In a multi-turn conversation this is the answer of the most recent turn; it is available while the agent is still running (e.g. suspended waiting for the next chat event) as well as after it completes.

Derives a directed execution graph from the workflow history suitable for rendering with D3.js or React Flow. Nodes represent execution steps; edges connect them in the order they were scheduled.

Returns detailed info for a single human task, including memo fields. Calls Temporal DescribeWorkflowExecution to read the memo set at task creation.

Returns detailed info for a single review activity, including the failure context, the activity arguments that triggered the task, and the JSON Schema of the input accepted by the proceed-with-input decision (formSchema).

Returns all execution history events for a workflow run in chronological order. Each event includes an event-type-specific attribute map suitable for timeline display.

Gets current execution info for a workflow without waiting for it to finish. Returns the status, workflow type, and ID.

Gets execution info for a specific run of a workflow, identified by both workflow ID and run ID. Unlike getWorkflowInfo, this targets the exact run rather than the latest run.

Returns the workflow metadata document for this program: registered workflow definitions, human tasks, activities, and durable agents, with their JSON schemas. The document is complete at module init — before any workflow has executed — so it is safe to read once at startup and publish to a control plane.

Returns the Temporal task queue this program's worker serves, or nil before the worker has registered. The queue is chosen at program startup — worker configuration, not workflow metadata — which is why it is exposed on its own rather than inside the metadata document: a control plane treats it as runtime state, like capabilities. Integrations in one project share a Temporal namespace, so the queue is the only attribute separating one integration's executions from its neighbours'.

Lists all human task instances across all parent workflows, with optional filters. Queries Temporal's visibility API for executions whose workflow TYPE starts with humantask-. The taskName and parentWorkflowId fields are extracted from the task's Temporal memo (set when the task was created by awaitHumanTask).

Lists all review activity instances across all parent workflows, with optional filters. Queries Temporal's visibility API for executions whose workflow TYPE starts with reviewactivity-.

Returns the pending human task child workflows started by the given parent workflow, grouped by task type and sorted alphabetically by task name. Scans the parent's event history for child workflow start events whose workflow TYPE has the humantask- prefix (the ID itself is a bare UUID; what a task is travels in its type and memo).

Returns pending review activity child workflows started by the given parent workflow, grouped by task name and sorted alphabetically. Scans the parent's event history for child workflow start events whose workflow TYPE has the reviewactivity- prefix (the ID itself is a bare UUID).

Returns the events this run can be reset to — its workflow-task events — each annotated with the activity-tree nodes that task scheduled. A reset target is a workflow task, so the annotation is what lets a caller see which steps a point re-runs before choosing it.

Lists all workflow types registered with this worker, for use in the workflow launcher UI. Returns one entry per registered workflow function. The inputSchema field is derived at runtime from the registered workflow function's signature, or () when the workflow takes no data input.

Lists workflow instances, excluding human task and review activity children.

Reassigns a live task or review: each named audience list replaces the declared one. Only an administrator of the task may ask; the act is recorded in the task's history.

Resets a run to a workflow-task event: history up to that point is preserved and everything after it re-executes as a new run of the same workflow ID — including compensation the run already performed, and against the worker's current code.

Resumes a previously suspended workflow by sending a __wf_resume signal.

Resumes a specific run of a suspended workflow. Targets the exact runId rather than the latest run, which is correct when a workflow ID has multiple historical runs.

Sends a named data event to a running workflow instance, addressing it by ID — the management-side counterpart of workflow:sendData. The event is durable once accepted, so an instance that has not reached its wait yet still receives it.

Starts a workflow or durable agent by its registered type name. With instanceId the id is the caller's — a business key that doubles as the correlation key — and the policies say what happens when it is already held: a ConflictError when the policy refuses, an InvalidRequestError for an unacceptable id or policy.

Starts a new workflow instance by its registered type name.

Requests a running workflow to pause. It stops at its next durable operation and holds there until resumeWorkflow; while paused its status reads SUSPENDED.

Suspends a specific run of a workflow. Targets the exact runId rather than the latest run, which is correct when a workflow ID has multiple historical runs.

Terminates a running workflow immediately with an optional reason. Unlike cancel, terminate does not allow the workflow to perform cleanup.

The canonical JSON representation of a management error: {"error": {"message": "..."}}. Every transport serializes errors this way, so a consumer sees the same payload whichever path the operation was invoked through.

Wakes a durable agent instance out of its built-in sleep tool. Harmless when the instance is not sleeping: the request is consumed by the next sleep.