ballerina/workflow.management Ballerina library

Cancels a pending human task by terminating its child workflow. Unlike failHumanTask, cancel does not send a result to the waiting workflow — the child workflow is terminated immediately, which causes the parent workflow's awaitHumanTask to return a HumanTaskTimeoutError or a terminal error.

check management:cancelHumanTask(taskId, cancelledBy = "admin@example.com");

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 manual retry task by sending the human's decision back to the waiting workflow. The taskWorkflowId is the child workflow ID of the retry task, available via listPendingRetryTasks or listAllRetryTasks.

// Retry with original arguments
check management:completeRetryTask(taskId, {action: "retry"});

// Retry with different input
check management:completeRetryTask(taskId, {action: "retry-with-input", input: {"orderId": "NEW-123"}});

// Permanently fail the activity
check management:completeRetryTask(taskId, {action: "fail"});

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.

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 manual retry task, including the failure context and activity arguments that triggered the task.

management:RetryTaskInfo info = check management:getRetryTaskInfo(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 manual retry task instances across all parent workflows, with optional filters. Queries Temporal's visibility API for executions whose workflow ID starts with retrytask-.

management:RetryTaskSummary[] pending = check management:listAllRetryTasks(status = "PENDING");

management:RetryTaskSummary[] recent =
    check management:listAllRetryTasks(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 manual retry task 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 retrytask-{parentWorkflowId}- prefix.

management:RetryTaskSummary[] tasks = check management:listPendingRetryTasks(parentWorkflowId);
foreach management:RetryTaskSummary task in tasks {
    check management:completeRetryTask(task.taskId, {action: "retry"});
}

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

Requests a running workflow to suspend (pause) execution. Sends a __wf_suspend signal; the workflow runtime handles blocking until resumeWorkflow is called.

check management:suspendWorkflow(workflowId);

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.