Lesson 11: Changing a workflow

A return request is inspected by the warehouse, and the refund is granted. Version 2.0.0 adds a finance approval for refunds of 500 or more. Instances that started on 1.0.0 finish on 1.0.0; new instances start on 2.0.0. This lesson shows how both versions run side by side, and when the old one can go.

Version 1.0.0

/// <summary>Version 1.0.0: a warehouse clerk inspects the returned goods and the refund is granted.</summary>
public sealed class ReturnRequestWorkflowV1 : IDeclarativeWorkflow<ReturnRequest>
{
    public string WorkflowName => "ReturnRequest";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Return request";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["warehouse"];

    public WorkflowSpec<ReturnRequest> Spec { get; } = WorkflowSpec.For<ReturnRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("returnId", WorkflowExpr.Path("start.returnId")),
                WorkflowExpr.Prop("customer", WorkflowExpr.Path("start.customer"))))
        .AddTask(
            WorkflowHumanTask.For<ReturnRequest>("Inspect return", "ReturnInspection", "returns/inspect")
                .WithPayload(WorkflowExpr.Obj(WorkflowExpr.Prop("returnId", WorkflowExpr.Path("state.returnId"))))
                .OnComplete(flow => flow
                    .Set("refund", WorkflowExpr.Path("payload.refund"))
                    .Complete()))
        .StartWith(flow => flow.ActivateTask("Inspect return"))
        .Build();

    public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}

Version 2.0.0

The same workflow name with a higher version. The inspection task keeps its name, so an inspection opened by 1.0.0 is still a task of the workflow:

/// <summary>
/// Version 2.0.0, the same workflow name: a refund of 500 or more now also needs a finance approval.
/// The inspection task keeps its name, so the open inspections of version 1.0.0 stay valid.
/// </summary>
public sealed class ReturnRequestWorkflowV2 : IDeclarativeWorkflow<ReturnRequest>
{
    public string WorkflowName => "ReturnRequest";

    public string WorkflowVersion => "2.0.0";

    public string DisplayName => "Return request";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["warehouse", "finance"];

    public WorkflowSpec<ReturnRequest> Spec { get; } = WorkflowSpec.For<ReturnRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("returnId", WorkflowExpr.Path("start.returnId")),
                WorkflowExpr.Prop("customer", WorkflowExpr.Path("start.customer"))))
        .AddTask(
            WorkflowHumanTask.For<ReturnRequest>("Inspect return", "ReturnInspection", "returns/inspect", ["warehouse"])
                .WithPayload(WorkflowExpr.Obj(WorkflowExpr.Prop("returnId", WorkflowExpr.Path("state.returnId"))))
                .OnComplete(flow => flow
                    .Set("refund", WorkflowExpr.Path("payload.refund"))
                    .WhenExpression(
                        "Large refund?",
                        WorkflowExpr.Gte(WorkflowExpr.Path("state.refund"), WorkflowExpr.Number(500)),
                        large => large.ActivateTask("Approve refund"),
                        small => small.Complete())))
        .AddTask(
            WorkflowHumanTask.For<ReturnRequest>("Approve refund", "RefundApproval", "returns/approve", ["finance"])
                .WithPayload(
                    WorkflowExpr.Obj(
                        WorkflowExpr.Prop("returnId", WorkflowExpr.Path("state.returnId")),
                        WorkflowExpr.Prop("refund", WorkflowExpr.Path("state.refund"))))
                .OnComplete(flow => flow.Complete()))
        .StartWith(flow => flow.ActivateTask("Inspect return"))
        .Build();

    public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}

Registering both versions

/// <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;
}

What happens at run time

  1. A start without workflowVersion takes the highest registered version, 2.0.0. A start that names "workflowVersion": "1.0.0" takes that version.

  2. An instance keeps the version that started it. When its inspection is completed with { "refund": 900 }, an instance on 1.0.0 completes, and an instance on 2.0.0 opens Approve refund for finance.

  3. Before you remove the 1.0.0 registration, check that no instance of it is open:

    curl -s "http://localhost:5090/api/workflow/instances?workflowName=ReturnRequest&workflowVersion=1.0.0&status=Open" \
      -H "Authorization: Bearer $TOKEN"
    

    Expected result: "instances": []. Then remove ReturnRequestWorkflowV1 and its registration.

Concepts

Pitfalls

The complete code

The lesson’s complete code. It uses the namespace of the tutorials; put the classes in a namespace of yours.

ReturnRequestWorkflows.cs:

using Microsoft.Extensions.DependencyInjection;

using StellaOps.Workflow.Abstractions;
using StellaOps.Workflow.Contracts;

namespace Examples.Workflow.Tutorials.ChangingAWorkflow;

public sealed class ReturnRequest
{
    [WorkflowBusinessId]
    public string ReturnId { get; set; } = string.Empty;

    public string Customer { get; set; } = string.Empty;
}

/// <summary>Version 1.0.0: a warehouse clerk inspects the returned goods and the refund is granted.</summary>
public sealed class ReturnRequestWorkflowV1 : IDeclarativeWorkflow<ReturnRequest>
{
    public string WorkflowName => "ReturnRequest";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Return request";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["warehouse"];

    public WorkflowSpec<ReturnRequest> Spec { get; } = WorkflowSpec.For<ReturnRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("returnId", WorkflowExpr.Path("start.returnId")),
                WorkflowExpr.Prop("customer", WorkflowExpr.Path("start.customer"))))
        .AddTask(
            WorkflowHumanTask.For<ReturnRequest>("Inspect return", "ReturnInspection", "returns/inspect")
                .WithPayload(WorkflowExpr.Obj(WorkflowExpr.Prop("returnId", WorkflowExpr.Path("state.returnId"))))
                .OnComplete(flow => flow
                    .Set("refund", WorkflowExpr.Path("payload.refund"))
                    .Complete()))
        .StartWith(flow => flow.ActivateTask("Inspect return"))
        .Build();

    public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}

/// <summary>
/// Version 2.0.0, the same workflow name: a refund of 500 or more now also needs a finance approval.
/// The inspection task keeps its name, so the open inspections of version 1.0.0 stay valid.
/// </summary>
public sealed class ReturnRequestWorkflowV2 : IDeclarativeWorkflow<ReturnRequest>
{
    public string WorkflowName => "ReturnRequest";

    public string WorkflowVersion => "2.0.0";

    public string DisplayName => "Return request";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["warehouse", "finance"];

    public WorkflowSpec<ReturnRequest> Spec { get; } = WorkflowSpec.For<ReturnRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("returnId", WorkflowExpr.Path("start.returnId")),
                WorkflowExpr.Prop("customer", WorkflowExpr.Path("start.customer"))))
        .AddTask(
            WorkflowHumanTask.For<ReturnRequest>("Inspect return", "ReturnInspection", "returns/inspect", ["warehouse"])
                .WithPayload(WorkflowExpr.Obj(WorkflowExpr.Prop("returnId", WorkflowExpr.Path("state.returnId"))))
                .OnComplete(flow => flow
                    .Set("refund", WorkflowExpr.Path("payload.refund"))
                    .WhenExpression(
                        "Large refund?",
                        WorkflowExpr.Gte(WorkflowExpr.Path("state.refund"), WorkflowExpr.Number(500)),
                        large => large.ActivateTask("Approve refund"),
                        small => small.Complete())))
        .AddTask(
            WorkflowHumanTask.For<ReturnRequest>("Approve refund", "RefundApproval", "returns/approve", ["finance"])
                .WithPayload(
                    WorkflowExpr.Obj(
                        WorkflowExpr.Prop("returnId", WorkflowExpr.Path("state.returnId")),
                        WorkflowExpr.Prop("refund", WorkflowExpr.Path("state.refund"))))
                .OnComplete(flow => flow.Complete()))
        .StartWith(flow => flow.ActivateTask("Inspect return"))
        .Build();

    public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}

public static class ReturnRequestRegistrations
{
    /// <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;
    }
}

The canonical form

The C# compiles to a canonical JSON definition per version. Write them to files with the export helper of lesson 9:

Back to the lessons.