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

What happens at run time

  1. A client starts AcknowledgeDocument with { "documentId": "DOC-1", "recipient": "staff-1" }.
  2. The state becomes { "documentId": "DOC-1", "recipient": "staff-1" }, and the business reference is DOC-1.
  3. The task Acknowledge document opens for the role staff.
  4. A member of staff completes the task; OnComplete runs Complete(), and the instance is Completed.

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:

Next: Lesson 2: Service tasks.