You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md
+24-35Lines changed: 24 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,15 +6,17 @@ weight: 2000
6
6
description: "Learn more about the Dapr Workflow features and concepts"
7
7
---
8
8
9
-
Now that you've learned about the [workflow building block]({{% ref workflow-overview.md %}}) at a high level, let's deep dive into the features and concepts included with the Dapr Workflow engine and SDKs. Dapr Workflow exposes several core features and concepts which are common across all supported languages.
9
+
Now that you've learned about the [workflow building block]({{% ref workflow-overview.md %}}) at a high level, let's deep dive into the features and concepts included with the Dapr Workflow engine and SDKs. Dapr Workflow exposes several core features and concepts which are common across all supported languages.
10
10
11
11
{{% alert title="Note" color="primary" %}}
12
12
For more information on how workflow state is managed, see the [workflow architecture guide]({{% ref workflow-architecture.md %}}).
13
13
{{% /alert %}}
14
14
15
15
## Workflows
16
16
17
-
Dapr Workflows are functions you write that define a series of tasks to be executed in a particular order. The Dapr Workflow engine takes care of scheduling and execution of the tasks, including managing failures and retries. If the app hosting your workflows is scaled out across multiple machines, the workflow engine may also load balance the execution of workflows and their tasks across multiple machines.
17
+
Dapr Workflows are functions you write that define a series of tasks to be executed in a particular order.
18
+
The Dapr Workflow engine takes care of scheduling and execution of the tasks, including managing failures and retries.
19
+
If the app hosting your workflows is scaled out across multiple machines, the workflow engine load balances the execution of workflows and their tasks across multiple machines.
18
20
19
21
There are several different kinds of tasks that a workflow can schedule, including
20
22
-[Activities]({{% ref "workflow-features-concepts.md#workflow-activities" %}}) for executing custom logic
@@ -32,7 +34,7 @@ Only one workflow instance with a given ID can exist at any given time. However,
32
34
33
35
Dapr Workflows maintain their execution state by using a technique known as [event sourcing](https://learn.microsoft.com/azure/architecture/patterns/event-sourcing). Instead of storing the current state of a workflow as a snapshot, the workflow engine manages an append-only log of history events that describe the various steps that a workflow has taken. When using the workflow SDK, these history events are stored automatically whenever the workflow "awaits" for the result of a scheduled task.
34
36
35
-
When a workflow "awaits" a scheduled task, it unloads itself from memory until the task completes. Once the task completes, the workflow engine schedules the workflow function to run again. This second workflow function execution is known as a _replay_.
37
+
When a workflow "awaits" a scheduled task, it unloads itself from memory until the task completes. Once the task completes, the workflow engine schedules the workflow function to run again. This second workflow function execution is known as a _replay_.
36
38
37
39
When a workflow function is replayed, it runs again from the beginning. However, when it encounters a task that already completed, instead of scheduling that task again, the workflow engine:
38
40
@@ -57,16 +59,16 @@ As discussed in the [workflow replay]({{% ref "#workflow-replay" %}}) section, w
57
59
58
60
You can use the following two techniques to write workflows that may need to schedule extreme numbers of tasks:
59
61
60
-
1.**Use the _continue-as-new_ API**:
62
+
1.**Use the _continue-as-new_ API**:
61
63
Each workflow SDK exposes a _continue-as-new_ API that workflows can invoke to restart themselves with a new input and history. The _continue-as-new_ API is especially ideal for implementing "eternal workflows", like monitoring agents, which would otherwise be implemented using a `while (true)`-like construct. Using _continue-as-new_ is a great way to keep the workflow history size small.
62
-
64
+
63
65
> The _continue-as-new_ API truncates the existing history, replacing it with a new history.
64
66
65
-
1.**Use child workflows**:
67
+
1.**Use child workflows**:
66
68
Each workflow SDK exposes an API for creating child workflows. A child workflow behaves like any other workflow, except that it's scheduled by a parent workflow. Child workflows have:
67
-
- Their own history
68
-
- The benefit of distributing workflow function execution across multiple machines.
69
-
69
+
- Their own history
70
+
- The benefit of distributing workflow function execution across multiple machines.
71
+
70
72
If a workflow needs to schedule thousands of tasks or more, it's recommended that those tasks be distributed across child workflows so that no single workflow's history size grows too large.
71
73
72
74
### Updating workflow code
@@ -145,18 +147,6 @@ Workflows can also wait for multiple external event signals of the same name, in
145
147
146
148
Learn more about [external system interaction.]({{% ref "workflow-patterns.md#external-system-interaction" %}})
147
149
148
-
## Workflow backend
149
-
150
-
Dapr Workflow relies on the Durable Task Framework for Go (a.k.a. [durabletask-go](https://github.com/dapr/durabletask-go)) as the core engine for executing workflows. This engine is designed to support multiple backend implementations. For example, the [durabletask-go](https://github.com/dapr/durabletask-go) repo includes a SQLite implementation and the Dapr repo includes an Actors implementation.
151
-
152
-
By default, Dapr Workflow supports the Actors backend, which is stable and scalable. However, you can choose a different backend supported in Dapr Workflow. For example, [SQLite](https://github.com/dapr/durabletask-go/tree/main/backend/sqlite)(TBD future release) could be an option for backend for local development and testing.
153
-
154
-
The backend implementation is largely decoupled from the workflow core engine or the programming model that you see. The backend primarily impacts:
155
-
- How workflow state is stored
156
-
- How workflow execution is coordinated across replicas
157
-
158
-
In that sense, it's similar to Dapr's state store abstraction, except designed specifically for workflow. All APIs and programming model features are the same, regardless of which backend is used.
159
-
160
150
## Purging
161
151
162
152
Workflow state can be purged from a state store, purging all its history and removing all metadata related to a specific workflow instance. The purge capability is used for workflows that have run to a `COMPLETED`, `FAILED`, or `TERMINATED` state.
@@ -165,11 +155,11 @@ Learn more in [the workflow API reference guide]({{% ref workflow_api.md %}}).
165
155
166
156
## Limitations
167
157
168
-
### Workflow determinism and code restraints
158
+
### Workflow determinism and code restraints
169
159
170
160
To take advantage of the workflow replay technique, your workflow code needs to be deterministic. For your workflow code to be deterministic, you may need to work around some limitations.
171
161
172
-
#### Workflow functions must call deterministic APIs.
162
+
#### Workflow functions must call deterministic APIs.
173
163
APIs that generate random numbers, random UUIDs, or the current date are _non-deterministic_. To work around this limitation, you can:
174
164
- Use these APIs in activity functions, or
175
165
- (Preferred) Use built-in equivalent APIs offered by the SDK. For example, each authoring SDK provides an API for retrieving the current time in a deterministic manner.
#### Workflow functions must only interact _indirectly_ with external state.
273
-
External data includes any data that isn't stored in the workflow state. Workflows must not interact with global variables, environment variables, the file system, or make network calls.
274
-
262
+
#### Workflow functions must only interact _indirectly_ with external state.
263
+
External data includes any data that isn't stored in the workflow state. Workflows must not interact with global variables, environment variables, the file system, or make network calls.
264
+
275
265
Instead, workflows should interact with external state _indirectly_ using workflow inputs, activity tasks, and through external event handling.
#### Workflow functions must execute only on the workflow dispatch thread.
370
+
#### Workflow functions must execute only on the workflow dispatch thread.
381
371
The implementation of each language SDK requires that all workflow function operations operate on the same thread (goroutine, etc.) that the function was scheduled on. Workflow functions must never:
382
372
- Schedule background threads, or
383
-
- Use APIs that schedule a callback function to run on another thread.
384
-
373
+
- Use APIs that schedule a callback function to run on another thread.
374
+
385
375
Failure to follow this rule could result in undefined behavior. Any background processing should instead be delegated to activity tasks, which can be scheduled to run serially or concurrently.
386
376
387
377
For example, instead of this:
@@ -478,19 +468,18 @@ task.Await(nil)
478
468
479
469
Make sure updates you make to the workflow code maintain its determinism. A couple examples of code updates that can break workflow determinism:
480
470
481
-
-**Changing workflow function signatures**:
482
-
Changing the name, input, or output of a workflow or activity function is considered a breaking change and must be avoided.
471
+
-**Changing workflow function signatures**:
472
+
Changing the name, input, or output of a workflow or activity function is considered a breaking change and must be avoided.
483
473
484
-
-**Changing the number or order of workflow tasks**:
474
+
-**Changing the number or order of workflow tasks**:
485
475
Changing the number or order of workflow tasks causes a workflow instance's history to no longer match the code and may result in runtime errors or other unexpected behavior.
486
476
487
477
To work around these constraints:
488
478
489
-
- Instead of updating existing workflow code, leave the existing workflow code as-is and create new workflow definitions that include the updates.
490
-
- Upstream code that creates workflows should only be updated to create instances of the new workflows.
479
+
- Instead of updating existing workflow code, leave the existing workflow code as-is and create new workflow definitions that include the updates.
480
+
- Upstream code that creates workflows should only be updated to create instances of the new workflows.
491
481
- Leave the old code around to ensure that existing workflow instances can continue to run without interruption. If and when it's known that all instances of the old workflow logic have completed, then the old workflow code can be safely deleted.
Copy file name to clipboardExpand all lines: daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md
+15-7Lines changed: 15 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,14 +6,15 @@ weight: 1000
6
6
description: "Overview of Dapr Workflow"
7
7
---
8
8
9
-
Dapr workflow makes it easy for developers to write business logic and integrations in a reliable way. Since Dapr workflows are stateful, they support long-running and fault-tolerant applications, ideal for orchestrating microservices. Dapr workflow works seamlessly with other Dapr building blocks, such as service invocation, pub/sub, state management, and bindings.
9
+
Dapr workflow makes it easy for developers to write business logic and integrations in a reliable way.
10
+
Since Dapr workflows are stateful, they support long-running and fault-tolerant applications, ideal for orchestrating microservices.
11
+
Dapr workflow works seamlessly with other Dapr building blocks, such as service invocation, pub/sub, state management, and bindings.
10
12
11
13
The durable, resilient Dapr Workflow capability:
12
14
13
15
- Offers a built-in workflow runtime for driving Dapr Workflow execution.
14
16
- Provides SDKs for authoring workflows in code, using any language.
15
17
- Provides HTTP and gRPC APIs for managing workflows (start, query, pause/resume, raise event, terminate, purge).
16
-
- Integrates with any other workflow runtime via workflow components.
17
18
18
19
<imgsrc="/images/workflow-overview/workflow-overview.png"width=800alt="Diagram showing basics of Dapr Workflow">
19
20
@@ -28,16 +29,20 @@ Some example scenarios that Dapr Workflow can perform are:
28
29
29
30
### Workflows and activities
30
31
31
-
With Dapr Workflow, you can write activities and then orchestrate those activities in a workflow. Workflow activities are:
32
+
With Dapr Workflow, you can write activities and then orchestrate those activities in a workflow.
33
+
Workflow activities are:
32
34
33
35
- The basic unit of work in a workflow
34
36
- Used for calling other (Dapr) services, interacting with state stores, and pub/sub brokers.
37
+
- Used for calling external third party services.
35
38
36
39
[Learn more about workflow activities.]({{% ref "workflow-features-concepts.md##workflow-activities" %}})
37
40
38
41
### Child workflows
39
42
40
-
In addition to activities, you can write workflows to schedule other workflows as child workflows. A child workflow has its own instance ID, history, and status that is independent of the parent workflow that started it, except for the fact that terminating the parent workflow terminates all of the child workflows created by it. Child workflow also supports automatic retry policies.
43
+
In addition to activities, you can write workflows to schedule other workflows as child workflows.
44
+
A child workflow has its own instance ID, history, and status that is independent of the parent workflow that started it, except for the fact that terminating the parent workflow terminates all of the child workflows created by it.
45
+
Child workflow also supports automatic retry policies.
41
46
42
47
[Learn more about child workflows.]({{% ref "workflow-features-concepts.md#child-workflows" %}})
43
48
@@ -49,7 +54,8 @@ Same as Dapr actors, you can schedule reminder-like durable delays for any time
49
54
50
55
### Workflow HTTP calls to manage a workflow
51
56
52
-
When you create an application with workflow code and run it with Dapr, you can call specific workflows that reside in the application. Each individual workflow can be:
57
+
When you create an application with workflow code and run it with Dapr, you can call specific workflows that reside in the application.
58
+
Each individual workflow can be:
53
59
54
60
- Started or terminated through a POST request
55
61
- Triggered to deliver a named event through a POST request
@@ -61,13 +67,15 @@ When you create an application with workflow code and run it with Dapr, you can
61
67
62
68
## Workflow patterns
63
69
64
-
Dapr Workflow simplifies complex, stateful coordination requirements in microservice architectures. The following sections describe several application patterns that can benefit from Dapr Workflow.
70
+
Dapr Workflow simplifies complex, stateful coordination requirements in microservice architectures.
71
+
The following sections describe several application patterns that can benefit from Dapr Workflow.
65
72
66
73
Learn more about [different types of workflow patterns]({{% ref workflow-patterns.md %}})
67
74
68
75
## Workflow SDKs
69
76
70
-
The Dapr Workflow _authoring SDKs_ are language-specific SDKs that contain types and functions to implement workflow logic. The workflow logic lives in your application and is orchestrated by the Dapr Workflow engine running in the Dapr sidecar via a gRPC stream.
77
+
The Dapr Workflow _authoring SDKs_ are language-specific SDKs that contain types and functions to implement workflow logic.
78
+
The workflow logic lives in your application and is orchestrated by the Dapr Workflow engine running in the Dapr sidecar via a gRPC stream.
0 commit comments