Alteration Plans API

The Alterations module exposes a REST API for managing alteration plans. For example, to submit a plan that modifies a variable, migrates the workflow instance to a new version and to schedule an activity, use the following request:

POST /alterations/submit HTTP/1.1
Host: localhost:5001

{
    "alterations": [
        {
            "type": "ModifyVariable",
            "variableId": "83fde420b5794bc39a0a7db725405511",
            "value": "Hello world!"
        },
        {
            "type": "Migrate",
            "targetVersion": 9
        },
        {
            "type": "ScheduleActivity",
            "activityId": "mY1rb4GRjkW3urm8dcNSog"
        }
    ],
    "workflowInstanceIds": [
        "88ce68d00e824c78a53af04f16d276ea"
    ]
}

The response wil include the Plan ID:

{
  "planId": "6cdc459867a94027a6f237417acf398f"
}

You can use the Plan ID to query the status of the plan:

GET /elsa/api/alterations/6cdc459867a94027a6f237417acf398f HTTP/1.1
Host: localhost:5001

The response will include the plan's status:

{
  "plan": {
    "alterations": [
      {
        "type": "ModifyVariable",
        "variableId": "9b4cecbe82204102813ee968d517bc8a",
        "value": "Hello world!"
      },
      {
        "type": "ScheduleActivity",
        "activityId": "BK2-RkUrgkmMj3RIkKfh9g"
      }
    ],
    "workflowInstanceIds": [
      "5d87afa152e54f88ac22e5d69ead6b69"
    ],
    "status": 2,
    "createdAt": "2023-10-04T22:34:31.28188+00:00",
    "completedAt": "2023-10-04T22:34:31.44371+00:00",
    "id": "6cdc459867a94027a6f237417acf398f"
  },
  "jobs": [
    {
      "planId": "6cdc459867a94027a6f237417acf398f",
      "workflowInstanceId": "5d87afa152e54f88ac22e5d69ead6b69",
      "status": 2,
      "log": [
        {
          "message": "ModifyVariable succeeded",
          "logLevel": 2,
          "timestamp": "2023-10-04T22:34:31.407518+00:00"
        },
        {
          "message": "ScheduleActivity succeeded",
          "logLevel": 2,
          "timestamp": "2023-10-04T22:34:31.415783+00:00"
        }
      ],
      "createdAt": "2023-10-04T22:34:31.28188+00:00",
      "completedAt": "2023-10-04T22:34:31.426614+00:00",
      "id": "92062c77cbcd419a87ac621886e5f60a"
    }
  ]
}

Immediate Alterations

Instead of submitting alteration plans for asynchronous execution, you can apply alterations immediately using the IAlterationRunner service. For example:

var alterations = new List<IAlteration>
{
    new ModifyVariable("MyVariable", "MyValue")
},

var workflowInstanceIds = new[] { "26cf02e60d4a4be7b99a8588b7ac3bb9" };
var runner = serviceProvider.GetRequiredService<IAlterationRunner>();
var results = await runner.RunAsync(plan, cancellationToken);

When an alteration plan is executed immediately, the alterations are applied synchronously and the results are returned. You will have to manually schedule affected workflow instances to resume execution. Use the IAlteredWorkflowDispatcher:

var dispatcher = serviceProvider.GetRequiredService<IAlteredWorkflowDispatcher>();
await dispatcher.DispatchAsync(results, cancellationToken);

This will tell the workflow engine to pickup the altered workflow instances and execute them.

Extensibility

Elsa Workflows supports custom alteration types, allowing developers to define their own types and utilize them as alterations.

To define a custom alteration type, implement the IAlteration interface.

public interface IAlteration
{
}

Next, implement an alteration handler that handles the alteration type.

public interface IAlterationHandler where T : IAlteration
{
    bool CanHandle(IAlteration alteration);
    ValueTask HandleAsync(AlterationHandlerContext context);
}

Or, derive from the AlterationHandlerBase<T> base class to simplify the implementation.

Finally, register the alteration handler with the service collection.

services.AddElsa(elsa => 
{
    elsa.UseAlterations(alterations => 
    {
        alterations.AddAlteration<MyAlteration, MyAlterationHandler>();
    })
});

Example

The following example demonstrates how to define a custom alteration type and handler.

public class MyAlteration : IAlteration
{
    public string Message { get; set; }
}

public class MyAlterationHandler : AlterationHandlerBase<MyAlteration>
{
    public override async ValueTask HandleAsync(AlterationHandlerContext<MyAlteration> context, CancellationToken cancellationToken = default)
    {
        context.WorkflowExecutionContext.Output.Add("Message", context.Alteration.Message);
    }
}