ballerina/workflow Ballerina library

Overview

Workflows and activities are ordinary Ballerina functions:

• @workflow:Workflow — A durable function that orchestrates a business process. The runtime checkpoints every step and replays recorded history to recover from failures.
• @workflow:Activity — A function that performs a single non-deterministic operation (API call, database query, email send). Once an activity completes, its result is recorded and never re-executed during replay.

import ballerina/workflow;

type OrderRequest record {|
    string orderId;
    string item;
|};

type OrderResult record {|
    string orderId;
    string status;
|};

@workflow:Activity
function checkInventory(string item) returns boolean|error {
    // Call external inventory API
    return true;
}

@workflow:Workflow
function processOrder(workflow:Context ctx, OrderRequest request) returns OrderResult|error {
    boolean inStock = check ctx->callActivity(checkInventory, {"item": request.item});
    if !inStock {
        return {orderId: request.orderId, status: "OUT_OF_STOCK"};
    }
    return {orderId: request.orderId, status: "COMPLETED"};
}

Key Features

• @workflow:Workflow and @workflow:Activity annotations for durable orchestration and non-deterministic operations
• Automatic checkpointing and replay-based recovery from failures
• External data delivery to running workflow instances

Authoring guidelines

• Workflow functions must contain only orchestration logic (control flow and waiting for data). All business logic and non-deterministic operations - database calls, external API calls, I/O - belong in activity functions.
• Activities must be invoked through ctx->callActivity(...) from within a workflow function. Calling an activity function directly is a compile-time error.
• When calling an activity, pass its arguments as a record whose keys exactly match the activity function's parameter names - for example, ctx->callActivity(checkInventory, {"item": request.item}) for function checkInventory(string item).
• When using the Ballerina Integrator tooling, place all @workflow:Workflow and @workflow:Activity functions in the project's functions.bal file.
• Store the workflow ID returned by workflow:run() so that later workflow:sendData() calls can be routed to the correct running instance.

Starting a Workflow

Use workflow:run() to start a workflow instance from any entry point — HTTP service, scheduled job, message consumer, or main:

string workflowId = check workflow:run(processOrder, {orderId: "ORD-001", item: "laptop"});

Receiving External Data

A workflow can pause and wait for external input — approvals, payment confirmations, user decisions — using future-based event records. Send data to a running workflow with workflow:sendData():

// In the workflow — wait for a human decision
ApprovalDecision decision = check wait events.approval;

// From outside — deliver the decision
check workflow:sendData(processOrder, workflowId, "approval", {approverId: "mgr-1", approved: true});

Multi-Future Waits with ctx->await

Use ctx->await to wait for multiple futures at once, with optional quorum and timeout:

Error Handling

Activity errors are returned as plain Ballerina values. The workflow decides what happens next:

string|error result = ctx->callActivity(chargeCard, {"amount": input.amount});
if result is error {
    // retry with a different card, fall back, or compensate
}

Enable automatic retries for transient failures:

string result = check ctx->callActivity(chargeCard, {"amount": input.amount},
    retryPolicy = {maxRetries: 3});

Configuration

Add a Config.toml to your project. For local development with no server:

[ballerina.workflow]
mode = "IN_MEMORY"

For production, connect to a Temporal server:

[ballerina.workflow]
mode = "SELF_HOSTED"
url = "temporal.mycompany.com:7233"
namespace = "default"
taskQueue = "my-task-queue"

See Configure the Module for every mode and field.

Documentation

Examples