Lesson 7: Shared helpers

Several workflows of one application send the same payloads and end with the same steps. Helpers keep those in one place, and the analyzer still checks them.

Payload helpers

/// <summary>Expression helpers shared by several workflows.</summary>
public static class Payloads
{
    /// <summary>The customer reference that every customer-service call sends.</summary>
    public static WorkflowExpressionDefinition CustomerReference() =>
        WorkflowExpr.Obj(WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")));
}

A flow extension

/// <summary>A step sequence several workflows end with: notify the customer, then complete.</summary>
public static class FlowExtensions
{
    public static WorkflowFlowBuilder<TStartRequest> NotifyCustomerAndComplete<TStartRequest>(
        this WorkflowFlowBuilder<TStartRequest> flow)
        where TStartRequest : class
    {
        return flow
            .Call("Notify customer", new HttpAddress("notifications", "/messages"), Payloads.CustomerReference())
            .Complete();
    }
}

A workflow that uses them

/// <summary>Updates a customer's address and notifies the customer, using the shared helpers.</summary>
public sealed class AddressChangeWorkflow : IDeclarativeWorkflow<AddressChangeRequest>
{
    public string WorkflowName => "AddressChange";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Customer address change";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["customer-service"];

    public WorkflowSpec<AddressChangeRequest> Spec { get; } = WorkflowSpec.For<AddressChangeRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("customerId", WorkflowExpr.Path("start.customerId")),
                WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("start.newAddress"))))
        .StartWith(flow => flow
            .Call(
                "Update address",
                new EndpointAddress("customers", "/addresses"),
                WorkflowExpr.Obj(
                    WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")),
                    WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("state.newAddress"))))
            .NotifyCustomerAndComplete())
        .Build();

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

Concepts

The complete code

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

SharedHelpers.cs:

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

namespace Examples.Workflow.Tutorials.SharedHelpers;

/// <summary>Expression helpers shared by several workflows.</summary>
public static class Payloads
{
    /// <summary>The customer reference that every customer-service call sends.</summary>
    public static WorkflowExpressionDefinition CustomerReference() =>
        WorkflowExpr.Obj(WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")));
}

/// <summary>A step sequence several workflows end with: notify the customer, then complete.</summary>
public static class FlowExtensions
{
    public static WorkflowFlowBuilder<TStartRequest> NotifyCustomerAndComplete<TStartRequest>(
        this WorkflowFlowBuilder<TStartRequest> flow)
        where TStartRequest : class
    {
        return flow
            .Call("Notify customer", new HttpAddress("notifications", "/messages"), Payloads.CustomerReference())
            .Complete();
    }
}

public sealed class AddressChangeRequest
{
    [WorkflowBusinessId]
    public string CustomerId { get; set; } = string.Empty;

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

/// <summary>Updates a customer's address and notifies the customer, using the shared helpers.</summary>
public sealed class AddressChangeWorkflow : IDeclarativeWorkflow<AddressChangeRequest>
{
    public string WorkflowName => "AddressChange";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Customer address change";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["customer-service"];

    public WorkflowSpec<AddressChangeRequest> Spec { get; } = WorkflowSpec.For<AddressChangeRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("customerId", WorkflowExpr.Path("start.customerId")),
                WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("start.newAddress"))))
        .StartWith(flow => flow
            .Call(
                "Update address",
                new EndpointAddress("customers", "/addresses"),
                WorkflowExpr.Obj(
                    WorkflowExpr.Prop("customerId", WorkflowExpr.Path("state.customerId")),
                    WorkflowExpr.Prop("newAddress", WorkflowExpr.Path("state.newAddress"))))
            .NotifyCustomerAndComplete())
        .Build();

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

The canonical form

The C# compiles to a canonical JSON definition, the document the engine validates, stores and renders. Write it to a file with the export helper of lesson 9:

Next: Lesson 8: Expressions.