ballerina/workflow Ballerina library

Executes an activity function. A completed activity is never re-executed on workflow replay — its recorded result is reused, even across process crashes and restarts. A failed attempt may run again, however: AutoRetry re-executes the activity automatically and HumanReview lets a human rerun it, so make the activity's side effects idempotent (or deduplicate them) when retries are enabled.

PaymentResult result = check ctx->callActivity(processPayment, args = {"orderId": orderId});

Waits for at least minCount data futures to complete. Results are a positional tuple aligned to input order. Use nullable types (T?) for partial waits.

The result can be captured in several ways:

// Wait for all (tuple binding pattern)
[Approval, Payment] [approval, payment] = check ctx->await([events.approval, events.payment]);
// Capture the whole result, including a possible timeout, without `check`
[Approval, Payment]|error result = ctx->await([events.approval, events.payment]);
if result is error { /* handle timeout */ }
// Handle each position independently (a slot is a value or an error)
[Approval|error, Payment|error] [a, p] = check ctx->await([events.approval, events.payment]);
// Wait for any (1 of 2) — use nilable members for partial waits
[Approval?, Payment?] result = check ctx->await([events.approval, events.payment], minCount = 1);

Creates a human task and blocks until a human completes it or the optional timeout elapses. Internally, the task is modelled as a durable Temporal child workflow whose type is taskName, so the task survives worker restarts. Register the task name at module init time via wfInternal:registerHumanTask(taskName) (the compiler plugin generates this call automatically).

ApprovalDecision d = check ctx->awaitHumanTask("approveExpense", "FINANCE_APPROVER",
    payload = {"amount": 1200, "currency": "USD"},
    title = "Approve order",
    timeout = {hours: 24}
) on fail workflow:HumanTaskTimeoutError e {
    check ctx->callActivity(notifyEscalation, args = {"taskName": e.detail().taskName});
    return e;
};

Starts a child workflow and returns its instance ID without waiting for the result. The child is a true Temporal child workflow: its lifecycle is tied to this workflow, so when this workflow closes, in-flight children are cancelled with it.

Use getChildWorkflowResult (non-blocking) or waitForChildWorkflow (durable wait) to read the child's result later — this enables fan-out/fan-in orchestration:

string kycId = check ctx->runChildWorkflow(kycWorkflow, input = customer);   // fan out
string scoreId = check ctx->runChildWorkflow(scoreWorkflow, input = customer);
Kyc kyc = check ctx->waitForChildWorkflow(kycId);                            // gather
Score score = check ctx->waitForChildWorkflow(scoreId);

Returns the result of a child workflow started with runChildWorkflow if it has already completed, without waiting. While the child is still running (e.g. suspended on a human task) a workflow:WorkflowBusyError is returned — check back later, or switch to the blocking waitForChildWorkflow form.

Kyc|error result = ctx->getChildWorkflowResult(kycId);
if result is workflow:WorkflowBusyError { /* still running — do other work */ }

Waits durably until a child workflow started with runChildWorkflow completes and returns its result. The wait is a durable suspend — no thread is held, and the wait survives worker crashes and restarts (on replay the result is served from history).

Starts a child workflow and durably waits for its result — runChildWorkflow followed by waitForChildWorkflow fused into one call. "Blocking" here is a durable suspend, not a held thread, so this is safe for long-running children.

Receipt receipt = check ctx->callWorkflow(billingWorkflow, input = order);

Sends data to a running workflow instance's events record from inside a workflow. This is the in-workflow counterpart of workflow:sendData and is typically used to signal a child workflow started with runChildWorkflow, but accepts any workflow instance ID.

check ctx->sendDataToChildWorkflow(childId, "approval", {approved: true});

Durable sleep that survives process crashes and restarts. Do not use runtime:sleep() in workflows.

check ctx.sleep({seconds: 30});

Returns the deterministic workflow time. Use instead of time:utcNow() inside workflows.

time:Utc now = ctx.currentTime();

Checks whether the workflow is recovering from a failure (re-executing recorded history).

Get the unique workflow ID.

Get the workflow type name.