Changing a workflow
Each workflow is versioned and every run stays on the version it started on. Registering a new version only applies to new runs and never to runs in progress. This page explains how to release a new workflow version safely.
1. Give the change a new version
Change the definition and bump up its version:
export const orderFulfilment = defineWorkflow<Order>()({
name: "order-fulfilment",
version: 4, // was 3
steps: [/* ... */],
});
Any change to the workflow definition needs a new version, for example:
- adding, removing or renaming a step;
- changing the order of the steps, or where a step goes next (next, onFailure, a choice’s condition);
- changing a retry policy, a timeout, or the workflow’s overall runTimeout.
Only descriptions can be changed without a new version.
- Forgot to bump up the version? Registering version 3 again with different steps is refused with
409, because runs already on version 3 would silently change behaviour. Nothing is changed. - Only reworded a description? That is not considered a change as descriptions are ignored for comparison. So, pushing it again under the same version is fine.
- Pushed the same definition twice? Nothing happens. Pushing an unchanged definition is safe, which is why you can push on every deploy.
2. Deploy handlers that serve both versions
While old runs are in flight, your service will receive tasks from both the old and new versions. Foliot calls the same handler for a step whatever the version (unless the new workflow version routes a step to a different handler) and each task says which version it is using (ctx.workflowVersion with the SDK, workflowVersion in the payload).
- Changing what a step does is safe: both versions call the same handler. If old and new runs need different behaviour, branch on
ctx.workflowVersion. - Adding a step is safe: only runs on the new version reach it.
- Changing a step’s output needs care: later steps of old runs read the output using its old shape, so a handler that reads
ctx.output("…")must accept both shapes until old runs are done. - Removing or renaming a task step needs care: a run on the old version that has not reached that step yet will still ask for it. With the SDK, a step that is no longer in the definition has no handler, and the task fails with
no_handlerwithout retrying. Wait until no run on the old version can still reach it (see step 5), or move those runs onto the new version first (step 4).
Deploy the service before new runs start on the new version, so no task arrives for a step it cannot handle yet.
3. Register it and choose when new runs use it
Push the new definition as usual:
foliot push dist/workflows.js
Which version a new run gets depends on how it is started:
| Started with | Gets |
|---|---|
A version (the SDK’s start sends the definition’s own) |
Exactly that version. For the above example, only the new runs will use version 4 after the definition is deployed. |
An alias such as production |
The version the alias points at when the run starts. Moving the alias later changes only the runs you start after the move. You can move it whenever you are ready without requiring a deployment. |
| Neither | The version default points at when the run starts. This is the the newest version unless you pointed default to another version. |
Rolling out with an alias
An alias lets you register a version first and switch to it later:
- Start runs with
alias: "production"instead of a version. - Push version 4.
productionstill points at version 3, so nothing changes yet. - To validate version 4, start a few runs with
version: 4and observe. - Point
productionat version 4 once the validation is completed. All new runs will target version 4 starting with the next one.
You can move an alias in Foliot Console (the workflow’s page, Aliases), using the SDK’s setAlias("order-fulfilment", "production", 4) function, or through an API call to PUT /apps/{appId}/workflows/{workflow}/aliases/{alias}.
Rolling back is the same move in reverse: point production at version 3 again. New runs go back to version 3 at once. Runs that already started on version 4 stay there and you can move them with a rewind if you need to (see below).
Moving an alias only changes which version the new runs get. It never moves a run that has already
started, even one whose first step is still waiting on startAfter. Say production points at
version 3 and you start run A, then point production at version 4 and start run B. A stays on
version 3 and B runs version 4.
4. Move runs in flight to the new version
Runs finish on the version they started on but there might be times when you might need to change this - to fix a faulty release for example. In this case, you will need to register a new workflow version and rewind these runs onto it.
A rewind restarts a run from the step name you pass to it and then run every step after it again. It uses the version you pass or the run’s own version if you don’t provide one. You can only rewind to a step that the run has started on before.
-
For a single run: Use Rewind to step… on the run’s page in Foliot Console, or send
POST /apps/{appId}/runs/{runId}/rewindwith the step to go back to and the version to run on:{ "toStep": "charge-card", "version": 4 } -
For many runs: Use the bulk rewind functionality after trying it on a dry run first. See Managing runs.
The step you want to rewind to must exist in the new version. A rewind cannot undo a side effect an earlier attempt had (eg. an email sent or a credit card charged) so rewind to a step that is safe to run again.
5. Retire the old version
You can stop supporting an old version after confirming nothing is still sending your service a task for that handler. You need to confirm the following:
- No active runs are left. Check for runs still running, sleeping, waiting or stuck on that version:
const { runs } = await foliot.listRuns({
workflow: "onboarding",
version: 3,
status: ["running", "sleeping", "waiting", "stuck"],
});
Without the SDK, send GET /apps/{appId}/runs with the same filters:
GET https://api.foliot.app/apps/<app id>/runs?workflow=onboarding&version=3&status=running&status=sleeping&status=waiting&status=stuck
Authorization: Bearer <the API key>
When the list is empty, no runs on version 3 will send your service a task on its own.
- You are not planning to redrive or rewind an old run. A finished run can be rewound for 90 days after it finishes (as long as Foliot keeps its full history) and a redrive or a rewind without a version will run on the run’s initial version. If you need to redrive or rewind a failed version 3 run, for example, you either have to keep version 3’s handlers or rewind that run onto the newest version.
Once both are true, you can delete the handler code that only version 3 used. The version itself stays registered, because it is part of the run history that used it. You can still read it on the workflow’s Definition tab in Foliot Console.
Checklist
- Change the definition and bump up the
version - Deploy handlers that can handle both versions
- Register the new version in Foliot
- Switch new runs to it by deploying the code that starts runs or by moving an alias
- Wait for old runs to finish or rewind the ones that need the version change
- Once all runs on the old version are completed, remove code only it used