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 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.
10
-
11
9
This guide details the Workflows API within Cloudflare Workers, including methods, types and usage examples.
12
10
13
-
## Bind to a Workflow
14
-
15
-
:::note[Workflows beta]
16
-
17
-
Workflows currently requires you to bind to a Workflow via `wrangler.toml` and does not yet support bindings via the Workers dashboard.
18
-
19
-
:::
11
+
## WorkflowEntrypoint
20
12
21
-
You can bind to a Workflow by defining a `[[workflows]]` binding within your `wrangler.toml` configuration.
22
-
23
-
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:
24
-
25
-
```toml title="wrangler.toml"
26
-
#:schema node_modules/wrangler/config-schema.json
27
-
name = "workflows-starter"
28
-
main = "src/index.ts"
29
-
compatibility_date = "2024-10-16"
13
+
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.
30
14
31
-
[[workflows]]
32
-
# name of your workflow
33
-
name = "workflows-starter"
34
-
# binding name env.MYWORKFLOW
35
-
binding = "MY_WORKFLOW"
36
-
# this is class that extends the Workflow class in src/index.ts
37
-
class_name = "MyWorkflow"
38
-
# script_name is required during for the beta.
39
-
# Must match the "name" of your Worker at the top of wrangler.toml
*`event` - the event passed to the Workflow, including an optional `payload` containing data (parameters)
@@ -112,3 +90,183 @@ Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-
112
90
113
91
* Throws an error that forces the current Workflow instance to fail and not be retried.
114
92
* Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how how Workflows are retried.
93
+
94
+
## Call Workflows from Workers
95
+
96
+
:::note[Workflows beta]
97
+
98
+
Workflows currently requires you to bind to a Workflow via `wrangler.toml` and does not yet support bindings via the Workers dashboard.
99
+
100
+
:::
101
+
102
+
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.
103
+
104
+
You can bind to a Workflow by defining a `[[workflows]]` binding within your `wrangler.toml` configuration.
105
+
106
+
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:
107
+
108
+
```toml title="wrangler.toml"
109
+
#:schema node_modules/wrangler/config-schema.json
110
+
name = "workflows-starter"
111
+
main = "src/index.ts"
112
+
compatibility_date = "2024-10-16"
113
+
114
+
[[workflows]]
115
+
# name of your workflow
116
+
name = "workflows-starter"
117
+
# binding name env.MYWORKFLOW
118
+
binding = "MY_WORKFLOW"
119
+
# this is class that extends the Workflow class in src/index.ts
120
+
class_name = "MyWorkflow"
121
+
# script_name is required during for the beta.
122
+
# Must match the "name" of your Worker at the top of wrangler.toml
123
+
script_name = "workflows-starter"
124
+
```
125
+
126
+
## Workflow
127
+
128
+
:::note
129
+
130
+
Ensure you have `@cloudflare/workers-types` version `4.20241022.0` or later installed when binding to Workflows from within a Workers project.
131
+
132
+
:::
133
+
134
+
The `Workflow` type provides methods that allow you to create, inspect the status and manage running Workflow instances from within a Worker script.
135
+
136
+
```ts
137
+
interfaceEnv {
138
+
// The 'MY_WORKFLOW' variable should match the "binding" value set in wrangler.toml
139
+
MY_WORKFLOW:Workflow;
140
+
}
141
+
```
142
+
143
+
The `Workflow` type exports the following methods:
144
+
145
+
### create
146
+
147
+
Create (trigger) a new instance of the given Workflow.
*`options` - optional properties to pass when creating an instance.
152
+
153
+
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.
154
+
155
+
```ts
156
+
// Create a new Workflow instance with your own ID:
157
+
let instance =awaitenv.MY_WORKFLOW.create({ id: myIdDefinedFromOtherSystem })
| Read Queries (qps) |`readQueries`| The number of read queries issued against a database. This is the raw number of read queries, and is not used for billing. |
20
20
21
21
Metrics can be queried (and are retained) for the past 31 days.
22
22
23
+
### Labels and dimensions
24
+
25
+
The `workflowsAdaptiveGroups` dataset provides the following dimensions for filtering and grouping query results:
26
+
27
+
*`workflowName` - Workflow name - e.g. `my-workflow`
28
+
*`instanceId` - Instance ID.
29
+
*`stepName` - Step name
30
+
*`eventType` - Event type (see [event types](#event-types))
31
+
*`stepCount` - Step number within a given instance
32
+
*`date` - The date when trigger was triggered
33
+
*`datetimeFifteenMinutes` - The date and time truncated to fifteen minutes
34
+
*`datetimeFiveMinutes` - The date and time truncated to five minutes
35
+
*`datetimeHour` - The date and time truncated to the hour
36
+
*`datetimeMinute` - The date and time truncated to the minute
37
+
38
+
### Event types
39
+
40
+
The `eventType` metric allows you to filter (or groupBy) Workflows and steps based on their last observed status.
41
+
42
+
The possible values for `eventType` are documented below:
43
+
44
+
#### Workflows-level status labels
45
+
46
+
*`WORKFLOW_QUEUED` - the Workflow is queued, but not currently running. This can happen when you are at the [concurrency limit](/workflows/reference/limits/) and new instances are waiting for currently running instances to complete.
47
+
*`WORKFLOW_START` - the Workflow has started and is running.
48
+
*`WORKFLOW_SUCCESS` - the Workflow finished without errors.
49
+
*`WORKFLOW_FAILURE` - the Workflow failed due to errors (exhausting retries, errors thrown, etc)
50
+
*`WORKFLOW_TERMINATED` - the Workflow was explicitly terminated.
51
+
52
+
#### Step-level status labels
53
+
54
+
*`STEP_START` - the step has started and is running.
55
+
*`STEP_SUCCESS` - the step finished without errors.
56
+
*`STEP_FAILURE` - the step failed due to an error.
57
+
*`SLEEP_START` - the step is sleeping.
58
+
*`SLEEP_COMPLETE` - the step last finished sleeping.
59
+
*`ATTEMPT_START` - a step is retrying.
60
+
*`ATTEMPT_SUCCESS` - the retry succeeded.
61
+
*`ATTEMPT_FAILURE` - the retry attempt failed.
62
+
23
63
## View metrics in the dashboard
24
64
25
65
Per-Workflow and instance analytics for Workflows are available in the Cloudflare dashboard. To view current and historical metrics for a database:
@@ -34,7 +74,7 @@ You can optionally select a time window to query. This defaults to the last 24 h
34
74
35
75
You can programmatically query analytics for your Workflows via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).
36
76
37
-
Workflows GraphQL datasets require an `accountTag` filter with your Cloudflare account ID, and includes the `workflowsAdaptive` and `workflowsAdaptiveGroups`datasets.
77
+
Workflows GraphQL datasets require an `accountTag` filter with your Cloudflare account ID, and includes the `workflowsAdaptiveGroups`dataset.
38
78
39
79
### Examples
40
80
@@ -126,7 +166,7 @@ Here we are doing the same for `wallTime`, `instanceRuns` and `stepCount` in the
126
166
127
167
Here lets query `workflowsAdaptive` for raw data about `$instanceId` between `$datetimeStart` and `$datetimeEnd`:
128
168
129
-
```
169
+
```graphql
130
170
{
131
171
viewer {
132
172
accounts(filter: { accountTag: $accountTag }) {
@@ -165,32 +205,3 @@ Example values for the query variables:
As said above, you can use [introspection](/analytics/graphql-api/features/discovery/introspection/) with your favorite GraphQL client to discover the available fields and types of the Workflows datasets, but here are some of our `workflowsAdaptiveGroups` dimensions:
170
-
171
-
* date - The date when trigger was triggered
172
-
* datetimeFifteenMinutes - The date and time truncated to fifteen minutes
173
-
* datetimeFiveMinutes - The date and time truncated to five minutes
174
-
* datetimeHour - The date and time truncated to the hour
175
-
* datetimeMinute - The date and time truncated to the minute
176
-
* eventType - Event type
177
-
* instanceId - Instance Id
178
-
* stepCount - Step number
179
-
* stepName - Step name
180
-
* workflowName - Workflow Name
181
-
182
-
And here's a list of `eventType`s you can filter on:
| Retention limit for completed Workflow state | 3 days | 30 days [^2]|
28
+
| Maximum length of a Workflow ID | 64 bytes |
28
29
29
-
[^1]: This limit will be reviewed and revised during the open beta for Workflows, and we'll update this page and our changelog.
30
+
[^1]: This limit will be reviewed and revised during the open beta for Workflows. Follow the [Workflows changelog](/workflows/reference/changelog/) for updates.
30
31
31
-
[^2]: Workflow state and logs will be retained for 3 days on the Workers Free plan and 30 days on the Workers Paid plan.
32
+
[^2]: Workflow state and logs will be retained for 3 days on the Workers Free plan and for 7 days on the Workers Paid plan.
0 commit comments