Change a workflow safely

Runs can last days or months, so you’ll often deploy a new version of a workflow while some of its runs are still going. Nelkap has no versions to manage: a run in progress uses your new code on its next call. This page explains what that means for each kind of change, so you can change a workflow without surprises.

How a run meets new code

On each call, your workflow runs from the top, and each step looks for its saved result by kind and name, in the order your code reaches it. So what matters is the name of each step, not where it sits in your code:

A step that keeps its name gives back its saved result, even if you moved it.
A step with a new name runs as a new step, even where an old one used to be.
A saved step your code no longer reaches is ignored.

Runs pick up the new code at their next call: after a sleep or a wait, or when Nelkap calls again after a deploy cut a call off.

Changes that are always safe

Changing what happens after the point a run has reached. Its next call runs the new code from there.
Changing the code inside a step that’s already saved. The saved result comes back, and the new code runs only in runs that haven’t reached the step yet.
Adding steps after the point a run has reached.
Changing code outside steps, as long as it takes the same path for the steps already saved.

Changes to make with care

Adding a step before the point a run has reached

The step runs at the run’s next call, since it has no saved result. For example, an email added between two steps of a run that has already passed that point goes out when the run picks up. That’s often what you want. If it isn’t, branch on a version, as shown below.

Renaming a step

The renamed step has no saved result, so its work is done again under the new name. Keep the old name for steps that have already run in some runs.

Changing a sleep’s duration or a wait’s key

A sleep is named after its duration, and a wait after its key. A run already sleeping keeps its original wake-up time, and a run already waiting keeps its original key. Once it goes on, the new name doesn’t match the saved one, so the run pauses again with the new duration or key. To wake a run that’s already waiting, emit the event with its original key. Steps with the same name are matched in order. If you remove one of them, the ones after it shift, and each gets the saved result of the one before it.

Keep old runs on the old path

When a change must only apply to new runs, branch on a version saved in the run’s first step. Add the step when you first write the workflow, returning 1. When a change comes, return the next number and branch on it:

export async function onboardUser(userId: string) {
  const version = await nelkap.step.run(
    'version',
    () => 2,
  );

  await nelkap.step.run('profile', () =>
    createProfile(userId),
  );

  // Runs from version 2 on send the survey.
  if (version >= 2) {
    await nelkap.step.run('survey', () =>
      sendWelcomeSurvey(userId),
    );
  }

  await nelkap.step.sleep('1 day');

  await nelkap.step.run('welcome', () =>
    sendWelcomeEmail(userId),
  );
}

Runs started earlier saved 1, so they keep the old path. New runs save 2 and take the new one.

Rename or remove a workflow

A workflow’s name is how Nelkap tells your app which code to run. Renaming a workflow counts as removing the old name and adding a new one. Removing a workflow cancels its runs that haven’t started yet, and those sleeping or waiting. See Workflows and runs. To retire a workflow without cutting its runs short, first remove its events and its schedule, and stop starting it from your code. Keep it registered until its last runs have ended, then remove it.

Get started

Concepts

Frameworks

Triggers

Write workflows

Deploy

Monitor

Manage

Help

Change a workflow safely

How a run meets new code

Changes that are always safe

Changes to make with care

Adding a step before the point a run has reached

Renaming a step

Changing a sleep’s duration or a wait’s key

Keep old runs on the old path

Rename or remove a workflow

​How a run meets new code

​Changes that are always safe

​Changes to make with care

​Adding a step before the point a run has reached

​Renaming a step

​Changing a sleep’s duration or a wait’s key

​Removing steps that share a name

​Keep old runs on the old path

​Rename or remove a workflow

How a run meets new code

Changes that are always safe

Changes to make with care

Adding a step before the point a run has reached

Renaming a step

Changing a sleep’s duration or a wait’s key

Removing steps that share a name

Keep old runs on the old path

Rename or remove a workflow