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
Workflows, a new product for building reliable, multi-step workflows using Cloudflare Workers, is now in public beta. The public beta is available to any user with a [free or paid Workers plan](/workers/platform/pricing/).
12
12
13
-
A Workflow allows you to define multiple, independent steps that encapsulate errors, automatically retry, persist state, and can run for seconds, minutes, hours or even days. A Workflow can be useful for post-processing data from R2 buckets before querying it, automating a [Workers AI RAG pipeline](/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/), or managing user signup flows and lifecycle emails.
13
+
A Workflow allows you to define multiple, independent steps that encapsulate errors, automatically retry, persist state, and can run for seconds, minutes, hours or even days. A Workflow can be useful for post-processing data from R2 buckets before querying it, automating a Workers AI RAG pipeline, or managing user signup flows and lifecycle emails.
14
14
15
-
You can learn more about Workflows in [our announcement blog], or start building in our [get started guide].
15
+
You can learn more about Workflows in [our announcement blog](https://blog.cloudflare.com/building-workflows-durable-execution-on-workers/), or start building in our [get started guide](/workflows/get-started/guide/).
This guide details the Workflows API within Cloudflare Workers, including methods, types and usage examples.
12
12
13
-
TODO
13
+
## WorkflowEntrypoint
14
14
15
-
## Interact with Workflows
15
+
The `WorkflowEntrypoint` class is the core element of a Workflow definition. A Workflow must extend this class and define a `run` method with at least one `step` call to be considered a valid Workflow.
*`event` - the event passed to the Workflow, including an optional `payload` containing data (parameters)
28
+
*`step` - the `WorkflowStep` type that provides the step methods for your Workflow
25
29
26
-
TODO
30
+
The `WorkflowEvent` type accepts an optional [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables) that allows you to provide a type for the `payload` property within the `WorkflowEvent`.
31
+
32
+
Refer to the [events and parameters](/workflows/build/events-and-parameters/) documentation for how to handle events within yur Workflow code.
* <code>step.sleepUntil(name: string, timestamp: Date | number): Promise<void></code>
68
+
69
+
*`name` - the name of the step.
70
+
*`timestamp` - a JavaScript `Date` object or seconds from the Unix epoch to sleep the Workflow instance until.
71
+
72
+
## WorkflowStepConfig
73
+
74
+
```ts
75
+
exporttypeWorkflowStepConfig= {
76
+
retries?: {
77
+
limit:number;
78
+
delay:string|number;
79
+
backoff?:WorkflowBackoff;
80
+
};
81
+
timeout?:string|number;
82
+
};
83
+
```
84
+
85
+
* A `WorkflowStepConfig` is an optional argument to the `do` method of a `WorkflowStep` and defines properties that allow you to configure the retry behaviour of that step.
86
+
87
+
Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how how Workflows are retried.
88
+
89
+
## NonRetryableError
90
+
91
+
* <code>throw new NonRetryableError(message: <Typetext='string' />, name <Typetext='string' /> <MetaInfotext='optional' />)</code>: <Typetext='NonRetryableError' />
92
+
93
+
* Throws an error that forces the current Workflow instance to fail and not be retried.
94
+
* Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how how Workflows are retried.
95
+
96
+
## Call Workflows from Workers
97
+
98
+
:::note[Workflows beta]
99
+
100
+
Workflows currently requires you to bind to a Workflow via `wrangler.toml` and does not yet support bindings via the Workers dashboard.
101
+
102
+
:::
103
+
104
+
Workflows exposes a API directly to your Workers scripts via the [bindings](/workers/runtime-apis/bindings/#what-is-a-binding) concept. Bindings allow you to securely call a Workflow without having to manage API keys or clients.
105
+
106
+
You can bind to a Workflow by defining a `[[workflows]]` binding within your `wrangler.toml` configuration.
107
+
108
+
For example, to bind to a Workflow called `workflows-starter` and to make it available on the `MY_WORKFLOW` variable to your Worker script, you would configure the following fields within the `[[workflows]]` binding definition:
109
+
110
+
```toml title="wrangler.toml"
111
+
#:schema node_modules/wrangler/config-schema.json
112
+
name = "workflows-starter"
113
+
main = "src/index.ts"
114
+
compatibility_date = "2024-10-16"
115
+
116
+
[[workflows]]
117
+
# name of your workflow
118
+
name = "workflows-starter"
119
+
# binding name env.MYWORKFLOW
120
+
binding = "MY_WORKFLOW"
121
+
# this is class that extends the Workflow class in src/index.ts
122
+
class_name = "MyWorkflow"
123
+
# script_name is required during for the beta.
124
+
# Must match the "name" of your Worker at the top of wrangler.toml
125
+
script_name = "workflows-starter"
126
+
```
127
+
128
+
## Workflow
129
+
130
+
:::note
131
+
132
+
Ensure you have `@cloudflare/workers-types` version `4.20241022.0` or later installed when binding to Workflows from within a Workers project.
133
+
134
+
:::
135
+
136
+
The `Workflow` type provides methods that allow you to create, inspect the status and manage running Workflow instances from within a Worker script.
137
+
138
+
```ts
139
+
interfaceEnv {
140
+
// The 'MY_WORKFLOW' variable should match the "binding" value set in wrangler.toml
141
+
MY_WORKFLOW:Workflow;
142
+
}
143
+
```
144
+
145
+
The `Workflow` type exports the following methods:
52
146
53
-
* TODO -
147
+
### create
54
148
55
-
TODO - show an example
149
+
Create (trigger) a new instance of the given Workflow.
*`options` - optional properties to pass when creating an instance.
59
154
60
-
TODO
155
+
An ID is automatically generated, but a user-provided ID can be specified. This can be useful when mapping Workflows to users, merchants or other identifiers in your system.
61
156
62
-
## NonRetriableError
157
+
```ts
158
+
// Create a new Workflow instance with your own ID:
159
+
let instance =awaitenv.MY_WORKFLOW.create({ id: myIdDefinedFromOtherSystem })
0 commit comments