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:
- Approvers per site, team or customer. Compute the role name from the state, as above.
- The requester’s manager. Put the manager’s role or user group in the start request, and use it as the expression.
- A fixed set plus a computed one. Return an array with both, for example
WorkflowExpr.Array(WorkflowExpr.String("finance"), <computed role>).
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
- Task roles (
["reviewer"]) replace the workflow roles for one task; runtime roles, computed byActivateTask(name, rolesExpression), replace both for one opened task. WithPayload: what the task shows. The completion payload ispayload.*inOnComplete.WithTimeout(seconds, whenTimeout): a deadline and the steps when it passes.AddTaskdeclares a task;ActivateTaskopens it, from any step, including the task’s ownOnComplete.- Who may complete a task: Human tasks and the HTTP API.
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:
CanonicalExport.WriteCanonicalJson(new DocumentReviewWorkflow(), "document-review.definition.json");CanonicalExport.WriteCanonicalJson(new PurchaseRequestWorkflow(), "purchase-request.definition.json");
Next: Lesson 5: Sub-workflows.
