diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md index b9f7d260750..b6191d23de3 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md +++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md @@ -28,19 +28,88 @@ The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar si ## 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. +[Workflow activities]({{< ref "workflow-features-concepts.md#workflow-activites" >}}) are the basic unit of work in a workflow and are the tasks that get orchestrated in the business process. {{< tabs ".NET" >}} {{% codetab %}} -Continuing the ASP.NET order processing example, the `OrderProcessingWorkflow` class is derived from a base class called `Workflow` with input and output parameter types. +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. -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: +The activities called in the example below 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. +### NotifyActivity + +```csharp +public class NotifyActivity : WorkflowActivity +{ + //... + + public NotifyActivity(ILoggerFactory loggerFactory) + { + this.logger = loggerFactory.CreateLogger(); + } + + //... +} +``` + +[See the full `NotifyActivity.cs` workflow activity example.](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Activities/NotifyActivity.cs) + +### ReserveInventoryActivity + +```csharp +public class ReserveInventoryActivity : WorkflowActivity +{ + //... + + public ReserveInventoryActivity(ILoggerFactory loggerFactory, DaprClient client) + { + this.logger = loggerFactory.CreateLogger(); + this.client = client; + } + + //... + +} +``` +[See the full `ReserveInventoryActivity.cs` workflow activity example.](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Activities/ReserveInventoryActivity.cs) + +### ProcessPaymentActivity + +```csharp +public class ProcessPaymentActivity : WorkflowActivity +{ + //... + public ProcessPaymentActivity(ILoggerFactory loggerFactory) + { + this.logger = loggerFactory.CreateLogger(); + } + + //... + +} +``` + +[See the full `ProcessPaymentActivity.cs` workflow activity example.](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Activities/ProcessPaymentActivity.cs) + +{{% /codetab %}} + +{{< /tabs >}} + +## Write the workflow + +Next, register and call the activites in a workflow. + +{{< tabs ".NET" >}} + +{{% codetab %}} + +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. + ```csharp class OrderProcessingWorkflow : Workflow { @@ -73,19 +142,21 @@ It also includes a `RunAsync` method that does the heavy lifting of the workflow } ``` +[See the full workflow example in `OrderProcessingWorkflow.cs`.](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Workflows/OrderProcessingWorkflow.cs) + {{% /codetab %}} {{< /tabs >}} -## Write the workflow +## Write the application -Compose the workflow activities into a workflow. +Finally, compose the application using the workflow. {{< tabs ".NET" >}} {{% codetab %}} -[In the following example](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Program.cs), for a basic ASP.NET order processing application using the .NET SDK, your project code would include: +[In the following `Program.cs` example](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Program.cs), 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` diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md index 34aa106034e..7b2af68b477 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md +++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md @@ -21,16 +21,27 @@ string workflowComponent = "dapr"; string workflowName = "OrderProcessingWorkflow"; OrderPayload input = new OrderPayload("Paperclips", 99.95); Dictionary workflowOptions; // This is an optional parameter -CancellationToken cts = CancellationToken.None; -// Start the workflow. This returns back a "WorkflowReference" which contains the instanceID for the particular workflow instance. -WorkflowReference startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions, cts); +// Start the workflow. This returns back a "StartWorkflowResponse" which contains the instance ID for the particular workflow instance. +StartWorkflowResponse startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions); -// Get information on the workflow. This response will contain information such as the status of the workflow, when it started, and more! +// Get information on the workflow. This response contains information such as the status of the workflow, when it started, and more! GetWorkflowResponse getResponse = await daprClient.GetWorkflowAsync(orderId, workflowComponent, workflowName); // Terminate the workflow -await daprClient.TerminateWorkflowAsync(instanceId, workflowComponent); +await daprClient.TerminateWorkflowAsync(orderId, workflowComponent); + +// Raise an event (an incoming purchase order) that your workflow will wait for. This returns the item waiting to be purchased. +await daprClient.RaiseWorkflowEventAsync(orderId, workflowComponent, workflowName, input); + +// Pause +await daprClient.PauseWorkflowAsync(orderId, workflowComponent); + +// Resume +await daprClient.ResumeWorkflowAsync(orderId, workflowComponent); + +// Purge +await daprClient.PurgeWorkflowAsync(orderId, workflowComponent); ``` {{% /codetab %}} @@ -44,7 +55,7 @@ Manage your workflow using HTTP calls. The example below plugs in the properties To start your workflow with an ID `12345678`, run: -```bash +```http POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678 ``` @@ -54,15 +65,49 @@ Note that workflow instance IDs can only contain alphanumeric characters, unders To terminate your workflow with an ID `12345678`, run: -```bash +```http POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/terminate ``` +### Raise an event + +For workflow components that support subscribing to external events, such as the Dapr Workflow engine, you can use the following "raise event" API to deliver a named event to a specific workflow instance. + +```http +POST http://localhost:3500/v1.0-alpha1/workflows///raiseEvent/ +``` + +> An `eventName` can be any function. + +### Pause or resume a workflow + +To plan for down-time, wait for inputs, and more, you can pause and then resume a workflow. To pause a workflow with an ID `12345678` until triggered to resume, run: + +```http +POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/pause +``` + +To resume a workflow with an ID `12345678`, run: + +```http +POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/resume +``` + +### Purge a workflow + +The purge API can be used to permanently delete workflow metadata from the underlying state store, including any stored inputs, outputs, and workflow history records. This is often useful for implementing data retention policies and for freeing resources. + +Only workflow instances in the COMPLETED, FAILED, or TERMINATED state can be purged. If the workflow is in any other state, calling purge returns an error. + +```http +POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/purge +``` + ### Get information about a workflow To fetch workflow information (outputs and inputs) with an ID `12345678`, run: -```bash +```http GET http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678 ``` diff --git a/daprdocs/content/en/reference/api/workflow_api.md b/daprdocs/content/en/reference/api/workflow_api.md index 442b206ad29..4ddf8b7209f 100644 --- a/daprdocs/content/en/reference/api/workflow_api.md +++ b/daprdocs/content/en/reference/api/workflow_api.md @@ -12,7 +12,7 @@ Dapr provides users with the ability to interact with workflows and comes with a Start a workflow instance with the given name and optionally, an instance ID. -```bash +```http POST http://localhost:3500/v1.0-alpha1/workflows///start[?instanceId=] ``` @@ -22,7 +22,7 @@ Note that workflow instance IDs can only contain alphanumeric characters, unders Parameter | Description --------- | ----------- -`workflowComponentName` | Current default is `dapr` for Dapr Workflows +`workflowComponentName` | Use `dapr` for Dapr Workflows `workflowName` | Identify the workflow type `instanceId` | (Optional) Unique value created for each run of a specific workflow @@ -52,7 +52,7 @@ The API call will provide a response similar to this: Terminate a running workflow instance with the given name and instance ID. -```bash +```http POST http://localhost:3500/v1.0-alpha1/workflows//terminate ``` @@ -60,7 +60,7 @@ POST http://localhost:3500/v1.0-alpha1/workflows//terminate Parameter | Description --------- | ----------- -`workflowComponentName` | Current default is `dapr` for Dapr Workflows +`workflowComponentName` | Use `dapr` for Dapr Workflows `instanceId` | Unique value created for each run of a specific workflow ### HTTP response codes @@ -75,11 +75,125 @@ Code | Description This API does not return any content. -### Get workflow request +## Raise Event request + +For workflow components that support subscribing to external events, such as the Dapr Workflow engine, you can use the following "raise event" API to deliver a named event to a specific workflow instance. + +```http +POST http://localhost:3500/v1.0-alpha1/workflows///raiseEvent/ +``` + +{{% alert title="Note" color="primary" %}} + The exact mechanism for subscribing to an event depends on the workflow component that you're using. Dapr Workflow has one way of subscribing to external events but other workflow components might have different ways. + +{{% /alert %}} + +### URL parameters + +Parameter | Description +--------- | ----------- +`workflowComponentName` | Use `dapr` for Dapr Workflows +`instanceId` | Unique value created for each run of a specific workflow +`eventName` | The name of the event to raise + +### HTTP response codes + +Code | Description +---- | ----------- +`202` | Accepted +`400` | Request was malformed +`500` | Request formatted correctly, error in dapr code or underlying component + +### Response content + +None. + +## Pause workflow request + +Pause a running workflow instance. + +```http +POST http://localhost:3500/v1.0-alpha1/workflows///pause +``` + +### URL parameters + +Parameter | Description +--------- | ----------- +`workflowComponentName` | Use `dapr` for Dapr Workflows +`instanceId` | Unique value created for each run of a specific workflow + +### HTTP response codes + +Code | Description +---- | ----------- +`202` | Accepted +`400` | Request was malformed +`500` | Error in Dapr code or underlying component + +### Response content + +None. + +## Resume workflow request + +Resume a paused workflow instance. + +```http +POST http://localhost:3500/v1.0-alpha1/workflows///resume +``` + +### URL parameters + +Parameter | Description +--------- | ----------- +`workflowComponentName` | Use `dapr` for Dapr Workflows +`instanceId` | Unique value created for each run of a specific workflow + +### HTTP response codes + +Code | Description +---- | ----------- +`202` | Accepted +`400` | Request was malformed +`500` | Error in Dapr code or underlying component + +### Response content + +None. + +## Purge workflow request + +Purge the workflow state from your state store with the workflow's instance ID. + +```http +POST http://localhost:3500/v1.0-alpha1/workflows///purge +``` + +### URL parameters + +Parameter | Description +--------- | ----------- +`workflowComponentName` | Use `dapr` for Dapr Workflows +`instanceId` | Unique value created for each run of a specific workflow + +### HTTP response codes + +Code | Description +---- | ----------- +`202` | Accepted +`400` | Request was malformed +`500` | Error in Dapr code or underlying component + +### Response content + +None. + +## Get workflow request Get information about a given workflow instance. -```bash +```http GET http://localhost:3500/v1.0-alpha1/workflows// ``` @@ -87,7 +201,7 @@ GET http://localhost:3500/v1.0-alpha1/workflows//