Alterations

An alteration represents a change that can be applied to a given workflow instance.

Using alterations, you can change the state of a running workflow instance without republishing the workflow definition. In release/3.8.0, Elsa exposes alterations through server APIs and Elsa Studio.

For the task-oriented path through immediate execution, filtered plans, Studio, durability, and retry operations, start with Alter a Running Workflow Instance.

What Elsa ships in release/3.8.0

Enabling UseAlterations() adds:

• the built-in Elsa.Alterations.ExecuteAlterationPlan system workflow used to execute submitted plans

• REST endpoints under /alterations

• in-memory alteration plan and job stores by default

• an in-memory background dispatcher for alteration jobs by default

The write endpoints shown on this page require the run:alterations permission. Reading stored plan and job status uses read:alterations.

When to use alterations

Use alterations when you need to correct or steer existing workflow instances. Typical examples include:

• updating a variable on a live instance

• scheduling an activity so a stalled workflow can continue

• canceling a workflow or a specific running activity

• migrating a running instance to a specific version of the same definition

Alteration Types

Elsa Workflows supports the following alteration types:

• Cancel: Cancels the entire workflow instance.

• CancelActivity: Cancels a specific running activity instance, or all running instances of an activity ID.

• ScheduleActivity: Schedules an activity for execution by activity ID or activity instance ID.

• ModifyVariable: Modifies a workflow variable by variable ID.

• Migrate: Migrates a workflow instance to a specific version of the same workflow definition.

Two execution modes

Elsa supports two ways to execute alterations:

1. Submit an alteration plan when you want Elsa to select target instances from a filter and process them asynchronously in the background.

2. Apply alterations immediately when you already know the workflow instance IDs and want the results in the current request.

Use these pages for each mode:

• Alteration Plans

• Applying Alterations

Which mode fits which job

Situation	Use
You already know the exact workflow instance IDs and need the response now	POST /alterations/run or IAlterationRunner
You need Elsa to find matching workflow instances from filters and process them in the background	alteration plans
You need to retry faulted activities for known workflow instances	GET or POST /alterations/workflows/retry
You want designers or operators to stage alterations for one running instance visually and inspect resulting plans later	Elsa Studio alterations module

Elsa Studio

Elsa Studio in release/3.8.0 includes an alterations module. When the backend Alterations feature is enabled, Studio shows an Alterable instances page and adds Alter actions for running workflow instances.

Studio exposes:

• an Alterations top-level menu with Instances and Plans views

• an Alterable instances page that lists non-system running workflow instances

• an alteration designer for staging the five built-in alteration types against an instance

• plan details pages that show plan status, generated jobs, and per-job logs

• quick Alter actions from workflow-instance screens

Studio creates plan submissions from a selected workflow instance. For cross-instance bulk operations, use alteration plans and their filter-based API, then use Studio's Plans view to inspect the resulting jobs and logs.

Persistence and dispatch options

By default, Alterations uses in-memory stores and an in-memory background dispatcher. That is fine for local development, but plans and jobs are not durable across process restarts.

For durable or multi-node deployments, configure persistence for alteration plans and jobs:

services.AddElsa(elsa => elsa.UseAlterations(alterations =>
{
    alterations.UseEntityFrameworkCore(ef => ef.UseSqlServer(connectionString));
}));

MongoDB persistence is available from elsa-extensions:

services.AddElsa(elsa => elsa.UseAlterations(alterations =>
{
    alterations.UseMongoDb();
}));

elsa-extensions also provides a MassTransit-backed dispatcher for background alteration jobs:

services.AddElsa(elsa => elsa.UseAlterations(alterations =>
{
    alterations.UseMassTransitDispatcher();
}));

Use the MassTransit dispatcher when alteration jobs should survive node boundaries or be processed by worker nodes connected through MassTransit. The dispatcher replaces the default in-memory background queue for alteration jobs only; it does not change how the immediate /alterations/run endpoint executes.

Operational notes

• Submitted plans create one alteration job per matched workflow instance.

• If a submitted plan matches no instances, Elsa still stores the plan but generates no jobs.

• /alterations/run dispatches successful workflow instances that still have scheduled work after the alterations finish.

• IAlterationRunner by itself does not dispatch scheduled work; pair it with IAlteredWorkflowDispatcher when you call the service directly.

• The retry endpoint schedules faulted activities by creating ScheduleActivity alterations and then dispatching the targeted workflow instances.