Workflow API reference

Detailed documentation on the workflow API

Note

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

Dapr provides users with the ability to interact with workflows and comes with a built-in dapr component.

Start workflow request

Start a workflow instance with the given name and optionally, an instance ID.

  1. POST http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<workflowName>/start[?instanceID=<instanceID>]

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

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
workflowNameIdentify the workflow type
instanceID(Optional) Unique value created for each run of a specific workflow

Request content

Any request content will be passed to the workflow as input. The Dapr API passes the content as-is without attempting to interpret it.

HTTP response codes

CodeDescription
202Accepted
400Request was malformed
500Request formatted correctly, error in dapr code or underlying component

Response content

The API call will provide a response similar to this:

  1. {
  2. "instanceID": "12345678"
  3. }

Terminate workflow request

Terminate a running workflow instance with the given name and instance ID.

  1. POST http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<instanceId>/terminate

Note

Terminating a workflow terminates all of the child workflows created by the workflow instance.

Terminating a workflow has no effect on any in-flight activity executions that were started by the terminated instance.

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
instanceIdUnique value created for each run of a specific workflow

HTTP response codes

CodeDescription
202Accepted
400Request was malformed
500Request formatted correctly, error in dapr code or underlying component

Response content

This API does not return any content.

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.

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

Note

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.

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
instanceIdUnique value created for each run of a specific workflow
eventNameThe name of the event to raise

HTTP response codes

CodeDescription
202Accepted
400Request was malformed
500Request formatted correctly, error in dapr code or underlying component

Response content

None.

Pause workflow request

Pause a running workflow instance.

  1. POST http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<instanceId>/pause

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
instanceIdUnique value created for each run of a specific workflow

HTTP response codes

CodeDescription
202Accepted
400Request was malformed
500Error in Dapr code or underlying component

Response content

None.

Resume workflow request

Resume a paused workflow instance.

  1. POST http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<instanceId>/resume

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
instanceIdUnique value created for each run of a specific workflow

HTTP response codes

CodeDescription
202Accepted
400Request was malformed
500Error 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.

  1. POST http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<instanceId>/purge

Note

Only COMPLETED, FAILED, or TERMINATED workflows can be purged.

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
instanceIdUnique value created for each run of a specific workflow

HTTP response codes

CodeDescription
202Accepted
400Request was malformed
500Error in Dapr code or underlying component

Response content

None.

Get workflow request

Get information about a given workflow instance.

  1. GET http://localhost:3500/v1.0-beta1/workflows/<workflowComponentName>/<instanceId>

URL parameters

ParameterDescription
workflowComponentNameUse dapr for Dapr Workflows
instanceIdUnique value created for each run of a specific workflow

HTTP response codes

CodeDescription
200OK
400Request was malformed
500Request formatted correctly, error in dapr code or underlying component

Response content

The API call will provide a JSON response similar to this:

  1. {
  2. "createdAt": "2023-01-12T21:31:13Z",
  3. "instanceID": "12345678",
  4. "lastUpdatedAt": "2023-01-12T21:31:13Z",
  5. "properties": {
  6. "property1": "value1",
  7. "property2": "value2",
  8. },
  9. "runtimeStatus": "RUNNING",
  10. }
ParameterDescription
runtimeStatusThe status of the workflow instance. Values include: “RUNNING”, “COMPLETED”, “CONTINUED_AS_NEW”, “FAILED”, “CANCELED”, “TERMINATED”, “PENDING”, “SUSPENDED”

Component format

A Dapr workflow.yaml component file has the following structure:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: <NAME>
  5. spec:
  6. type: workflow.<TYPE>
  7. version: v1.0-alpha1
  8. metadata:
  9. - name: <NAME>
  10. value: <VALUE>
SettingDescription
metadata.nameThe name of the workflow component.
spec/metadataAdditional metadata parameters specified by workflow component

However, Dapr comes with a built-in dapr workflow component that is built on Dapr Actors. No component file is required to use the built-in Dapr workflow component.

Next Steps

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