Release 0.3.0

This page lists what IdentityFlow 0.3.0 delivers, where it runs, what changed since 0.2.0 and what it does not do. Read the known limits before you plan a production rollout, and the upgrade notes before you move a 0.2.0 installation.

IdentityFlow 0.3.0 is released for production use. The 0.x version number means interfaces can still change between minor releases; such changes are listed as breaking below.

What is delivered

Delivery	What it is
identity-flow-v0.3.0-<target>	The IdentityFlow program: one executable that serves the web application and the GraphQL API and runs workflows. It needs no Node.js.
identity-flow-test-v0.3.0-<target>/	The Workflow Test distribution: the test runner for your Workflow Tests, a folder whose files stay together.
identity-flow-workshop-starter-v0.3.0.zip	The starter: an example project with workflows, a hooks file, tests, practice tasks and a local sign-in setup.
@identity-flow/api, sdk, binding-graphql, testing	The npm packages your workflow project uses, all at version 0.3.0.

<target> is macos-arm64 or linux-x64. The program, the Workflow Test distribution and the starter are provided to customers directly. If you don’t have them yet, write to contact@kenoxa.de. Install and run IdentityFlow describes each file.

Supported platforms

• macOS on Apple Silicon.
• Linux x64. The program is statically linked. The Workflow Test distribution brings its own Node.js and needs glibc, so Alpine and other musl-based systems cannot run it.
• Windows through WSL2, with the Linux x64 files.
• PostgreSQL 17 or 18. Workflow Tests start a PostgreSQL 18.6 container by default.
• Node.js is needed to install your project’s packages, not to run the program. The starter requires Node.js 26.8.1 exactly.
• No container image. 0.3.0 is delivered as the files above.

What 0.3.0 contains

Access control

• Access follows the signed-in account. Every view and command decides from the signed-in account and the principals its provider reports, in the web application and in GraphQL alike. When IdentityFlow cannot confirm the account’s principals, it denies. See Access control.
• Reviewed access is activated at startup. The configuration names the authorization.ts it reviewed, and the program activates it when it starts. With the reviewed digest declared, an unreviewed change stops the start. See Activate the configuration at startup.
• My access shows what an account reaches. Every signed-in account can see its principals and the workflow families it reaches per access function. See Check what an account can reach.
• Lists stay bounded with large access data. Instance, step and dialog lists are filtered by current access before they are paged, and IdentityFlow reports an account with more principals than IdentityFlow’s principal limit instead of cutting its access short.
• Refusals stay inside the application. Navigation shows only the sections the account can use. A page the account may not open explains the refusal and reads the same as a page that does not exist.

Writing workflows

• Parallel steps survive restarts. Workflow code can wait for all, any or the first of several steps. Completed and canceled branches are kept, so a restart neither repeats abandoned work nor loses a waiting step. See Promise composition.
• Start forms come from declared parameters. The start page builds its form from the parameter schema of the Workflow Definition, offers declared choices as lists, keeps declared defaults, and sends no undeclared values. Invalid parameters are refused when the workflow starts, instead of creating an instance that fails. See Build a start form from the input schema.
• Dialogs declare the answer they accept. The answer form is built from the dialog’s schema. An answer the form cannot describe can still be given as JSON.
• Custom value formats. A Workflow Definition can register its own serializers for persisted data. See Workflow API.
• Request steps can poll. flow.request accepts a polling interval and backoff, and keeps cancellation and its until deadline.
• Workflow discovery skips hidden directories, such as dependency and build caches next to your workflows.
• Recipes on this site: complete, tested examples for everyday tasks. See Recipes.

Operating workflows

• Operators can reassign a pending dialog to other principals, with a recorded reason. See Reassign a pending dialog.
• Operators can replay failed work, with the same access checks, locking and reason as other commands. See Replay failed work.
• Temporary database failures no longer error a workflow. Work that failed on a retryable PostgreSQL connection or transaction error stays scheduled and runs again.
• An older program refuses a newer database. It stops with WF_DATABASE_MIGRATION_MISMATCH instead of running migrations again; see Database migrations.
• Locks are released promptly, also after a timer resumes a workflow, so due retries run on a quiet system. Dialogs assigned to the same principal can start at the same time without a failed step.

Workflow Tests

• Workflow Tests run against real PostgreSQL, each in its own schema. A test starts workflows as declared accounts, answers dialogs, replaces bindings with typed fixtures, waits for later states and reads the events. See Test workflows.
• Tests drive child workflows, including a child that the parent started again after a retry.
• Waits behave like production. Paused dialogs and parallel steps suspend and cancel the same way as in a deployed workflow.
• Failures name their cause. An unsupported call names the API and the step, a runner that cannot start reports why, and a run ends with its summary instead of repeated error output. Answering a dialog also works in long test runs.

Sign-in and the web application

• Sign-in works from any page and returns there afterwards, also with two sign-ins in different tabs. A failed sign-in names its reason; see Troubleshooting.
• Plain HTTP only on literal loopback. Issuer and redirect URI may use plain HTTP only for 127.0.0.1 or [::1] in development or workshop mode, never for localhost. NODE_ENV=workshop is a mode for local training and development deployments.
• Session cookies follow the served address. They are marked Secure whenever auth.oidc.redirectUri uses HTTPS. A browser keeps at most five sign-ins in progress.
• Workflow data is shown as labelled values, not raw JSON. Values that look like dates but are not stay as written.
• Smaller fixes. A started workflow opens its instance, sign-out works from the menu, the sidebar starts expanded, narrow screens show the list of assigned dialogs and the open dialog separately, and search in Assigned to me no longer blocks the browser.

Starter

• Linux x64 and WSL2 are supported next to macOS on Apple Silicon.
• One setup command per platform checks the prerequisites, repairs the downloads in bin/ and installs the packages with npm from the lockfile.
• npm scripts start, stop, reset and inspect the local installation. See Command line.
• Practice tasks in exercises/, each with a starting state and a solution, and the tutorial that walks through the starter.

Breaking changes

• A changed bundle stops the start. When a file changes while its Workflow Definition keeps its name and version, the program stops with WF_DEFINITION_BUNDLE_CHANGED. 0.2.0 kept the stored bundle instead. Migration: raise the version before you start; see Versions and changed bundles.
• GraphQL has fixed views. The generic account, principal, workflow, instance, step and event queries and the broad mutations are gone. Migration: read through startCatalog, initiationHistory, assignedDialogs, participationHistory, business, operations, audit or deadLetters, and write with startWorkflow, completeDialog, pauseInstance, resumeInstance, terminateInstance, reassignDialog or replayDeadLetter. Authority comes from the session, not from client input. See the GraphQL API reference.

Upgrade from 0.2.0

The upgrade migrates the database in one direction: after the 0.3.0 program has started once, a 0.2.0 program fails against that database with 42723: function "uuid_generate_v7" already exists with same argument types. Back up the database first. The steps are in Upgrade from 0.2.0.

Known limits in 0.3.0

• No REST API. Clients use the GraphQL API. See Build your own UI.
• GraphQL needs a browser session. Requests are authenticated only by the session cookie of a browser sign-in; there are no tokens or API keys for clients without one. See Where your UI must run.
• Lists return the first 100 items. total, facets and pageInfo fail the query, so there is no cursor paging. See List arguments in 0.3.0.
• Refused commands carry no error code. Commands the engine refuses arrive as Unexpected error. with INTERNAL_SERVER_ERROR; the reason is only in the server log. See Errors.
• GraphQL answers same-site requests from other origins. A page on another subdomain or port of the same site can read data and run commands as the signed-in account. Do not host content you do not control on the same site as IdentityFlow. See Where your UI must run.
• An invalid dialog answer errors the step. It is reported as COMPLETED; then the step and the instance become ERRORED. See Answer the dialog.
• flow.request cannot be tested with Workflow Tests. See Limits of Workflow Tests in 0.3.0.
• A zero duration fails. A duration of 0 errors the instance with a TypeError in 0.3.0. Write durations as strings, such as '2 seconds'. See Retry boundary.
• A step’s timeout is not enforced. An attempt runs until its callback returns or throws. See Retry boundary.
• No traces or metrics are exported. OTEL_* variables have no effect. See Observability.
• No health endpoint. See Check that the program is ready.
• No introspection and no schema file. The program rejects introspection queries, and 0.3.0 ships no schema file. Use the schema on the GraphQL API reference page.
• No way to retire an old version. Deployed Workflow Definition versions stay in the database, and instances of an older version keep running from the stored definition after you remove it from your source. See Versions and changed bundles.
• No delegation or impersonation. An operator can reassign a pending dialog instead. See Delegation and impersonation.

Delegation and impersonation

Delegation would let one person act on another’s behalf for a limited time, for example “Alex may approve on Sam’s behalf until Friday”. It would have to settle which authority passes, when it ends and what happens to work in progress, and how the audit record shows both people.

Impersonation would let one person act as another: see what Sam sees and take actions in Sam’s name, with the audit record showing who really acted.

0.3.0 has neither. Every command runs as the signed-in account and is checked against that account’s own principals. Two features can look similar but work differently:

• Coverage through an assignee source. In the tutorial, the directory reports that vacation approvals now go to the coverage role, which the deputy holds. IdentityFlow receives the change event and replaces the waiting dialog’s assignees, and the deputy answers as themselves, with their own principal. Nobody acts on anyone’s behalf, and nobody gains authority they did not have. See When assignees are recomputed.
• Reassignment by an operator. An operator replaces a pending dialog’s assignees and records a reason. That changes who is asked; the new assignee answers in their own name. See Reassign a pending dialog.