How to: Manage workflows

Manage and run workflows

Note

Dapr Workflow is currently in beta. See known limitations for 1.14.1.

Now that you’ve authored the workflow and its activities in your application, you can start, terminate, and get information about the workflow using HTTP API calls. For more information, read the workflow API reference.

Manage your workflow within your code. In the workflow example from the Author a workflow guide, the workflow is registered in the code using the following APIs:

  • start_workflow: Start an instance of a workflow
  • get_workflow: Get information on the status of the workflow
  • pause_workflow: Pauses or suspends a workflow instance that can later be resumed
  • resume_workflow: Resumes a paused workflow instance
  • raise_workflow_event: Raise an event on a workflow
  • purge_workflow: Removes all metadata related to a specific workflow instance
  • terminate_workflow: Terminate or stop a particular instance of a workflow
  1. from dapr.ext.workflow import WorkflowRuntime, DaprWorkflowContext, WorkflowActivityContext
  2. from dapr.clients import DaprClient
  3. # Sane parameters
  4. instanceId = "exampleInstanceID"
  5. workflowComponent = "dapr"
  6. workflowName = "hello_world_wf"
  7. eventName = "event1"
  8. eventData = "eventData"
  9. # Start the workflow
  10. start_resp = d.start_workflow(instance_id=instanceId, workflow_component=workflowComponent,
  11. workflow_name=workflowName, input=inputData, workflow_options=workflowOptions)
  12. # Get info on the workflow
  13. getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
  14. # Pause the workflow
  15. d.pause_workflow(instance_id=instanceId, workflow_component=workflowComponent)
  16. # Resume the workflow
  17. d.resume_workflow(instance_id=instanceId, workflow_component=workflowComponent)
  18. # Raise an event on the workflow.
  19. d.raise_workflow_event(instance_id=instanceId, workflow_component=workflowComponent,
  20. event_name=eventName, event_data=eventData)
  21. # Purge the workflow
  22. d.purge_workflow(instance_id=instanceId, workflow_component=workflowComponent)
  23. # Terminate the workflow
  24. d.terminate_workflow(instance_id=instanceId, workflow_component=workflowComponent)

Manage your workflow within your code. In the workflow example from the Author a workflow guide, the workflow is registered in the code using the following APIs:

  • client.workflow.start: Start an instance of a workflow
  • client.workflow.get: Get information on the status of the workflow
  • client.workflow.pause: Pauses or suspends a workflow instance that can later be resumed
  • client.workflow.resume: Resumes a paused workflow instance
  • client.workflow.purge: Removes all metadata related to a specific workflow instance
  • client.workflow.terminate: Terminate or stop a particular instance of a workflow
  1. import { DaprClient } from "@dapr/dapr";
  2. async function printWorkflowStatus(client: DaprClient, instanceId: string) {
  3. const workflow = await client.workflow.get(instanceId);
  4. console.log(
  5. `Workflow ${workflow.workflowName}, created at ${workflow.createdAt.toUTCString()}, has status ${
  6. workflow.runtimeStatus
  7. }`,
  8. );
  9. console.log(`Additional properties: ${JSON.stringify(workflow.properties)}`);
  10. console.log("--------------------------------------------------\n\n");
  11. }
  12. async function start() {
  13. const client = new DaprClient();
  14. // Start a new workflow instance
  15. const instanceId = await client.workflow.start("OrderProcessingWorkflow", {
  16. Name: "Paperclips",
  17. TotalCost: 99.95,
  18. Quantity: 4,
  19. });
  20. console.log(`Started workflow instance ${instanceId}`);
  21. await printWorkflowStatus(client, instanceId);
  22. // Pause a workflow instance
  23. await client.workflow.pause(instanceId);
  24. console.log(`Paused workflow instance ${instanceId}`);
  25. await printWorkflowStatus(client, instanceId);
  26. // Resume a workflow instance
  27. await client.workflow.resume(instanceId);
  28. console.log(`Resumed workflow instance ${instanceId}`);
  29. await printWorkflowStatus(client, instanceId);
  30. // Terminate a workflow instance
  31. await client.workflow.terminate(instanceId);
  32. console.log(`Terminated workflow instance ${instanceId}`);
  33. await printWorkflowStatus(client, instanceId);
  34. // Wait for the workflow to complete, 30 seconds!
  35. await new Promise((resolve) => setTimeout(resolve, 30000));
  36. await printWorkflowStatus(client, instanceId);
  37. // Purge a workflow instance
  38. await client.workflow.purge(instanceId);
  39. console.log(`Purged workflow instance ${instanceId}`);
  40. // This will throw an error because the workflow instance no longer exists.
  41. await printWorkflowStatus(client, instanceId);
  42. }
  43. start().catch((e) => {
  44. console.error(e);
  45. process.exit(1);
  46. });

Manage your workflow within your code. In the OrderProcessingWorkflow example from the Author a workflow guide, the workflow is registered in the code. You can now start, terminate, and get information about a running workflow:

  1. string orderId = "exampleOrderId";
  2. string workflowComponent = "dapr";
  3. string workflowName = "OrderProcessingWorkflow";
  4. OrderPayload input = new OrderPayload("Paperclips", 99.95);
  5. Dictionary<string, string> workflowOptions; // This is an optional parameter
  6. // Start the workflow. This returns back a "StartWorkflowResponse" which contains the instance ID for the particular workflow instance.
  7. StartWorkflowResponse startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions);
  8. // Get information on the workflow. This response contains information such as the status of the workflow, when it started, and more!
  9. GetWorkflowResponse getResponse = await daprClient.GetWorkflowAsync(orderId, workflowComponent, eventName);
  10. // Terminate the workflow
  11. await daprClient.TerminateWorkflowAsync(orderId, workflowComponent);
  12. // Raise an event (an incoming purchase order) that your workflow will wait for. This returns the item waiting to be purchased.
  13. await daprClient.RaiseWorkflowEventAsync(orderId, workflowComponent, workflowName, input);
  14. // Pause
  15. await daprClient.PauseWorkflowAsync(orderId, workflowComponent);
  16. // Resume
  17. await daprClient.ResumeWorkflowAsync(orderId, workflowComponent);
  18. // Purge the workflow, removing all inbox and history information from associated instance
  19. await daprClient.PurgeWorkflowAsync(orderId, workflowComponent);

Manage your workflow within your code. In the workflow example from the Java SDK, the workflow is registered in the code using the following APIs:

  • scheduleNewWorkflow: Starts a new workflow instance
  • getInstanceState: Get information on the status of the workflow
  • waitForInstanceStart: Pauses or suspends a workflow instance that can later be resumed
  • raiseEvent: Raises events/tasks for the running workflow instance
  • waitForInstanceCompletion: Waits for the workflow to complete its tasks
  • purgeInstance: Removes all metadata related to a specific workflow instance
  • terminateWorkflow: Terminates the workflow
  • purgeInstance: Removes all metadata related to a specific workflow
  1. package io.dapr.examples.workflows;
  2. import io.dapr.workflows.client.DaprWorkflowClient;
  3. import io.dapr.workflows.client.WorkflowInstanceStatus;
  4. // ...
  5. public class DemoWorkflowClient {
  6. // ...
  7. public static void main(String[] args) throws InterruptedException {
  8. DaprWorkflowClient client = new DaprWorkflowClient();
  9. try (client) {
  10. // Start a workflow
  11. String instanceId = client.scheduleNewWorkflow(DemoWorkflow.class, "input data");
  12. // Get status information on the workflow
  13. WorkflowInstanceStatus workflowMetadata = client.getInstanceState(instanceId, true);
  14. // Wait or pause for the workflow instance start
  15. try {
  16. WorkflowInstanceStatus waitForInstanceStartResult =
  17. client.waitForInstanceStart(instanceId, Duration.ofSeconds(60), true);
  18. }
  19. // Raise an event for the workflow; you can raise several events in parallel
  20. client.raiseEvent(instanceId, "TestEvent", "TestEventPayload");
  21. client.raiseEvent(instanceId, "event1", "TestEvent 1 Payload");
  22. client.raiseEvent(instanceId, "event2", "TestEvent 2 Payload");
  23. client.raiseEvent(instanceId, "event3", "TestEvent 3 Payload");
  24. // Wait for workflow to complete running through tasks
  25. try {
  26. WorkflowInstanceStatus waitForInstanceCompletionResult =
  27. client.waitForInstanceCompletion(instanceId, Duration.ofSeconds(60), true);
  28. }
  29. // Purge the workflow instance, removing all metadata associated with it
  30. boolean purgeResult = client.purgeInstance(instanceId);
  31. // Terminate the workflow instance
  32. client.terminateWorkflow(instanceToTerminateId, null);
  33. System.exit(0);
  34. }
  35. }

Manage your workflow within your code. In the workflow example from the Go SDK, the workflow is registered in the code using the following APIs:

  • StartWorkflow: Starts a new workflow instance
  • GetWorkflow: Get information on the status of the workflow
  • PauseWorkflow: Pauses or suspends a workflow instance that can later be resumed
  • RaiseEventWorkflow: Raises events/tasks for the running workflow instance
  • ResumeWorkflow: Waits for the workflow to complete its tasks
  • PurgeWorkflow: Removes all metadata related to a specific workflow instance
  • TerminateWorkflow: Terminates the workflow
  1. // Start workflow
  2. type StartWorkflowRequest struct {
  3. InstanceID string // Optional instance identifier
  4. WorkflowComponent string
  5. WorkflowName string
  6. Options map[string]string // Optional metadata
  7. Input any // Optional input
  8. SendRawInput bool // Set to True in order to disable serialization on the input
  9. }
  10. type StartWorkflowResponse struct {
  11. InstanceID string
  12. }
  13. // Get the workflow status
  14. type GetWorkflowRequest struct {
  15. InstanceID string
  16. WorkflowComponent string
  17. }
  18. type GetWorkflowResponse struct {
  19. InstanceID string
  20. WorkflowName string
  21. CreatedAt time.Time
  22. LastUpdatedAt time.Time
  23. RuntimeStatus string
  24. Properties map[string]string
  25. }
  26. // Purge workflow
  27. type PurgeWorkflowRequest struct {
  28. InstanceID string
  29. WorkflowComponent string
  30. }
  31. // Terminate workflow
  32. type TerminateWorkflowRequest struct {
  33. InstanceID string
  34. WorkflowComponent string
  35. }
  36. // Pause workflow
  37. type PauseWorkflowRequest struct {
  38. InstanceID string
  39. WorkflowComponent string
  40. }
  41. // Resume workflow
  42. type ResumeWorkflowRequest struct {
  43. InstanceID string
  44. WorkflowComponent string
  45. }
  46. // Raise an event for the running workflow
  47. type RaiseEventWorkflowRequest struct {
  48. InstanceID string
  49. WorkflowComponent string
  50. EventName string
  51. EventData any
  52. SendRawData bool // Set to True in order to disable serialization on the data
  53. }

Manage your workflow using HTTP calls. The example below plugs in the properties from the Author a workflow example with a random instance ID number.

Start workflow

To start your workflow with an ID 12345678, run:

  1. POST http://localhost:3500/v1.0-beta1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678

Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.

Terminate workflow

To terminate your workflow with an ID 12345678, run:

  1. POST http://localhost:3500/v1.0-beta1/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.

  1. POST http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<instanceID>/raiseEvent/<eventName>

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:

  1. POST http://localhost:3500/v1.0-beta1/workflows/dapr/12345678/pause

To resume a workflow with an ID 12345678, run:

  1. POST http://localhost:3500/v1.0-beta1/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.

  1. POST http://localhost:3500/v1.0-beta1/workflows/dapr/12345678/purge

Get information about a workflow

To fetch workflow information (outputs and inputs) with an ID 12345678, run:

  1. GET http://localhost:3500/v1.0-beta1/workflows/dapr/12345678

Learn more about these HTTP calls in the workflow API reference guide.

Next steps

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)