152 lines
6.5 KiB
Plaintext
152 lines
6.5 KiB
Plaintext
---
|
|
title: Workflows
|
|
label: Workflows
|
|
order: 30
|
|
desc: A Task is a distinct function declaration that can be run within Payload's Jobs Queue.
|
|
keywords: jobs queue, application framework, typescript, node, react, nextjs
|
|
---
|
|
|
|
<Banner type="default">
|
|
A **"Workflow"** is an optional way to *combine multiple tasks together* in a way that can be gracefully retried from the point of failure.
|
|
</Banner>
|
|
|
|
They're most helpful when you have multiple tasks in a row, and you want to configure each task to be able to be retried if they fail.
|
|
|
|
If a task within a workflow fails, the Workflow will automatically "pick back up" on the task where it failed and **not re-execute any prior tasks that have already been executed**.
|
|
|
|
#### Defining a workflow
|
|
|
|
The most important aspect of a Workflow is the `handler`, where you can declare when and how the tasks should run by simply calling the `runTask` function. If any task within the workflow, fails, the entire `handler` function will re-run.
|
|
|
|
However, importantly, tasks that have successfully been completed will simply re-return the cached and saved output without running again. The Workflow will pick back up where it failed and only task from the failure point onward will be re-executed.
|
|
|
|
To define a JS-based workflow, simply add a workflow to the `jobs.workflows` array in your Payload config. A workflow consists of the following fields:
|
|
|
|
| Option | Description |
|
|
| --------------------------- | -------------------------------------------------------------------------------- |
|
|
| `slug` | Define a slug-based name for this workflow. This slug needs to be unique among both tasks and workflows.|
|
|
| `handler` | The function that should be responsible for running the workflow. You can either pass a string-based path to the workflow function file, or workflow job function itself. If you are using large dependencies within your workflow, you might prefer to pass the string path because that will avoid bundling large dependencies in your Next.js app. Passing a string path is an advanced feature that may require a sophisticated build pipeline in order to work. |
|
|
| `inputSchema` | Define the input field schema - payload will generate a type for this schema. |
|
|
| `interfaceName` | You can use interfaceName to change the name of the interface that is generated for this workflow. By default, this is "Workflow" + the capitalized workflow slug. |
|
|
| `label` | Define a human-friendly label for this workflow. |
|
|
| `queue` | Optionally, define the queue name that this workflow should be tied to. Defaults to "default". |
|
|
| `retries` | You can define `retries` on the workflow level, which will enforce that the workflow can only fail up to that number of retries. If a task does not have retries specified, it will inherit the retry count as specified on the workflow. You can specify `0` as `workflow` retries, which will disregard all `task` retry specifications and fail the entire workflow on any task failure. You can leave `workflow` retries as undefined, in which case, the workflow will respect what each task dictates as their own retry count. By default this is undefined, meaning workflows retries are defined by their tasks |
|
|
|
|
Example:
|
|
|
|
```ts
|
|
export default buildConfig({
|
|
// ...
|
|
jobs: {
|
|
tasks: [
|
|
// ...
|
|
]
|
|
workflows: [
|
|
{
|
|
slug: 'createPostAndUpdate',
|
|
|
|
// The arguments that the workflow will accept
|
|
inputSchema: [
|
|
{
|
|
name: 'title',
|
|
type: 'text',
|
|
required: true,
|
|
},
|
|
],
|
|
|
|
// The handler that defines the "control flow" of the workflow
|
|
// Notice how it uses the `tasks` argument to execute your predefined tasks.
|
|
// These are strongly typed!
|
|
handler: async ({ job, tasks }) => {
|
|
|
|
// This workflow first runs a task called `createPost`.
|
|
|
|
// You need to define a unique ID for this task invocation
|
|
// that will always be the same if this workflow fails
|
|
// and is re-executed in the future. Here, we hard-code it to '1'
|
|
const output = await tasks.createPost('1', {
|
|
input: {
|
|
title: job.input.title,
|
|
},
|
|
})
|
|
|
|
// Once the prior task completes, it will run a task
|
|
// called `updatePost`
|
|
await tasks.updatePost('2', {
|
|
input: {
|
|
post: job.taskStatus.createPost['1'].output.postID, // or output.postID
|
|
title: job.input.title + '2',
|
|
},
|
|
})
|
|
},
|
|
} as WorkflowConfig<'updatePost'>
|
|
]
|
|
}
|
|
})
|
|
```
|
|
|
|
#### Running tasks inline
|
|
|
|
In the above example, our workflow was executing tasks that we already had defined in our Payload config. But, you can also run tasks without predefining them.
|
|
|
|
To do this, you can use the `inlineTask` function.
|
|
|
|
The drawbacks of this approach are that tasks cannot be re-used across workflows as easily, and the **task data stored in the job** will not be typed. In the following example, the inline task data will be stored on the job under `job.taskStatus.inline['2']` but completely untyped, as types for dynamic tasks like these cannot be generated beforehand.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
export default buildConfig({
|
|
// ...
|
|
jobs: {
|
|
tasks: [
|
|
// ...
|
|
]
|
|
workflows: [
|
|
{
|
|
slug: 'createPostAndUpdate',
|
|
inputSchema: [
|
|
{
|
|
name: 'title',
|
|
type: 'text',
|
|
required: true,
|
|
},
|
|
],
|
|
handler: async ({ job, tasks, inlineTask }) => {
|
|
// Here, we run a predefined task.
|
|
// The `createPost` handler arguments and return type
|
|
// are both strongly typed
|
|
const output = await tasks.createPost('1', {
|
|
input: {
|
|
title: job.input.title,
|
|
},
|
|
})
|
|
|
|
// Here, this task is not defined in the Payload config
|
|
// and is "inline". Its output will be stored on the Job in the database
|
|
// however its arguments will be untyped.
|
|
const { newPost } = await inlineTask('2', {
|
|
task: async ({ req }) => {
|
|
const newPost = await req.payload.update({
|
|
collection: 'post',
|
|
id: '2',
|
|
req,
|
|
retries: 3,
|
|
data: {
|
|
title: 'updated!',
|
|
},
|
|
})
|
|
return {
|
|
output: {
|
|
newPost
|
|
},
|
|
}
|
|
},
|
|
})
|
|
},
|
|
} as WorkflowConfig<'updatePost'>
|
|
]
|
|
}
|
|
})
|
|
```
|