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
A start without
workflowVersiontakes the highest registered version, 2.0.0. A start that names"workflowVersion": "1.0.0"takes that version.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 opensApprove refundfor finance.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 removeReturnRequestWorkflowV1and its registration.
Concepts
- The workflow name is the identity: its instances, its tasks and its Designated Workflow count. A new version of a workflow is not a new Designated Workflow.
- Versions are ordered as semantic versions: 2.0.0 is higher than 1.10.0, and 1.10.0 is higher than 1.9.0.
- A version is immutable once instances run on it. Change the shape of a workflow only in a new version.
- A stored definition follows the same rule: import the new version and activate it (Governed activation and publishing).
Pitfalls
- Changing a version in place. Editing the 1.0.0 class while 1.0.0 instances are open changes the steps they resume with. Copy the class and raise the version instead.
- Renaming a task the old version still opens. Keep every task an open instance can reach under the same name until those instances are finished.
- Removing the old registration too early. An open instance of a version the host no longer registers cannot resume. Check for open instances first, as in step 3.
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:
CanonicalExport.WriteCanonicalJson(new ReturnRequestWorkflowV1(), "return-request-1.0.0.definition.json");CanonicalExport.WriteCanonicalJson(new ReturnRequestWorkflowV2(), "return-request-2.0.0.definition.json");
