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 initConnect 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"ExpandCollapse
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, andremindersare your columns. They hold the run's state, and the steps read and change them throughself.welcome,remind, andactivateare steps. Each one returns what happens next:wake_in(...)runs a step after a delay, andNoneends the run.- Reflex's migration commands find
Baseand create the tables on it. If your app registers its model bases withrx.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 initWhen 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",
)ExpandCollapse
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 runOpen 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.