For AI agents: the complete documentation index is at llms.txt. Remove the trailing slash from a page URL and append .md to read its Markdown version. For the docs home, use index.md.

Tutorial: Build an Onboarding Workflow

In this tutorial, you build a Reflex app that signs users up and runs an onboarding sequence for each one: a welcome email straight away, then up to two reminders, until the user activates their account. Along the way, you stop the server in the middle of a run and watch it pick up where it left off.

The tutorial takes about 15 minutes. You need Python 3.11 or later and a PostgreSQL database you can create tables in. To keep things quick, the reminders are 30 seconds apart and the "emails" are printed to the terminal.

Create the app

Create a project directory, add Reflex with its database extra, reflex-workflow, and the psycopg 3 driver, and scaffold the app. If you haven't installed uv yet, see the installation guide.

mkdir onboarding
cd onboarding
uv init
uv add "reflex[db]" reflex-workflow "psycopg[binary]"
uv run reflex init
When prompted to select a template, choose option 0 for a blank project.

Connect the app to Postgres

Open rxconfig.py and point both database URLs at your Postgres database. The postgresql+psycopg:// prefix selects psycopg 3, which serves both the synchronous connection Reflex uses for migrations and the asynchronous one the workflows use:

import reflex as rx

DATABASE_URL = "postgresql+psycopg://postgres@localhost:5432/onboarding"

config = rx.Config(
    app_name="onboarding",
    db_url=DATABASE_URL,
    async_db_url=DATABASE_URL,
)

Replace the user, host, and database name with your own.

Define the workflow

Create onboarding/workflows.py with the following code:

from datetime import timedelta

from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

from reflex_workflow import Workflow, step, wake_in


class Base(DeclarativeBase):
    pass


class Onboarding(Base, Workflow):
    __tablename__ = "onboarding"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(255), unique=True)
    status: Mapped[str] = mapped_column(String(32), default="new")
    reminders: Mapped[int] = mapped_column(default=0)

    @step(retries=3)
    async def welcome(self):
        print(f"Sending welcome email to {self.email}")
        self.status = "welcomed"
        return wake_in(Onboarding.remind, timedelta(seconds=30))

    @step
    async def remind(self):
        if self.reminders == 2:
            self.status = "gave up"
            return None
        self.reminders += 1
        print(f"Sending reminder {self.reminders} to {self.email}")
        return wake_in(Onboarding.remind, timedelta(seconds=30))

    @step
    async def activate(self):
        print(f"{self.email} activated")
        self.status = "activated"
Expand

This is an ordinary SQLAlchemy model with the Workflow mixin added. Each row in the onboarding table is one user's onboarding run:

  • email, status, and reminders are your columns. They hold the run's state, and the steps read and change them through self.
  • welcome, remind, and activate are steps. Each one returns what happens next: wake_in(...) runs a step after a delay, and None ends the run.
  • Reflex's migration commands find Base and create the tables on it. If your app registers its model bases with rx.ModelRegistry.register, register this one too; see Choose a base for workflow tables.

Start the workers

Workers are what run the steps. Replace the contents of onboarding/onboarding.py with the following code, which starts them with the app as a lifespan task:

import contextlib

import reflex as rx
from reflex.model import get_async_engine
from sqlalchemy.ext.asyncio import async_sessionmaker

from reflex_workflow import run_workflows

from .workflows import Onboarding


@contextlib.asynccontextmanager
async def workflows():
    sessions = async_sessionmaker(get_async_engine(None), expire_on_commit=False)
    async with run_workflows(sessions):
        yield


app = rx.App()
app.register_lifespan_task(workflows)

get_async_engine(None) reuses the engine Reflex builds from async_db_url, so the app keeps a single connection pool.

Create the table

Set up migrations for the app. Reflex finds the Onboarding model through the import in onboarding/onboarding.py, so this also generates and applies a migration that creates its table:

uv run reflex db init

When you change the model later, generate and apply a new migration with uv run reflex db makemigrations and uv run reflex db migrate.

The new table has your four columns plus the ones the Workflow mixin adds, such as next_step and wake_at, which record what each run does next and when.

Start a run from the page

Add a state and a page to onboarding/onboarding.py, above the app = rx.App() line. Signing up starts a run, the Activate button sends a run straight to its activate step, and Refresh reads the rows back:

class SignupState(rx.State):
    email: str = ""
    runs: list[dict[str, str]] = []

    @rx.event
    def set_email(self, value: str):
        self.email = value

    @rx.event
    async def sign_up(self):
        await Onboarding(email=self.email).start(Onboarding.welcome)
        self.email = ""
        await self.load_runs()

    @rx.event
    async def activate(self, email: str):
        await Onboarding.by(Onboarding.email == email).run(Onboarding.activate)
        await self.load_runs()

    @rx.event
    async def load_runs(self):
        rows = await Onboarding.by().all()
        self.runs = [
            {
                "email": row.email,
                "status": row.status,
                "next_step": row.next_step or "-",
                "wake_at": f"{row.wake_at:%H:%M:%S}" if row.wake_at else "-",
            }
            for row in sorted(rows, key=lambda row: row.id)
        ]


def run_row(run: dict[str, str]) -> rx.Component:
    return rx.table.row(
        rx.table.cell(run["email"]),
        rx.table.cell(run["status"]),
        rx.table.cell(run["next_step"]),
        rx.table.cell(run["wake_at"]),
        rx.table.cell(
            rx.button("Activate", on_click=SignupState.activate(run["email"]))
        ),
    )


def index() -> rx.Component:
    return rx.vstack(
        rx.hstack(
            rx.input(
                placeholder="Email",
                value=SignupState.email,
                on_change=SignupState.set_email,
            ),
            rx.button("Sign up", on_click=SignupState.sign_up),
            rx.button("Refresh", on_click=SignupState.load_runs, variant="soft"),
        ),
        rx.table.root(
            rx.table.header(
                rx.table.row(
                    rx.table.column_header_cell("Email"),
                    rx.table.column_header_cell("Status"),
                    rx.table.column_header_cell("Next step"),
                    rx.table.column_header_cell("Due at"),
                    rx.table.column_header_cell(""),
                ),
            ),
            rx.table.body(rx.foreach(SignupState.runs, run_row)),
        ),
        padding="2em",
    )
Expand

Then register the page after app = rx.App():

app.add_page(index, on_load=SignupState.load_runs)

start inserts the row and schedules its first step. Onboarding.by(...) addresses existing runs by a SQL condition; with no condition, it addresses all of them.

Watch a run

Start the app:

uv run reflex run

Open the app, enter an email address, and click Sign up. The table shows the run with the status new and welcome as its next step. Click Refresh: a worker has already run welcome, so the status is welcomed, the next step is remind, and it is due 30 seconds from now. The terminal shows the welcome email.

Wait 30 seconds and click Refresh again. The terminal shows the first reminder, and the second one is scheduled.

Restart in the middle of a run

Now see what makes the workflow durable. Stop the server with Ctrl+C while a reminder is scheduled, wait until its due time has passed, and start the server again with uv run reflex run.

The overdue reminder is sent as soon as the app starts. Nothing was lost while the server was down: the next step and its due time were columns in the row, and the first thing a worker does is look for runs that are due.

Interrupt a run

Click Activate, then Refresh. The status is activated and there is no next step: run replaced the scheduled reminder with the activate step, which ran straight away and ended the run.

Sign up the same email address a second time. Nothing changes, because the email column is unique and start never inserts a second row for the same key.

What you built

You built a workflow that:

  • Keeps each run's state in an ordinary table that your app can query.
  • Schedules work for later without keeping anything running in the meantime.
  • Survives a restart and catches up on what came due while it was down.
  • Can be redirected from an event handler.

Next steps

  • Learn every value a step can return in Steps.
  • Replace the Activate button with an approval that has a deadline in Waiting for events.
  • Before you deploy, read How workflows work: a step can run more than once, and real emails need an idempotency key.