mirror of
https://github.com/directus/directus.git
synced 2026-01-29 05:48:14 -05:00
435 lines
15 KiB
Markdown
435 lines
15 KiB
Markdown
---
|
|
description:
|
|
Operations are the individual actions in a flow. They enable you to do things like manage data within Directus,
|
|
transform the flow's data, send information off to outside services, set conditional logic, trigger other flows, and
|
|
beyond!
|
|
readTime: 5 min read
|
|
---
|
|
|
|
# Operations
|
|
|
|
> Operations are the individual actions in a flow. They enable you to do things like manage data within Directus,
|
|
> transform the flow's data, send information off to outside services, set conditional logic, trigger other flows, _and
|
|
> beyond!_
|
|
|
|
:::tip Before You Begin
|
|
|
|
On this page, we'll explain what each operation does, the value it appends to the data chain, how to make use of its
|
|
configuration options, as well as any well as other relevant details. We will assume you have read the documentation on
|
|
[Flows](/configuration/flows) and [Triggers](/configuration/flows/triggers).
|
|
|
|
:::
|
|
|
|
## Condition
|
|
|
|
|
|
|
|
A **Condition** operation lets you choose a **success path** or **failure path** by validating data passed into it with
|
|
[Filter Rules](/reference/filter-rules).
|
|
|
|
**Options**
|
|
|
|
- **Condition Rules** — Create conditions with [Filter Rules](/reference/filter-rules).
|
|
|
|
**Payload**
|
|
|
|
This operation does not generate data. If the filter rule is configured properly, it will append a `null` value on its
|
|
`operationKey`, regardless of if the condition was met or not. However, if the filter rule is misconfigured, it will
|
|
append an array containing an object you can use to help debug the misconfiguration.
|
|
|
|
**More Details**
|
|
|
|
:::warning
|
|
|
|
When using an [Event Hook](/configuration/flows/triggers.md#event-hook) configured to be **Action (Blocking)**, if your
|
|
flow ends with a condition that executes with a `reject` path, it will cancel your database transaction.
|
|
|
|
:::
|
|
|
|
## Run Script
|
|
|
|
<!--
|
|
<video autoplay playsinline muted loop controls title="Run Script">
|
|
<source src="" type="video/mp4" />
|
|
</video>
|
|
-->
|
|
|
|
This operation lets you add a custom script using vanilla JavaScript or TypeScript.
|
|
The script will be executed securely in an isolated sandbox. No interactions take place between the sandbox and the host except for sharing input and output values. This means, for example, no access to the file system and no ability to do network requests.
|
|
|
|
**Options**
|
|
|
|
The operation provides a default function template. The _optional_ `data` parameter lets you pass in the data chain as
|
|
an argument.
|
|
|
|
**Payload**
|
|
|
|
The function's `return` value will be appended under its `<operationKey>`.
|
|
|
|
**More Details**
|
|
|
|
As an example, let's say you have this function in a script operation, named `myScript`.
|
|
|
|
```JSON
|
|
// A key from the data chain
|
|
{
|
|
"previousOperation": {
|
|
"value": 5
|
|
}
|
|
}
|
|
```
|
|
|
|
Then you add the following logic via Run Script.
|
|
|
|
```TypeScript
|
|
// Your function in the myScript operation
|
|
module.exports = function(data) {
|
|
return {
|
|
timesTwo: data.previousOperation.value * 2
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
The returned value will be appended under the `myScript` operation key.
|
|
|
|
```JSON
|
|
{
|
|
"previousOperation": {
|
|
"value": 5
|
|
},
|
|
"myScript": {
|
|
"timesTwo": 10
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
:::tip
|
|
|
|
Make sure your `return` value is valid JSON.
|
|
|
|
:::
|
|
|
|
:::tip Throwing Errors
|
|
|
|
If you throw an error in a **Run Script** operation, it will immediately break your flow chain and stop execution of
|
|
subsequent flows. If you used a ["Blocking" Event hook](/configuration/flows/triggers.md#event-hook), throwing an error
|
|
will cancel the original event transaction to the database.
|
|
|
|
:::
|
|
|
|
:::tip Node Modules
|
|
|
|
For security reasons, module usage is disabled by default. You can configure what Node Modules are available through
|
|
[the `FLOWS_EXEC_ALLOWED_MODULES` environment variable](/self-hosted/config-options#security).
|
|
|
|
:::
|
|
|
|
## Create Data
|
|
|
|
|
|
|
|
This operation creates item(s) in a collection.
|
|
|
|
**Options**
|
|
|
|
- **Collection** — Select the collection you'd like to create items in.
|
|
- **Permissions** — Select the scope of permissions used for this operation.
|
|
- **Emit Events** — Toggle whether the event is emitted.
|
|
- **Payload** — Defines the payload to create item(s) in a collection.
|
|
|
|
**Payload**
|
|
|
|
An array with the ID(s) of all items created will be appended under its `<operationKey>`.
|
|
|
|
**More Details**
|
|
|
|
:::warning
|
|
|
|
**Emit Events** toggles the event's _visibility_ throughout Directus. For example, if toggled on, this operation will
|
|
trigger relevant event hooks in other flows or custom extensions. If toggled off, the operation will not trigger other
|
|
event hooks. Imagine a situation where you have a flow being triggered by `<collection>.items.create` which contains an
|
|
operation that then tries to create another item in that `<collection>`. This would throw an infinite loop where the
|
|
operation triggers its own flow, endlessly. However, if you toggle **Emit Events** off, then this operation no longer
|
|
triggers other event hooks.
|
|
|
|
:::
|
|
|
|
:::tip
|
|
|
|
To learn about payload requirements when creating an item, see [API Reference > Items](/reference/items).
|
|
|
|
:::
|
|
|
|
## Delete Data
|
|
|
|
|
|
|
|
This operation deletes item(s) from a collection.
|
|
|
|
**Options**
|
|
|
|
- **Collection** — Select the collection you'd like to delete items from.
|
|
- **Permissions** — Set the scope of permissions used for this operation.
|
|
- **Emit Events** — Toggle whether the event is emitted.
|
|
- **IDs** — Set Item IDs and press enter to confirm. Click the ID to remove.
|
|
- **Query** — Select items to delete with a query. To learn more, see [Filter Rules](/reference/filter-rules).
|
|
|
|
**Payload**
|
|
|
|
An array with the ID(s) of all items deleted will be appended under its `<operationKey>`.
|
|
|
|
**More Details**
|
|
|
|
:::warning
|
|
|
|
**Emit Events** toggles the event's _visibility_ throughout Directus. For example, if togged on, this operation will
|
|
trigger relevant event hooks in other flows or custom extensions. If toggled off, the operation will not trigger other
|
|
event hooks. Imagine a situation where you have a flow being triggered by `<collection>.items.delete` which contains an
|
|
operation that then tries to delete another item in that `<collection>`. This would throw an infinite loop where the
|
|
operation triggers its own flow, endlessly. However, if you toggle **Emit Events** off, then this operation no longer
|
|
triggers other event hooks.
|
|
|
|
:::
|
|
|
|
## Read Data
|
|
|
|
|
|
|
|
This operation reads item(s) from a collection and adds them onto the data chain. You may select Items by their ID or by
|
|
running a query.
|
|
|
|
**Options**
|
|
|
|
- **Permissions** — Set the scope of permissions used for this operation.
|
|
- **Collections** — Select the collection you'd like to read items from.
|
|
- **IDs** — Input the ID for items you wish to read and press enter. Click the ID to remove.
|
|
- **Query** — Select the items with a query. To learn more, see [Filter Rules](/reference/filter-rules).
|
|
- **Emit Events** — Toggle whether the event is emitted.
|
|
|
|
**Payload**
|
|
|
|
An array containing all items read will be appended under its `<operationKey>`.
|
|
|
|
**More Details**
|
|
|
|
:::warning
|
|
|
|
**Emit Events** toggles the event's _visibility_ throughout Directus. For example, if togged on, this operation will
|
|
trigger relevant event hooks in other flows or custom extensions. If toggled off, the operation will not trigger other
|
|
event hooks. Imagine a situation where you have a flow being triggered by `<collection>.items.read` which contains an
|
|
operation that then tries to read another item in that `<collection>`. This would throw an infinite loop where the
|
|
operation triggers its own flow, endlessly. However, if you toggle **Emit Events** off, then this operation no longer
|
|
triggers other event hooks.
|
|
|
|
:::
|
|
|
|
## Update Data
|
|
|
|
|
|
|
|
This operation updates item(s) in a collection. You may select item(s) to update by their ID or by running a query.
|
|
|
|
**Options**
|
|
|
|
- **Collection** — Select the collection on which you'd like to update items in.
|
|
- **Permissions** — Set the role that this operation will inherit permissions from.
|
|
- **Emit Events** — Toggle whether the event is emitted.
|
|
- **IDs** — Input the ID for Item(s) you wish to read and press enter. Click the ID to remove.
|
|
- **Payload** — Update Items in a collection. To learn more, see [API > Items](/reference/items).
|
|
- **Query** — Select items to update with a query. To learn more, see [Filter Rules](/reference/filter-rules).
|
|
|
|
**Payload**
|
|
|
|
An array containing all items updated will be appended under its `<operationKey>`.
|
|
|
|
**More Details**
|
|
|
|
:::warning
|
|
|
|
**Emit Events** toggles the event's _visibility_ throughout Directus. For example, if togged on, this operation will
|
|
trigger relevant event hooks in other flows or custom extensions. If toggled off, the operation will not trigger other
|
|
event hooks. Imagine a situation where you have a flow being triggered by `<collection>.items.update` which contains an
|
|
operation that then tries to update another item in that `<collection>`. This would throw an infinite loop where the
|
|
operation triggers its own flow, endlessly updating items. However, if you toggle **Emit Events** off, then this
|
|
operation no longer triggers other event hooks.
|
|
|
|
:::
|
|
|
|
:::tip
|
|
|
|
To learn about `payload` requirements when updating an item, see [API Reference > Items](/reference/items).
|
|
|
|
:::
|
|
|
|
## Log to Console
|
|
|
|
|
|
|
|
This operation outputs information to the server-side console as well as the [Logs](/configuration/flows#logs) within
|
|
the Data Studio. This is a key tool for troubleshooting flow configuration. A Log operation's key will have a null value
|
|
on the data chain.
|
|
|
|
**Options**
|
|
|
|
- **Message** — Sets a [log message](/configuration/flows#logs).
|
|
|
|
**Payload**
|
|
|
|
This operation does not generate data for the data chain as its messages are for debugging and troubleshooting. It will
|
|
append a `null` value on the `operationKey`.
|
|
|
|
**More Details**
|
|
|
|
For more details, see the section on [Logs](/configuration/flows#logs).
|
|
|
|
## Send Email
|
|
|
|
|
|
|
|
This operation sends off emails.
|
|
|
|
**Options**
|
|
|
|
- **To** — Sets the email addresses. Hit `↵` `Enter` (PC) or `return` (Mac) to save the email. Click on a pill to remove
|
|
it.
|
|
- **Subject** — Set the subject line.
|
|
- **Body** — Use a Markdown or WYSIWYG editor to create the email body.
|
|
|
|
**Payload**
|
|
|
|
This operation does not generate data for the data chain. It will append a `null` value on the `operationKey`.
|
|
|
|
**More Details**
|
|
|
|
:::tip Batch Emails
|
|
|
|
You can input an array of emails in the `To` input option to send off multiple emails.
|
|
|
|
:::
|
|
|
|
:::tip
|
|
|
|
If you are testing out this operation from `localhost:8080`, be sure to check your spam box, because your email provider
|
|
may send it there automatically.
|
|
|
|
:::
|
|
|
|
## Send Notification
|
|
|
|
|
|
|
|
This operation pushes notifications to Directus Users. If the operation executes successfully, a list containing the IDs
|
|
of all sent notifications generated is appended under this operation's key.
|
|
|
|
**Options**
|
|
|
|
- **Users** — Define a user by their UUID. Hit `↵` `Enter` (PC) or `return` (Mac) to save it. Click on a pill to remove
|
|
it.
|
|
- **Permissions** — Define the role that this operation will inherit permissions from.
|
|
- **Title** — Set the title of the notification.
|
|
- **Message** — Set the main body of the notification.
|
|
|
|
**Payload**
|
|
|
|
This operation does not generate data. It will append a `null` value on its `operationKey`.
|
|
|
|
**More Details**
|
|
|
|
:::tip Batch Notifications
|
|
|
|
You can input an array of UUIDs in the `To` input option to send off multiple emails.
|
|
|
|
:::
|
|
|
|
## Webhook / Request URL
|
|
|
|
|
|
|
|
This operation makes a request to another URL.
|
|
|
|
**Options**
|
|
|
|
- **Method** — Choose to make a GET, POST, PATCH, DELETE, or other type of request.
|
|
- **URL** — Define the URL to send the request to.
|
|
- **Headers** — Create a new `header:value` to pass along with the request.
|
|
- **Request Body** — Set the request body's data.
|
|
|
|
**Payload**
|
|
|
|
When an operation completes successfully, the `response` is appended under its `<operationKey`.
|
|
|
|
## Sleep
|
|
|
|
|
|
|
|
This operation creates a delay in the Flow for a given amount of milliseconds, then continues to the next operation.
|
|
|
|
**Options**
|
|
|
|
- **Milliseconds** — Define the number of milliseconds to sleep.
|
|
|
|
**Payload**
|
|
|
|
This operation does not generate data. It will append a `null` value on its `operationKey`.
|
|
|
|
## Transform Payload
|
|
|
|
|
|
|
|
This operation lets you custom define your own JSON payload for use in subsequent operations. This enables you to take
|
|
multiple sources of data and "tidy them up" into a single payload.
|
|
|
|
**Options**
|
|
|
|
- **JSON** — Define JSON to insert into the data chain.
|
|
|
|
**Payload**
|
|
|
|
When an operation completes successfully, the value you defined under the **JSON** configuration operation is appended
|
|
onto its `operationKey`.
|
|
|
|
**More Details**
|
|
|
|
When does the Transform Payload operation come in handy? Let's say you need to create a payload with data from a
|
|
`users_collection`, `widgets_collection` and some 3rd party resource which processes the data. You can add a
|
|
[Read Data](#read-data) operation for `collection_a`, another Read Data operation for `collection_b`, and a
|
|
[Webhook](#webhook--request-url) operation for the third party resource.
|
|
|
|
Then you could stitch together all this data to create a new JSON object, like so:
|
|
|
|
```
|
|
{
|
|
"note": "You can add a hard-coded value!",
|
|
"name": "{{users_collection.username}}",
|
|
"widget_id": "{{widgets_collection.id}}",
|
|
"results": "{{webhookKey.subnestedValue}}"
|
|
}
|
|
```
|
|
|
|
## Trigger Flow
|
|
|
|
|
|
|
|
This operation starts another flow and _(optionally)_ passes data into it. It should be used in combination with the
|
|
[Another Flow](/configuration/flows/triggers#another-flow) trigger.
|
|
|
|
**Options**
|
|
|
|
- **Flow** — Define a flow by its primary key UUID.
|
|
- **Payload** — Defines a JSON `payload` to pass into `$trigger` on the flow it triggered.
|
|
|
|
**Payload**
|
|
|
|
If you've configured a **Response Body** in the trigger of the other flow, this will be appended under this
|
|
`operationKey`. If no **Response Body** is configured, `null` is appended under this `operationKey`.
|
|
|
|
**More Details**
|
|
|
|
:::tip Flows for-loops
|
|
|
|
If you pass an array to the other flow, the other flow will run once for each item in the array.
|
|
|
|
:::
|