Skip to content

Commit c8d807e

Browse files
elithrarOxyjuncelsobruxodasilva
authored and
harshil1712
committed
workflows: new docset #16220)
* commit * icon * fix link * rename to workflows-starter * fix limit * mebibyte * events and params * npx -> npm * more * wrangler * cron triggers * more docs * rules of steps * fix * CLI guide * finish CLI starter * update landing page * fix numbering * fix link formatting * fix * sleeping / retrying * trigger * wording * wrap get-started guide * rules of workflows * trigger done * sleep * NonRetryableError * better header for nonretryableerror * npm create cloudflare@latest workflows-starter -- --template 'cloudflare/workflows-starter' * Apply suggestions from code review Co-authored-by: Jun Lee <[email protected]> * @workflows -> @latest * remove output from CLI guide * fix missing link * fix links * workflows: review Co-authored-by: Jun Lee <[email protected]> * Adds Workflows GraphQL examples and docs * Apply suggestions from code review Co-authored-by: Jun Lee <[email protected]> * types * changelog + dates * Apply suggestions from code review Fixing broken CI (required) pipeline by removing duplicated lines. * workflows: Apply suggestions from code review Co-authored-by: Jun Lee <[email protected]> * compat date * remove how-workflows-works for now * finalize types * wrangler version note * Importing Type and MetaInfo component Stops the required CI pipeline from breaking. * Fixing REST API links Not fixing it blocks merge. * Apply suggestions from code review Co-authored-by: Diogo Ferreira <[email protected]> Co-authored-by: Jun Lee <[email protected]> * fix API URL * comment out pause * fix bad class naming * edits * naming steps --------- Co-authored-by: Jun Lee <[email protected]> Co-authored-by: Celso Martinho <[email protected]> Co-authored-by: Diogo Ferreira <[email protected]>
1 parent 5e20bcd commit c8d807e

30 files changed

+2433
-2
lines changed

‎src/content/changelogs/workflows.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
link: "/workflows/reference/changelog/"
3+
productName: Workflows
4+
productLink: "/workflows/"
5+
productArea: Developer platform
6+
productAreaLink: /workers/platform/changelog/platform/
7+
entries:
8+
- publish_date: "2024-10-23"
9+
title: "Workflows is now in public beta!"
10+
description: |-
11+
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+
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+
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/).

‎src/content/docs/workers/configuration/cron-triggers.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ Cron Triggers allow users to map a cron expression to a Worker using a [`schedul
1111

1212
Cron Triggers are ideal for running periodic jobs, such as for maintenance or calling third-party APIs to collect up-to-date data. Workers scheduled by Cron Triggers will run on underutilized machines to make the best use of Cloudflare's capacity and route traffic efficiently.
1313

14+
:::note
15+
16+
Cron Triggers can also be combined with [Workflows](/workflows/) to trigger multi-step, long-running tasks. You can [bind to a Workflow](/workflows/build/workers-api/) from directly from your Cron Trigger to execute a Workflow on a schedule.
17+
18+
:::
19+
1420
Cron Triggers execute on UTC time.
1521

1622
## Add a Cron Trigger

‎src/content/docs/workers/runtime-apis/bindings/workflows.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Workflows
4+
external_link: /workflows/
5+
head: []
6+
description: APIs available in Cloudflare Workers to interact with
7+
Workflows. Workflows allow you to build durable, multi-step applications
8+
using Workers.
9+
10+
---

‎src/content/docs/workers/wrangler/commands.mdx‎

Lines changed: 151 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Wrangler offers a number of commands to manage your Cloudflare Workers.
2828
- [`r2 object`](#r2-object) - Manage Workers R2 objects.
2929
- [`secret`](#secret) - Manage the secret variables for a Worker.
3030
- [`secret:bulk`](#secretbulk) - Manage multiple secret variables for a Worker.
31+
- [`workflows`](#workflows) - Manage and configure Workflows.
3132
- [`tail`](#tail) - Start a session to livestream logs from a deployed Worker.
3233
- [`pages`](#pages) - Configure Cloudflare Pages.
3334
- [`queues`](#queues) - Configure Workers Queues.
@@ -138,10 +139,10 @@ wrangler docs [<COMMAND>]
138139

139140
## `init`
140141

141-
:::note
142+
:::note
142143

143144

144-
The `init` command will be removed in a future version. Please use `npm create cloudflare@latest` instead.
145+
The `init` command will be removed in a future version. Please use `npm create cloudflare@latest` instead.
145146

146147

147148
:::
@@ -1244,6 +1245,154 @@ Finished processing secrets JSON file:
12441245
🚨 1 secrets failed to upload
12451246
```
12461247

1248+
## `workflows`
1249+
1250+
:::note
1251+
1252+
The `wrangler workflows` command requires Wrangler version `3.83.0` or greater. Use `npx wrangler@latest` to always use the latest Wrangler version when invoking commands.
1253+
1254+
:::
1255+
1256+
Manage and configure [Workflows](/workflows/).
1257+
1258+
### `list`
1259+
1260+
Lists the registered Workflows for this account.
1261+
1262+
```sh
1263+
wrangler workflows list
1264+
```
1265+
1266+
- `--page` <Type text="number" /> <MetaInfo text="optional" />
1267+
- Show a specific page from the listing. You can configure page size using "per-page".
1268+
- `--per-page` <Type text="number" /> <MetaInfo text="optional" />
1269+
- Configure the maximum number of Workflows to show per page.
1270+
1271+
### `instances`
1272+
1273+
Manage and interact with specific instances of a Workflow.
1274+
1275+
### `instances list`
1276+
1277+
List Workflow instances.
1278+
1279+
```sh
1280+
wrangler workflows instances list <WORKFLOW_NAME> [OPTIONS]
1281+
```
1282+
1283+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1284+
- The name of a registered Workflow.
1285+
1286+
### `instances describe`
1287+
1288+
Describe a specific instance of a Workflow, including its current status, any persisted state, and per-step outputs.
1289+
1290+
```sh
1291+
wrangler workflows instances describe <WORKFLOW_NAME> <ID> [OPTIONS]
1292+
```
1293+
1294+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1295+
- The name of a registered Workflow.
1296+
- `ID` <Type text="string" /> <MetaInfo text="required" />
1297+
- The ID of a Workflow instance. You can optionally provide `latest` to refer to the most recently created instance of a Workflow.
1298+
1299+
```sh
1300+
# Passing `latest` instead of an explicit ID will describe the most recently queued instance
1301+
wrangler workflows instances describe my-workflow latest
1302+
```
1303+
```sh output
1304+
Workflow Name: my-workflow
1305+
Instance Id: 51c73fc8-7fd5-47d9-bd82-9e301506ee72
1306+
Version Id: cedc33a0-11fa-4c26-8a8e-7d28d381a291
1307+
Status: ✅ Completed
1308+
Trigger: 🌎 API
1309+
Queued: 10/16/2024, 2:00:39 PM
1310+
Success: ✅ Yes
1311+
Start: 10/16/2024, 2:00:39 PM
1312+
End: 10/16/2024, 2:01:40 PM
1313+
Duration: 1 minute
1314+
# Remaining output truncated
1315+
```
1316+
1317+
### `instances terminate`
1318+
1319+
Terminate (permanently stop) a Workflow instance.
1320+
1321+
```sh
1322+
wrangler workflows instances terminate <WORKFLOW_NAME> <ID> [OPTIONS]
1323+
```
1324+
1325+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1326+
- The name of a registered Workflow.
1327+
- `ID` <Type text="string" /> <MetaInfo text="required" />
1328+
- The ID of a Workflow instance.
1329+
1330+
{/*
1331+
### `instances pause`
1332+
1333+
Pause (until resumed) a Workflow instance.
1334+
1335+
```sh
1336+
wrangler workflows instances pause <WORKFLOW_NAME> <ID> [OPTIONS]
1337+
```
1338+
1339+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1340+
- The name of a registered Workflow.
1341+
- `ID` <Type text="string" /> <MetaInfo text="required" />
1342+
- The ID of a Workflow instance.
1343+
1344+
### `instances resume`
1345+
1346+
Resume a paused Workflow instance.
1347+
1348+
```sh
1349+
wrangler workflows instances resume <WORKFLOW_NAME> <ID> [OPTIONS]
1350+
```
1351+
1352+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1353+
- The name of a registered Workflow.
1354+
- `ID` <Type text="string" /> <MetaInfo text="required" />
1355+
- The ID of a Workflow instance.
1356+
1357+
*/}
1358+
1359+
### `describe`
1360+
1361+
```sh
1362+
wrangler workflows describe <WORKFLOW_NAME> [OPTIONS]
1363+
```
1364+
1365+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1366+
- The name of a registered Workflow.
1367+
1368+
### `trigger`
1369+
1370+
Trigger (create) a Workflow instance.
1371+
```sh
1372+
wrangler workflows describe <WORKFLOW_NAME> <PARAMS> [OPTIONS]
1373+
```
1374+
1375+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1376+
- The name of a registered Workflow.
1377+
- `PARAMS` <Type text="string" /> <MetaInfo text="optional" />
1378+
- The parameters to pass to the Workflow as an event. Must be a JSON-encoded string.
1379+
1380+
```sh
1381+
# Pass optional params to the Workflow.
1382+
wrangler workflows instances trigger my-workflow '{"hello":"world"}'
1383+
```
1384+
1385+
### `delete`
1386+
1387+
Delete (unregister) a Workflow.
1388+
1389+
```sh
1390+
wrangler workflows delete <WORKFLOW_NAME> [OPTIONS]
1391+
```
1392+
1393+
- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
1394+
- The name of a registered Workflow.
1395+
12471396
## `tail`
12481397

12491398
Start a session to livestream logs from a deployed Worker.

‎src/content/docs/workflows/build/events-and-parameters.mdx‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Events and parameters
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 10
6+
7+
---
8+
9+
When a Workflow is triggered, it can receive an optional event. This event can include data that your Workflow can act on, including request details, user data fetched from your database (such as D1 or KV) or from a webhook, or messages from a Queue consumer.
10+
11+
Events are a powerful part of a Workflow, as you often want a Workflow to act on data. Because a given Workflow instance executes durably, events are a useful way to provide a Workflow with data that should be immutable (not changing) and/or represents data the Workflow needs to operate on at that point in time.
12+
13+
## Pass parameters to a Workflow
14+
15+
You can pass parameters to a Workflow in two ways:
16+
17+
* As an optional argument to the `create` method on a [Workflow binding](/workers/wrangler/commands/#trigger) when triggering a Workflow from a Worker.
18+
* Via the `--params` flag when using the `wrangler` CLI to trigger a Workflow.
19+
20+
You can pass any JSON-serializable object as a parameter.
21+
22+
:::caution
23+
24+
A `WorkflowEvent` and its associated `payload` property are effectively _immutable_: any changes to an event are not persisted across the steps of a Workflow. This includes both cases when a Workflow is progressing normally, and in cases where a Workflow has to be restarted due to a failure.
25+
26+
Store state durably by returning it from your `step.do` callbacks.
27+
28+
:::
29+
30+
```ts
31+
export default {
32+
async fetch(req: Request, env: Env) {
33+
let someEvent = { url: req.url, createdTimestamp: Date.now() }
34+
// Trigger our Workflow
35+
// Pass our event as the second parameter to the `create` method
36+
// on our Workflow binding.
37+
let instance = await env.MYWORKFLOW.create(await crypto.randomUUID(), someEvent);
38+
39+
return Response.json({
40+
id: instance.id,
41+
details: await instance.status(),
42+
});
43+
44+
return Response.json({ result });
45+
},
46+
};
47+
```
48+
49+
To pass parameters via the `wrangler` command-line interface, pass a JSON string as the second parameter to the `workflows trigger` sub-command:
50+
51+
```sh
52+
npx wrangler@latest workflows trigger workflows-starter '{"some":"data"}'
53+
```
54+
```sh output
55+
🚀 Workflow instance "57c7913b-8e1d-4a78-a0dd-dce5a0b7aa30" has been queued successfully
56+
```
57+
58+
## TypeScript and type parameters
59+
60+
By default, the `WorkflowEvent` passed to the `run` method of your Workflow definition has a type that conforms to the following, with `payload` (your data) and `timestamp` properties:
61+
62+
```ts
63+
export type WorkflowEvent<T> = {
64+
// The data passed as the parameter when the Workflow instance was triggered
65+
payload: T;
66+
// The timestamp that the Workflow was triggered
67+
timestamp: Date;
68+
};
69+
```
70+
71+
You can optionally type these events by defining your own type and passing it as a [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables) to the `WorkflowEvent`:
72+
73+
```ts
74+
// Define a type that conforms to the events your Workflow instance is
75+
// instantiated with
76+
interface YourEventType {
77+
userEmail: string;
78+
createdTimestamp: number;
79+
metadata?: Record<string, string>;
80+
}
81+
```
82+
83+
When you pass your `YourEventType` to `WorkflowEvent` as a type parameter, the `event.payload` property now has the type `YourEventType` throughout your workflow definition:
84+
85+
```ts title="src/index.ts"
86+
// Import the Workflow definition
87+
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent} from 'cloudflare:workers';
88+
89+
export class MyWorkflow extends WorkflowEntrypoint {
90+
// Pass your type as a type parameter to WorkflowEvent
91+
// The 'payload' property will have the type of your parameter.
92+
async run(event: WorkflowEvent<YourEventType>, step: WorkflowStep) {
93+
let state = step.do("my first step", async () => {
94+
// Access your properties via event.payload
95+
let userEmail = event.payload.userEmail
96+
let createdTimestamp = event.payload.createdTimestamp
97+
})
98+
99+
step.do("my second step", async () => { /* your code here */ )
100+
}
101+
}
102+
```
103+
104+
Note that type parameters do not _validate_ that the incoming event matches your type definition. Properties (fields) that do not exist or conform to the type you provided will be dropped. If you need to validate incoming events, we recommend a library such as [zod](https://zod.dev/) or your own validator logic.

‎src/content/docs/workflows/build/index.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Build with Workflows
3+
pcx_content_type: navigation
4+
sidebar:
5+
order: 2
6+
group:
7+
hideIndex: true
8+
9+
---
10+
11+
import { DirectoryListing } from "~/components"
12+
13+
<DirectoryListing />

0 commit comments

Comments
 (0)