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 a ReviewTaskDefinition 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});

The result type T is inferred from what the result is assigned to, so the call must always be bound — including when the activity returns nothing but error?. Bind such a call to () _; a bare statement or a plain _ gives the compiler nothing to infer from:

() _ = check ctx->callActivity(reserveStock, 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. The task name is registered when the worker starts, from the workflow descriptor the compiler plugin generates at build time.

do {
    ApprovalDecision d = check ctx->awaitHumanTask("approveExpense",
        {"amount": 1200, "currency": "USD"},
        userRoles = "FINANCE_APPROVER",
        title = "Approve order",
        timeout = {hours: 24}
    );
    return d;
} on fail workflow:HumanTaskError e {
    if e is workflow:HumanTaskTimeoutError {
        () _ = 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.