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"});

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.

Lists all human task instances across all parent workflows, with optional filters. Queries Temporal's visibility API and filters executions whose workflow ID 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 ID 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 ID matches the humantask-<parentWorkflowId>- prefix.

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 ID starts with the reviewactivity-{parentWorkflowId}- prefix.

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

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 () until the compiler plugin generates JSON Schema at build time.

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

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

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.

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