ballerina/workflow Ballerina library

Executes an activity function within the workflow context.

Activities are non-deterministic operations (I/O, database calls, external APIs) that are executed exactly once during workflow execution. Even if the workflow replays, a completed activity is not re-executed.

The return type is inferred from the calling context, so the result is automatically converted to the expected type without manual casting.

By default (retryOnError = false), any error returned by the activity is passed back to the workflow as a normal return value so that workflow logic can handle it explicitly. Set retryOnError = true to enable the runtime retry policy; when all retries are exhausted the error propagates and the workflow fails unless it is caught.

Example:

// Default: error returned as value — workflow handles it
string|error result = ctx->callActivity(chargeCardActivity, {amount: total});
if result is error {
    return handlePaymentFailure(result);
}

// Opt in to automatic retries (3 retries, 2-second initial delay)
// On exhaustion the error propagates; use `check` to let the workflow fail
string result = check ctx->callActivity(sendEmailActivity, {email: addr},
    retryOnError = true, maxRetries = 3, retryDelay = 2.0);

Waits for at least minCount data futures to complete.

A replay-aware alternative to Ballerina's built-in wait { ... } syntax for workflow event futures. Uses cooperative scheduling internally — it yields the workflow thread without blocking the worker thread pool, and is a no-op during event history replay.

When minCount is omitted the function waits for all futures (equivalent to minCount = futures.length()).

The return type is inferred from the calling context (T), so you can assign results directly to a typed variable without explicit casting:

// Tuple — each element is typed to the matching future's inner type
[ApprovalDecision, ComplianceDecision] results =
    check ctx->await([events.ops, events.compliance]);
ApprovalDecision ops = results[0];   // no cloneWithType needed

When timeout is provided and the required number of futures have not completed within that duration, an error is returned. Omit timeout (or pass ()) to wait indefinitely.

Common patterns:

• Wait for all: ctx->await([f1, f2, f3]) — waits for all 3 (default)
• Wait for any: ctx->await([f1, f2], 1) — returns when 1 completes
• Quorum: ctx->await([f1, f2, f3], 2) — waits for 2 of 3
• With timeout: ctx->await([f1, f2], timeout = {hours: 48}) — returns error on timeout

Performs a durable sleep within the workflow.

This sleep is persisted by the workflow engine and will survive program restarts and workflow replays. The countdown continues even when the program is down, and the workflow resumes correctly after the duration has elapsed upon replay.

Do not use runtime:sleep() inside workflows as it is not deterministic across replays.

Example:

@workflow:Workflow
function reminderProcess(workflow:Context ctx, string userId) returns error? {
    // Wait 24 hours (durable - survives restarts)
    check ctx.sleep({hours: 24});
}

Returns the current workflow time as a time:Utc value.

The workflow engine does not use the real wall-clock time for workflow executions. Instead it records the timestamp at each workflow task and surfaces that as "now" during both the original execution and every subsequent replay. This guarantees that calls to this method from the same point in the workflow always return the same value, making the workflow deterministic regardless of when the program processes it.

Example:

@workflow:Workflow
function orderProcess(workflow:Context ctx, Order input) returns OrderResult|error {
    time:Utc startTime = ctx.currentTime();
    // ...
}

Check if the workflow is currently replaying history.

Useful for skipping side effects that should only happen on first execution. For example, logging or metrics that shouldn't be duplicated during replay.

Get the unique workflow ID.

Get the workflow type name.