Lesson 4: Human tasks

A reviewer approves a document, rejects it, or asks for changes. A change request sends the document to its author; the revision returns to the reviewer. A review left open for three days escalates to an editor.

The review task

.AddTask(
    WorkflowHumanTask.For<DocumentReviewRequest>("Review document", "DocumentReview", "documents/review", ["reviewer"])
        .WithPayload(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId")),
                WorkflowExpr.Prop("title", WorkflowExpr.Path("state.title")),
                WorkflowExpr.Prop("revision", WorkflowExpr.Path("state.revision"))))
        // Three days to act; then the escalation task opens and the review task closes.
        .WithTimeout(259200, timedOut => timedOut.ActivateTask("Escalated review"))
        .OnComplete(flow => flow
            .Set("decision", WorkflowExpr.Path("payload.decision"))
            .WhenExpression(
                "Changes requested?",
                WorkflowExpr.Eq(WorkflowExpr.Path("payload.decision"), WorkflowExpr.String("changes")),
                changes => changes
                    .Set("comments", WorkflowExpr.Path("payload.comments"))
                    .ActivateTask("Revise document"),
                final => final.Complete())))

The revision task

.AddTask(
    WorkflowHumanTask.For<DocumentReviewRequest>("Revise document", "DocumentRevision", "documents/revise", ["author"])
        .WithPayload(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId")),
                WorkflowExpr.Prop("comments", WorkflowExpr.Path("state.comments"))))
        // The revised document goes back to the reviewer: the same task opens again.
        .OnComplete(flow => flow
            .Set("revision", WorkflowExpr.Func("add", WorkflowExpr.Path("state.revision"), WorkflowExpr.Number(1)))
            .ActivateTask("Review document")))

Roles computed when the task opens

A purchase request is approved by the approvers of its cost centre. One definition serves every cost centre: ActivateTask takes an expression whose value is the task’s roles, computed from the state when the task opens.

// The approvers of the request's cost centre, for example "approver-cc-410", computed from the
// state when the task opens. They replace the task roles and the workflow roles for this task.
.StartWith(flow => flow.ActivateTask(
    "Approve purchase",
    WorkflowExpr.Array(
        WorkflowExpr.Func("concat", WorkflowExpr.String("approver-"), WorkflowExpr.Path("state.costCentre")))))

A request for the cost centre cc-410 opens the task with the roles ["approver-cc-410"]: its runtimeRoles and effectiveRoles both read approver-cc-410. A member of purchasing, the workflow role, is refused with 403 WorkflowTaskActionDenied; an actor with the role approver-cc-410 completes the task. When the expression yields no role, the task roles apply, or the workflow roles when the task has none.

Cases:

Pitfall: the roles are computed once, when the task opens. A change to the state later does not change the roles of an open task; assign the task to other roles instead (Human tasks and the HTTP API).

Concepts

The complete code

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

DocumentReviewWorkflow.cs:

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

namespace Examples.Workflow.Tutorials.HumanTasks;

public sealed class DocumentReviewRequest
{
    [WorkflowBusinessId]
    public string DocumentId { get; set; } = string.Empty;

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

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

/// <summary>
/// A reviewer approves a document, rejects it or asks for changes. A change request opens a revision
/// task for the author; the revised document returns to the reviewer. A review left open for three
/// days escalates to an editor.
/// </summary>
public sealed class DocumentReviewWorkflow : IDeclarativeWorkflow<DocumentReviewRequest>
{
    public string WorkflowName => "DocumentReview";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Document review";

    public IReadOnlyCollection<string> WorkflowRoles { get; } = ["reviewer", "author", "editor"];

    public WorkflowSpec<DocumentReviewRequest> Spec { get; } = WorkflowSpec.For<DocumentReviewRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("documentId", WorkflowExpr.Path("start.documentId")),
                WorkflowExpr.Prop("title", WorkflowExpr.Path("start.title")),
                WorkflowExpr.Prop("author", WorkflowExpr.Path("start.author")),
                WorkflowExpr.Prop("revision", WorkflowExpr.Number(1))))
        .AddTask(
            WorkflowHumanTask.For<DocumentReviewRequest>("Review document", "DocumentReview", "documents/review", ["reviewer"])
                .WithPayload(
                    WorkflowExpr.Obj(
                        WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId")),
                        WorkflowExpr.Prop("title", WorkflowExpr.Path("state.title")),
                        WorkflowExpr.Prop("revision", WorkflowExpr.Path("state.revision"))))
                // Three days to act; then the escalation task opens and the review task closes.
                .WithTimeout(259200, timedOut => timedOut.ActivateTask("Escalated review"))
                .OnComplete(flow => flow
                    .Set("decision", WorkflowExpr.Path("payload.decision"))
                    .WhenExpression(
                        "Changes requested?",
                        WorkflowExpr.Eq(WorkflowExpr.Path("payload.decision"), WorkflowExpr.String("changes")),
                        changes => changes
                            .Set("comments", WorkflowExpr.Path("payload.comments"))
                            .ActivateTask("Revise document"),
                        final => final.Complete())))
        .AddTask(
            WorkflowHumanTask.For<DocumentReviewRequest>("Revise document", "DocumentRevision", "documents/revise", ["author"])
                .WithPayload(
                    WorkflowExpr.Obj(
                        WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId")),
                        WorkflowExpr.Prop("comments", WorkflowExpr.Path("state.comments"))))
                // The revised document goes back to the reviewer: the same task opens again.
                .OnComplete(flow => flow
                    .Set("revision", WorkflowExpr.Func("add", WorkflowExpr.Path("state.revision"), WorkflowExpr.Number(1)))
                    .ActivateTask("Review document")))
        .AddTask(
            WorkflowHumanTask.For<DocumentReviewRequest>("Escalated review", "DocumentReview", "documents/review", ["editor"])
                .WithPayload(WorkflowExpr.Obj(WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId"))))
                .OnComplete(flow => flow
                    .Set("decision", WorkflowExpr.Path("payload.decision"))
                    .Complete()))
        .StartWith(flow => flow.ActivateTask("Review document"))
        .Build();

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

PurchaseRequestWorkflow.cs:

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

namespace Examples.Workflow.Tutorials.HumanTasks;

public sealed class PurchaseRequestRequest
{
    [WorkflowBusinessId]
    public string RequestId { get; set; } = string.Empty;

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

    public decimal Amount { get; set; }
}

/// <summary>
/// A purchase request is approved by the approvers of its cost centre. The roles of the approval task
/// are computed from the state when the task opens, so one definition serves every cost centre.
/// </summary>
public sealed class PurchaseRequestWorkflow : IDeclarativeWorkflow<PurchaseRequestRequest>
{
    public string WorkflowName => "PurchaseRequest";

    public string WorkflowVersion => "1.0.0";

    public string DisplayName => "Purchase request";

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

    public WorkflowSpec<PurchaseRequestRequest> Spec { get; } = WorkflowSpec.For<PurchaseRequestRequest>()
        .InitializeState(
            WorkflowExpr.Obj(
                WorkflowExpr.Prop("requestId", WorkflowExpr.Path("start.requestId")),
                WorkflowExpr.Prop("costCentre", WorkflowExpr.Path("start.costCentre")),
                WorkflowExpr.Prop("amount", WorkflowExpr.Path("start.amount"))))
        .AddTask(
            WorkflowHumanTask.For<PurchaseRequestRequest>("Approve purchase", "PurchaseApproval", "purchases/approve")
                .WithPayload(
                    WorkflowExpr.Obj(
                        WorkflowExpr.Prop("requestId", WorkflowExpr.Path("state.requestId")),
                        WorkflowExpr.Prop("amount", WorkflowExpr.Path("state.amount"))))
                .OnComplete(flow => flow
                    .Set("decision", WorkflowExpr.Path("payload.decision"))
                    .Complete()))
        // The approvers of the request's cost centre, for example "approver-cc-410", computed from the
        // state when the task opens. They replace the task roles and the workflow roles for this task.
        .StartWith(flow => flow.ActivateTask(
            "Approve purchase",
            WorkflowExpr.Array(
                WorkflowExpr.Func("concat", WorkflowExpr.String("approver-"), WorkflowExpr.Path("state.costCentre")))))
        .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 5: Sub-workflows.