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.

check management:completeHumanTask(taskWorkflowId, {approved: true, comment: "LGTM"});

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.

// Proceed with the original arguments (run the gated call / rerun the failed one)
check management:completeReviewActivity(taskId, {action: "proceed"});

// Proceed with edited arguments
check management:completeReviewActivity(taskId, {action: "proceed-with-input", input: {"orderId": "NEW-123"}});

// Reject: skip the call / fail the activity, with feedback for the agent
check management:completeReviewActivity(taskId, {action: "reject", feedback: "Amount too high"});

Classifies a management error into its ErrorCode reason.

Executes a management operation.

Parameters per operation, all optional unless stated:

• LIST_DEFINITIONS — none.
• GET_RUNTIME_INFO — none.
• LIST_INSTANCES — status, workflowType, workflowId, startedBy, limit, pageToken, startTimeFrom, startTimeTo, closeTimeFrom, closeTimeTo, taskQueue, kind (WORKFLOW, HUMAN_TASK, REVIEW_ACTIVITY, CHILD_WORKFLOW, AGENT). Without a kind the listing excludes task and review children, as it did before kinds existed; each row reports its own kind, so an unfiltered listing is still self-describing.
• START_INSTANCE — workflowType (required), input, workflowId, timeoutSeconds.
• GET_INSTANCE, SUSPEND_INSTANCE, RESUME_INSTANCE, CANCEL_INSTANCE, GET_INSTANCE_HISTORY, GET_INSTANCE_ACTIVITY_TREE, GET_INSTANCE_EXECUTION_GRAPH — workflowId (required), runId.
• WAKE_INSTANCE — workflowId (required).
• TERMINATE_INSTANCE — workflowId (required), runId, reason.
• LIST_HUMAN_TASKS — status, parentWorkflowId, parentWorkflowType, taskName, userRole, limit, pageToken, the four time bounds, taskQueue.
• LIST_WORK_ITEMS — kinds (comma list of HUMAN_TASK/REVIEW_ACTIVITY; both when absent), status, parentWorkflowId, parentWorkflowType, limit, pageToken, the four time bounds, taskQueue.
• COUNT_PENDING_HUMAN_TASKS — taskQueue.
• GET_HUMAN_TASK — taskId (required).
• COMPLETE_HUMAN_TASK — taskId (required), result.
• FAIL_HUMAN_TASK — taskId and reason (required), details.
• LIST_REVIEW_ACTIVITIES — status, parentWorkflowId, taskName, limit, pageToken, the four time bounds, taskQueue.
• GET_REVIEW_ACTIVITY — taskId (required).
• DECIDE_REVIEW_ACTIVITY — taskId and action (required), input, feedback.
• BULK_RETRY_REVIEW_ACTIVITIES — action (required, "retry" or "fail"), and exactly one of taskIds (an array of review activity IDs) or parentWorkflowId; activityName narrows a parentWorkflowId selection, feedback accompanies "fail". There is no parameter for replacement arguments: a bulk decision cannot change the payload an activity is retried with.
• LIST_RESET_POINTS — workflowId (required), runId.
• RESET_INSTANCE — workflowId and resetType (required), runId, eventId (required when resetType is "workflow-task-id"), reason, and reapply ({"type": …, "exclude": [...]}).

json|management:Error result = management:executeCommand({
    operation: management:COMPLETE_HUMAN_TASK,
    params: {taskId: "humantask-...", result: {approved: true}},
    identity: {userId: "alice", roles: ["approver"]}
});

This function authenticates nothing. It trusts command.identity as given and applies only the role checks the operations themselves perform — the same checks the HTTP API relies on once it has resolved a caller. A consumer that accepts commands from a remote channel is responsible for authenticating that channel and for populating identity from a verified credential; scope policies configured for the HTTP API (enforceScopes and friends) belong to that module and have no effect here.

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.

check management:failHumanTask(taskId, "Missing required documents",
        details = {"missingDocs": ["invoice", "receipt"]},
        callerRoles = ["finance_approver"]);

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.

import ballerina/workflow.management;

string? answer = check management:getAgentResponse(agentId);

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.

management:HumanTaskInfo info = check management:getHumanTaskInfo(taskId);

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

management:ReviewActivityInfo info = check management:getReviewActivityInfo(taskId);

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.

import ballerina/workflow.management;

WorkflowExecutionInfo info = check management:getWorkflowInfo(workflowId);

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.

import ballerina/workflow.management;

management:WorkflowMetadata meta = check management:getWorkflowMetadata();

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

string? queue = management:getWorkflowTaskQueue();

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

management:HumanTaskSummary[] pending =
    check management:listAllHumanTasks(status = "PENDING");

management:HumanTaskSummary[] recent =
    check management:listAllHumanTasks(startTimeFrom = "2026-06-01T00:00:00Z");

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

management:ReviewActivitySummary[] pending = check management:listAllReviewActivities(status = "PENDING");

management:ReviewActivitySummary[] recent =
    check management:listAllReviewActivities(startTimeFrom = "2026-06-01T00:00:00Z");

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

management:HumanTaskGroup[] groups = check management:listPendingHumanTasks(parentWorkflowId);
// groups are sorted alphabetically by taskName
foreach management:HumanTaskGroup group in groups {
    foreach string taskId in group.taskIds {
        check workflow:completeHumanTask(taskId, decision);
    }
}

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

management:ReviewActivitySummary[] tasks = check management:listPendingReviewActivities(parentWorkflowId);
foreach management:ReviewActivitySummary task in tasks {
    check management:completeReviewActivity(task.taskId, {action: "proceed"});
}

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.

management:WorkflowDefinition[] defs = check management:listWorkflowDefinitions();

Lists workflow instances with optional filtering and pagination. Excludes humantask- and reviewactivity- child workflows automatically.

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.

Everything downstream of the point runs again, including the error handling and compensation the workflow already performed on its first pass, and replay happens against the worker's current code — a workflow function that changed since the run started can fail to replay.

Resumes a previously suspended workflow by sending a __wf_resume signal.

check management:resumeWorkflow(workflowId);

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.

Starts a new workflow instance by its registered type name.

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.

Requests a running workflow to suspend (pause) execution. Sends a __wf_suspend signal; the workflow stops making progress at its next durable operation (activity call, timer, human task, retry task, or child workflow) and holds there until resumeWorkflow is called. While suspended, the workflow's reported status is SUSPENDED. An operation already in flight when the signal arrives finishes first — suspension takes effect at the next operation boundary.

check management:suspendWorkflow(workflowId);

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

check management:wakeAgent(instanceId);