dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3372 from cgillum/api-engine-changes 

[Workflow] Actor type and HTTP API updates
This commit is contained in:
Hannah Hunter 2023-05-03 15:54:49 -04:00 committed by GitHub
parent cfc0749aa1 0ef572f3eb
commit 189711d97a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 35 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
View File

@ -45,9 +45,11 @@ Manage your workflow using HTTP calls. The example below plugs in the properties
To start your workflow with an ID `12345678`, run: To start your workflow with an ID `12345678`, run:
```bash ```bash
POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/12345678/start POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678
``` ```
Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
### Terminate workflow ### Terminate workflow
To terminate your workflow with an ID `12345678`, run: To terminate your workflow with an ID `12345678`, run:
@ -61,7 +63,7 @@ POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/terminate
To fetch workflow information (outputs and inputs) with an ID `12345678`, run: To fetch workflow information (outputs and inputs) with an ID `12345678`, run:
```bash ```bash
GET http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/12345678 GET http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678
``` ```
Learn more about these HTTP calls in the [workflow API reference guide]({{< ref workflow_api.md >}}). Learn more about these HTTP calls in the [workflow API reference guide]({{< ref workflow_api.md >}}).

20
daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md
View File

@ -52,8 +52,10 @@ Each workflow instance managed by the engine is represented as one or more spans
There are two types of actors that are internally registered within the Dapr sidecar in support of the workflow engine: There are two types of actors that are internally registered within the Dapr sidecar in support of the workflow engine:
- `dapr.internal.wfengine.workflow` - `dapr.internal.{namespace}.{appID}.workflow`
- `dapr.internal.wfengine.activity` - `dapr.internal.{namespace}.{appID}.activity`
The `{namespace}` value is the Dapr namespace and defaults to `default` if no namespace is configured. The `{appID}` value is the app's ID. For example, if you have a workflow app named "wfapp", then the type of the workflow actor would be `dapr.internal.default.wfapp.workflow` and the type of the activity actor would be `dapr.internal.default.wfapp.activity`.
The following diagram demonstrates how internal workflow actors operate in a Kubernetes scenario: The following diagram demonstrates how internal workflow actors operate in a Kubernetes scenario:
@ -61,11 +63,13 @@ The following diagram demonstrates how internal workflow actors operate in a Kub
Just like user-defined actors, internal workflow actors are distributed across the cluster by the actor placement service. They also maintain their own state and make use of reminders. However, unlike actors that live in application code, these _internal_ actors are embedded into the Dapr sidecar. Application code is completely unaware that these actors exist. Just like user-defined actors, internal workflow actors are distributed across the cluster by the actor placement service. They also maintain their own state and make use of reminders. However, unlike actors that live in application code, these _internal_ actors are embedded into the Dapr sidecar. Application code is completely unaware that these actors exist.
There are two types of actors registered by the Dapr sidecar for workflow: the _workflow_ actor and the _activity_ actor. The next sections will go into more details on each. {{% alert title="Note" color="primary" %}}
The internal workflow actor types are only registered after an app has registered a workflow using a Dapr Workflow SDK. If an app never registers a workflow, then the internal workflow actors are never registered.
{{% /alert %}}
### Workflow actors ### Workflow actors
A new instance of the `dapr.internal.wfengine.workflow` actor is activated for every workflow instance that gets created. The ID of the _workflow_ actor is the ID of the workflow. This internal actor stores the state of the workflow as it progresses and determines the node on which the workflow code executes via the actor placement service. Workflow actors are responsible for managing the state and placement of all workflows running in the app. A new instance of the workflow actor is activated for every workflow instance that gets created. The ID of the workflow actor is the ID of the workflow. This internal actor stores the state of the workflow as it progresses and determines the node on which the workflow code executes via the actor placement service.
Each workflow actor saves its state using the following keys in the configured state store: Each workflow actor saves its state using the following keys in the configured state store:
@ -94,17 +98,13 @@ To summarize:
### Activity actors ### Activity actors
A new instance of the `dapr.internal.wfengine.activity` actor is activated for every activity task that gets scheduled by a workflow. The ID of the _activity_ actor is the ID of the workflow combined with a sequence number (sequence numbers start with 0). For example, if a workflow has an ID of `876bf371` and is the third activity to be scheduled by the workflow, it's ID will be `876bf371#2` where `2` is the sequence number. Activity actors are responsible for managing the state and placement of all workflow activity invocations. A new instance of the activity actor is activated for every activity task that gets scheduled by a workflow. The ID of the activity actor is the ID of the workflow combined with a sequence number (sequence numbers start with 0). For example, if a workflow has an ID of `876bf371` and is the third activity to be scheduled by the workflow, it's ID will be `876bf371::2` where `2` is the sequence number.
Each activity actor stores a single key into the state store: Each activity actor stores a single key into the state store:
| Key | Description | | Key | Description |
| --- | ----------- | | --- | ----------- |
| `activityreq-N` | The key contains the activity invocation payload, which includes the serialized activity input data. The `N` value is a 64-bit unsigned integer that represents the _generation_ of the workflow, a concept which is outside the scope of this documentation. | | `activityState` | The key contains the activity invocation payload, which includes the serialized activity input data. This key is deleted automatically after the activity invocation has completed. |
{{% alert title="Warning" color="warning" %}}
In the [Alpha release of the Dapr Workflow engine]({{< ref support-preview-features.md >}}), activity actor state will remain in the state store even after the activity task has completed. Scheduling a large number of workflow activities could result in unbounded storage usage. In a future release, data retention policies will be introduced that can automatically purge the state store of completed activity state.
{{% /alert %}}
The following diagram illustrates the typical lifecycle of an activity actor. The following diagram illustrates the typical lifecycle of an activity actor.

66
daprdocs/content/en/reference/api/workflow_api.md
View File

@ -10,29 +10,25 @@ Dapr provides users with the ability to interact with workflows and comes with a
## Start workflow request ## Start workflow request
Start a workflow instance with the given name and instance ID. Start a workflow instance with the given name and optionally, an instance ID.
```bash ```bash
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>/start POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/start[?instanceId=<instanceId>]
``` ```
Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
### URL parameters ### URL parameters
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
`workflowComponentName` | Current default is `dapr` for Dapr Workflows `workflowComponentName` | Current default is `dapr` for Dapr Workflows
`workflowName` | Identify the workflow type `workflowName` | Identify the workflow type
`instanceId` | Unique value created for each run of a specific workflow `instanceId` | (Optional) Unique value created for each run of a specific workflow
### Request content ### Request content
In the request you can pass along relevant input information that will be passed to the workflow: Any request content will be passed to the workflow as input. The Dapr API passes the content as-is without attempting to interpret it.
```json
{
"input": // argument(s) to pass to the workflow which can be any valid JSON data type (such as objects, strings, numbers, arrays, etc.)
}
```
### HTTP response codes ### HTTP response codes
@ -48,9 +44,7 @@ The API call will provide a response similar to this:
```json ```json
{ {
  "WFInfo": { "instanceID": "12345678"
    "instance_id": "SampleWorkflow"
  }
} }
``` ```
@ -59,7 +53,7 @@ The API call will provide a response similar to this:
Terminate a running workflow instance with the given name and instance ID. Terminate a running workflow instance with the given name and instance ID.
```bash ```bash
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/terminate POST http://localhost:3500/v1.0-alpha1/workflows/<instanceId>/terminate
``` ```
### URL parameters ### URL parameters
@ -67,7 +61,6 @@ POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instan
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
`workflowComponentName` | Current default is `dapr` for Dapr Workflows `workflowComponentName` | Current default is `dapr` for Dapr Workflows
`workflowName` | Identify the workflow type
`instanceId` | Unique value created for each run of a specific workflow `instanceId` | Unique value created for each run of a specific workflow
### HTTP response codes ### HTTP response codes
@ -80,22 +73,14 @@ Code | Description
### Response content ### Response content
The API call will provide a response similar to this: This API does not return any content.
```bash
HTTP/1.1 202 Accepted
Server: fasthttp
Date: Thu, 12 Jan 2023 21:31:16 GMT
Traceparent: 00-e3dedffedbeb9efbde9fbed3f8e2d8-5f38960d43d24e98-01
Connection: close 
```
### Get workflow request ### Get workflow request
Get information about a given workflow instance. Get information about a given workflow instance.
```bash ```bash
GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId> GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>
``` ```
### URL parameters ### URL parameters
@ -103,39 +88,30 @@ GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflo
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
`workflowComponentName` | Current default is `dapr` for Dapr Workflows `workflowComponentName` | Current default is `dapr` for Dapr Workflows
`workflowName` | Identify the workflow type
`instanceId` | Unique value created for each run of a specific workflow `instanceId` | Unique value created for each run of a specific workflow
### HTTP response codes ### HTTP response codes
Code | Description Code | Description
---- | ----------- ---- | -----------
`202` | Accepted `200` | OK
`400` | Request was malformed `400` | Request was malformed
`500` | Request formatted correctly, error in dapr code or underlying component `500` | Request formatted correctly, error in dapr code or underlying component
### Response content ### Response content
The API call will provide a response similar to this: The API call will provide a JSON response similar to this:
```bash
HTTP/1.1 202 Accepted
Server: fasthttp
Date: Thu, 12 Jan 2023 21:31:16 GMT
Content-Type: application/json
Content-Length: 139
Traceparent: 00-e3dedffedbeb9efbde9fbed3f8e2d8-5f38960d43d24e98-01
Connection: close 
```json
{ {
  "WFInfo": {   "createdAt": "2023-01-12T21:31:13Z",
    "instance_id": "SampleWorkflow"   "instanceID": "12345678",
  }, "lastUpdatedAt": "2023-01-12T21:31:13Z",
  "start_time": "2023-01-12T21:31:13Z",   "properties": {
  "metadata": { "property1": "value1",
    "status": "Running", "property2": "value2",
    "task_queue": "WorkflowSampleQueue" },
  } "runtimeStatus": "RUNNING",
} }
``` ```