Recipes

Each recipe is one complete workflow or hooks file and its test. Copy both into your project, run the test, then adapt the file to your system. The host deploys the default export of each workflow file, one Workflow Definition per file.

Before you start

Set up your project once as described in Test workflows: the @identity-flow/* packages, workflow-test.setup.ts, and a vitest.config.ts whose include covers both **/*.case.ts and **/*.test.ts. You also need the Workflow Test distribution of your release, and Docker must be running.

Save each recipe’s two files next to each other in that project, under the names the recipe gives. Each test imports its file by that name. Then run the tests from your project directory:

# Run from your project directory. Use the folder where you unpacked the
# Workflow Test distribution of your release and platform.
/opt/identity-flow/identity-flow-test-v0.3.0-linux-x64/identity-flow-test --run

This runs every test file the configuration includes. Two kinds of test appear on these pages:

• Workflow Tests, in files ending in .case.ts, start a real instance against PostgreSQL. They run only with the Workflow Test distribution.
• Hook tests, in files ending in .test.ts, load a hooks file into an in-memory host with no engine and no database. Only Map a login to principals has one.

Type-check with npx tsc --noEmit as well. Vitest does not check types, so a @ts-expect-error line or a changed interface fails only in the type check.

The recipes

• Build a start form from the input schema: describe the parameters a workflow accepts so the start form offers labels and choices.
• Assign a dialog to a role: wait for an answer from whoever currently holds a role.
• Retry a step and stop on a final error: retry a failure that can go away, and stop at once on one that cannot.
• Withdraw a dialog after a deadline: end an unanswered dialog after a set time.
• Call a GraphQL service through a binding: read from an external GraphQL service, and replace it with a fixture in the test.
• Map a login to principals: report the person, the teams and the managed people for one login.
• Deploy a new version of a workflow: change a workflow in place so that running instances can continue on the new version.

How to read a recipe

Several recipes depend on replay: when an instance continues, IdentityFlow runs the workflow function again from the top and returns each finished step’s recorded result instead of running the step again.

The company in the examples is invented. acme is the provider ID, employee IDs look like e-2041, and principal subjects look like role:vacation-approver. Replace them with your own.

Every code block on these pages is a file in the IdentityFlow repository. IdentityFlow’s continuous integration compiles each file, runs the Workflow Tests against PostgreSQL 17 and 18 and the hook test under plain Vitest, so the retry counts, canceled steps and refused answers shown here are what IdentityFlow does.