Lesson 1: Hello world
The smallest useful workflow: the state comes from the start request, one human task opens, and the workflow completes when a person completes the task.
The start request
/// <summary>The start request: the input contract of the workflow.</summary>
public sealed class AcknowledgeDocumentRequest
{
/// <summary>The business key. Instances and tasks can be searched by it.</summary>
[WorkflowBusinessId]
public string DocumentId { get; set; } = string.Empty;
public string Recipient { get; set; } = string.Empty;
}
The workflow
/// <summary>One human task: the recipient acknowledges a document, and the workflow completes.</summary>
public sealed class AcknowledgeDocumentWorkflow : IDeclarativeWorkflow<AcknowledgeDocumentRequest>
{
// The name and the version identify the definition. The name is the counted unit of the licence.
public string WorkflowName => "AcknowledgeDocument";
public string WorkflowVersion => "1.0.0";
public string DisplayName => "Acknowledge a document";
// The roles that may work the workflow's tasks, unless a task names its own roles.
public IReadOnlyCollection<string> WorkflowRoles { get; } = ["staff"];
public WorkflowSpec<AcknowledgeDocumentRequest> Spec { get; } = WorkflowSpec.For<AcknowledgeDocumentRequest>()
// The workflow state, built from the start request ("start.*").
.InitializeState(
WorkflowExpr.Obj(
WorkflowExpr.Prop("documentId", WorkflowExpr.Path("start.documentId")),
WorkflowExpr.Prop("recipient", WorkflowExpr.Path("start.recipient"))))
// The task: name (unique in the workflow), type (the form a client shows), route.
.AddTask(
WorkflowHumanTask.For<AcknowledgeDocumentRequest>(
"Acknowledge document",
"DocumentAcknowledgement",
"documents/acknowledge")
.WithPayload(
WorkflowExpr.Obj(
WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId"))))
.OnComplete(flow => flow.Complete()))
// The first steps: open the task and wait.
.StartWith(flow => flow.ActivateTask("Acknowledge document"))
.Build();
public IReadOnlyCollection<WorkflowTaskDescriptor> Tasks => Spec.TaskDescriptors;
}
Concepts
IDeclarativeWorkflow<TStartRequest>: the contract of every workflow class.WorkflowSpec.For<T>(): the builder;InitializeState,AddTask,StartWith,Build.WorkflowHumanTask.For<T>(name, type, route): a task;OnCompletelists the steps after it.WorkflowExpr: every value is an expression.start.documentIdreads the start request,state.documentIdthe workflow state.
What happens at run time
- A client starts
AcknowledgeDocumentwith{ "documentId": "DOC-1", "recipient": "staff-1" }. - The state becomes
{ "documentId": "DOC-1", "recipient": "staff-1" }, and the business reference isDOC-1. - The task
Acknowledge documentopens for the rolestaff. - A member of
staffcompletes the task;OnCompleterunsComplete(), and the instance isCompleted.
The complete code
The lesson’s complete code. It uses the namespace of the tutorials; put the classes in a namespace of yours.
AcknowledgeDocumentWorkflow.cs:
using StellaOps.Workflow.Abstractions;
using StellaOps.Workflow.Contracts;
namespace Examples.Workflow.Tutorials.HelloWorld;
/// <summary>The start request: the input contract of the workflow.</summary>
public sealed class AcknowledgeDocumentRequest
{
/// <summary>The business key. Instances and tasks can be searched by it.</summary>
[WorkflowBusinessId]
public string DocumentId { get; set; } = string.Empty;
public string Recipient { get; set; } = string.Empty;
}
/// <summary>One human task: the recipient acknowledges a document, and the workflow completes.</summary>
public sealed class AcknowledgeDocumentWorkflow : IDeclarativeWorkflow<AcknowledgeDocumentRequest>
{
// The name and the version identify the definition. The name is the counted unit of the licence.
public string WorkflowName => "AcknowledgeDocument";
public string WorkflowVersion => "1.0.0";
public string DisplayName => "Acknowledge a document";
// The roles that may work the workflow's tasks, unless a task names its own roles.
public IReadOnlyCollection<string> WorkflowRoles { get; } = ["staff"];
public WorkflowSpec<AcknowledgeDocumentRequest> Spec { get; } = WorkflowSpec.For<AcknowledgeDocumentRequest>()
// The workflow state, built from the start request ("start.*").
.InitializeState(
WorkflowExpr.Obj(
WorkflowExpr.Prop("documentId", WorkflowExpr.Path("start.documentId")),
WorkflowExpr.Prop("recipient", WorkflowExpr.Path("start.recipient"))))
// The task: name (unique in the workflow), type (the form a client shows), route.
.AddTask(
WorkflowHumanTask.For<AcknowledgeDocumentRequest>(
"Acknowledge document",
"DocumentAcknowledgement",
"documents/acknowledge")
.WithPayload(
WorkflowExpr.Obj(
WorkflowExpr.Prop("documentId", WorkflowExpr.Path("state.documentId"))))
.OnComplete(flow => flow.Complete()))
// The first steps: open the task and wait.
.StartWith(flow => flow.ActivateTask("Acknowledge document"))
.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 AcknowledgeDocumentWorkflow(), "acknowledge-document.definition.json");
Next: Lesson 2: Service tasks.
