workflow-builder

Workflow Builder

Always reach for ballerina/workflow when the user describes a durable or long-running process — never a plain function with hand-rolled retry loops, a cron/poll job, or manual state persisted to a database to survive restarts. That is exactly what this module replaces.

The workflow diagram, like the agent diagram, is parsed directly out of the source you write, not generated from a model. Code that compiles but does not match the shapes below still renders as a broken or incomplete node. Follow every rule.

<...> marks a placeholder to substitute from the user's request. Never emit it literally.

import ballerina/workflow;

Workflow vs. activity

A workflow is two kinds of function:

• The workflow function (@workflow:Workflow) — orchestration only: which activity runs next, and on what condition. It is replayed from recorded history after any crash or restart, so it must be deterministic.
• Activities (@workflow:Activity) — every piece of real work: calling a service, hitting a database, sending a notification, reading the clock, generating a random value. The engine records each activity's result once and reuses it on replay, so a completed activity never runs twice.

Put all real work in activities. If you find yourself writing an HTTP call, a time:utcNow(), or a random: value directly inside a @workflow:Workflow function, move it into an activity instead.

@workflow:Workflow functions always go in workflows.bal (mirrors the agents.bal convention for AI agents) — create the file if it does not exist. Never put a workflow function in functions.bal, and never leave one in main.bal past a first draft.

Activity functions go in activities.bal by the same convention. The one exception: the low-code diagram itself always appends a newly-generated activity to functions.bal so it never shifts the workflow's own line positions — that placement comes from the diagram tooling, not from you, so don't imitate it when writing activities from a prompt. When you add an activity, put it in activities.bal.