How to: Author a workflow

Learn how to develop and author workflows

This article provides a high-level overview of how to author workflows that are executed by the Dapr Workflow engine.

Note

If you haven’t already, try out the workflow quickstart for a quick walk-through on how to use workflows.

Author workflows as code

Dapr Workflow logic is implemented using general purpose programming languages, allowing you to:

Use your preferred programming language (no need to learn a new DSL or YAML schema).
Have access to the language’s standard libraries.
Build your own libraries and abstractions.
Use debuggers and examine local variables.
Write unit tests for your workflows, just like any other part of your application logic.

The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar simply drives the execution of the workflows, leaving all the workflow activities to be part of the application. The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar simply drives the execution of the workflows, leaving all the workflow activitie to be part of the application.

Write the workflow activities

Define the workflow activities you’d like your workflow to perform. Activities are a class definition and can take inputs and outputs. Activities also participate in dependency injection, like binding to a Dapr client.

.NET

Continuing the ASP.NET order processing example, the OrderProcessingWorkflow class is derived from a base class called Workflow with input and output parameter types.

It also includes a RunAsync method that does the heavy lifting of the workflow and calls the workflow activities. The activities called in the example are:

NotifyActivity: Receive notification of a new order.
ReserveInventoryActivity: Check for sufficient inventory to meet the new order.
ProcessPaymentActivity: Process payment for the order. Includes NotifyActivity to send notification of successful order.

 class OrderProcessingWorkflow : Workflow<OrderPayload, OrderResult>
    {
        public override async Task<OrderResult> RunAsync(WorkflowContext context, OrderPayload order)
        {
            //...
            await context.CallActivityAsync(
                nameof(NotifyActivity),
                new Notification($"Received order {orderId} for {order.Name} at {order.TotalCost:c}"));
            //...
            InventoryResult result = await context.CallActivityAsync<InventoryResult>(
                nameof(ReserveInventoryActivity),
                new InventoryRequest(RequestId: orderId, order.Name, order.Quantity));
            //...
            await context.CallActivityAsync(
                nameof(ProcessPaymentActivity),
                new PaymentRequest(RequestId: orderId, order.TotalCost, "USD"));
            await context.CallActivityAsync(
                nameof(NotifyActivity),
                new Notification($"Order {orderId} processed successfully!"));
            // End the workflow with a success result
            return new OrderResult(Processed: true);
        }
    }

Write the workflow

Compose the workflow activities into a workflow.

.NET

In the following example, for a basic ASP.NET order processing application using the .NET SDK, your project code would include:

A NuGet package called Dapr.Workflow to receive the .NET SDK capabilities
A builder with an extension method called AddDaprWorkflow
- This will allow you to register workflows and workflow activities (tasks that workflows can schedule)
HTTP API calls
- One for submitting a new order
- One for checking the status of an existing order

using Dapr.Workflow;
//...
// Dapr Workflows are registered as part of the service configuration
builder.Services.AddDaprWorkflow(options =>
{
    // Note that it's also possible to register a lambda function as the workflow
    // or activity implementation instead of a class.
    options.RegisterWorkflow<OrderProcessingWorkflow>();
    // These are the activities that get invoked by the workflow(s).
    options.RegisterActivity<NotifyActivity>();
    options.RegisterActivity<ReserveInventoryActivity>();
    options.RegisterActivity<ProcessPaymentActivity>();
});
WebApplication app = builder.Build();
// POST starts new order workflow instance
app.MapPost("/orders", async (WorkflowEngineClient client, [FromBody] OrderPayload orderInfo) =>
{
    if (orderInfo?.Name == null)
    {
        return Results.BadRequest(new
        {
            message = "Order data was missing from the request",
            example = new OrderPayload("Paperclips", 99.95),
        });
    }
//...
});
// GET fetches state for order workflow to report status
app.MapGet("/orders/{orderId}", async (string orderId, WorkflowEngineClient client) =>
{
    WorkflowState state = await client.GetWorkflowStateAsync(orderId, true);
    if (!state.Exists)
    {
        return Results.NotFound($"No order with ID = '{orderId}' was found.");
    }
    var httpResponsePayload = new
    {
        details = state.ReadInputAs<OrderPayload>(),
        status = state.RuntimeStatus.ToString(),
        result = state.ReadOutputAs<OrderResult>(),
    };
//...
}).WithName("GetOrderInfoEndpoint");
app.Run();

Important

Because of how replay-based workflows execute, you’ll write logic that does things like I/O and interacting with systems inside activities. Meanwhile, the workflow method is just for orchestrating those activities.

Next steps

Now that you’ve authored a workflow, learn how to manage it.

Manage workflows >>

Last modified February 10, 2023: fix link (14f07709)

How to: Author workflows