Upgrading

This page covers two kinds of change: a new release of the Workflow packages, and a new version of one of your workflows.

Upgrading the packages

Every Workflow package of a release has the same version, built from one commit. Install them together:

  1. Read the release notes of every version between yours and the new one.
  2. Update every StellaOps.Workflow* package, and the shared packages they depend on, to the new version in one change. A lock file (packages.lock.json) makes the restore repeatable.
  3. Build. Expected result: no errors. A new analyzer rule can report workflow code that an earlier release accepted; fix it as the message says.
  4. Run your definition and runtime tests (Testing).
  5. Stop every node of the installation, then start the new version. At the first start the store applies the schema changes of the new release. If you apply the schema script yourself (ApplyMigrationsOnStartup = false), apply the new script before the start.

CAUTION Do not run two releases of the engine on one store at the same time. The store’s schema follows the newest release, and nodes of the older release can fail on it. Stop all nodes, then upgrade.

Schema changes are forward only: a release never removes data that the previous release wrote. Restore the database backup to go back to an earlier release.

Changing a workflow

A workflow name keeps its instances and its count; a version describes one shape of its steps.

ChangeDo
A display name, a task payload field, a roleIncrease the version
A new step, a removed step, a changed decisionIncrease the version
A new task, a renamed taskIncrease the version; keep the old task until no open instance uses it (below)
A different processA new workflow name

Open instances. An instance keeps the version that started it, and resumes with that version’s definition. A host must therefore keep registering every version that still has open instances:

Add the new version as a new class and register both:

/// <summary>
/// Registers both versions. New starts take 2.0.0, the highest version; an instance started on
/// 1.0.0 resumes with the 1.0.0 definition. Remove the 1.0.0 registration once no instance of it
/// is open.
/// </summary>
public static IServiceCollection AddReturnRequestWorkflows(this IServiceCollection services)
{
    services.AddWorkflowRegistration<ReturnRequestWorkflowV1, ReturnRequest>();
    services.AddWorkflowRegistration<ReturnRequestWorkflowV2, ReturnRequest>();
    return services;
}

New starts take the highest version, compared as semantic versions (or the version a start request names). When GET /api/workflow/instances?workflowName=<name>&workflowVersion=<old>&status=Open returns no instance, remove the old registration.

Lesson 11 runs both versions side by side.

A stored definition never changes either: import a new version and activate it (Governed activation and publishing).

Renaming

A rename is a new workflow: instances of the old name are not moved, and both names count as Designated Workflows. Keep names stable; change display names instead.