mirror of
https://github.com/directus/directus.git
synced 2026-04-25 03:00:53 -04:00
Docs: Configuration > Data Flows (#13246)
* initial data flows outline * more details to data flows * minor tweaks * added basic explanation of variables, made other improvements * more lil updates * flows 70%, triggers 70%, operations 50% * added most media, operations info, and made small tweaks on flow and triggers * Revert "added most media, operations info, and made small tweaks on flow and triggers" This reverts commit3c35b8d728. * Revert "Revert "added most media, operations info, and made small tweaks on flow and triggers"" This reverts commiteadfb33969. * flows draft complete, not fully proof-edited Co-authored-by: Rijk van Zanten <rijkvanzanten@me.com>
This commit is contained in:
Eron Donevan Powell
committed by
GitHub
GitHub
parent
7d48be7531
commit
b379fd56c7
@@ -221,6 +221,24 @@ module.exports = {
|
||||
path: '/configuration/webhooks',
|
||||
title: 'Webhooks',
|
||||
},
|
||||
{
|
||||
type: 'page',
|
||||
path: '/configuration/flows/flows',
|
||||
title: 'Flows',
|
||||
collapsable: false,
|
||||
children: [
|
||||
{
|
||||
type: 'page',
|
||||
path: '/configuration/flows/triggers',
|
||||
title: 'Triggers',
|
||||
},
|
||||
{
|
||||
type: 'page',
|
||||
path: '/configuration/flows/operations',
|
||||
title: 'Operations',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: 'page',
|
||||
path: '/configuration/activity-log',
|
||||
|
||||
113
docs/configuration/flows/flows.md
Normal file
113
docs/configuration/flows/flows.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Flows
|
||||
|
||||
> Flows enable custom, event-driven data processing and task automation within Directus. Each Flow is composed of one
|
||||
> Trigger, followed by a series of Operations.
|
||||
|
||||
[[toc]]
|
||||
|
||||
<!--
|
||||
::: Before You Begin
|
||||
|
||||
[Learn Directus](/getting-started/learn-directus)
|
||||
|
||||
:::
|
||||
-->
|
||||
|
||||
## What's a Flow?
|
||||
|
||||
|
||||
|
||||
Each Flow begins with one Trigger, which defines the actions that start the Flow. Triggers can be some event or action
|
||||
within the app, an incoming webhook, a cron job, or manual click of a button. Please see the documentation on
|
||||
[Triggers](/configuration/flows/triggers) for more details.
|
||||
|
||||
Operations are the actions performed after the Trigger, which include things like creating new Items in a Collection,
|
||||
sending off emails, pushing _in-app_ notifications, or sending webhooks, just to name a few options. You can even set up
|
||||
divergent chains of Flow Operations, which execute conditionally, based on whether one Operation passed or failed. To
|
||||
ensure data is passed on as expected, a [console log](configuration/flows/operations/#log-to-console) is also included
|
||||
to help design and troubleshoot your Flows. Please see the documentation on
|
||||
[Operations](/configuration/flows/operations) for more details.
|
||||
|
||||
Once a Flow is triggered, a [Flow JSON Object](#the-flow-object) is created which stores data from the Trigger event.
|
||||
Then as each Operation in the flow executes, the data generated is added onto this Flow Object. Every Operation in a
|
||||
Flow has access to this Flow Object.
|
||||
|
||||
## Create a Flow
|
||||
|
||||
<video autoplay muted loop controls title="">
|
||||
<source src="https://cdn.directus.io/docs/v9/configuration/flows/flows/flows-20220603A/create-a-flow-20220603A.mp4" type="video/mp4" />
|
||||
</video>
|
||||
|
||||
To create a Flow, follow these steps:
|
||||
|
||||
1. Navigate to **"Settings > Flows"** and click <span mi btn>add</span> in the Page Header. A side menu will appear.
|
||||
2. Under **Flow Setup**, fill in a name for the Flow.\
|
||||
Optional: Set a status, material icon, description or color to help remember the Flow.
|
||||
3. Select your **Activity and Logs Tracking** preference as desired.\
|
||||
To learn more, please see [Activity](/reference/system/activity/) and [Logs](/#logs).
|
||||
4. Click <span mi btn>arrow_forward</span> to navigate to **Trigger Setup**, select a
|
||||
[Trigger](configuration/flows/triggers) type and configure as desired.
|
||||
5. Click <span mi btn>done</span> in the Menu Header and you will be taken to the Flow Grid Area.\
|
||||
A Trigger Panel will be on the Flow Grid.
|
||||
6. On the Trigger Panel, click <span mi>add</span> and the **Create Operation** side menu will open.
|
||||
7. Set a name, select the [Operation](configuration/flows/operations) type, and configure as desired.\
|
||||
The unique name will be converted into an Operation Key, used on the [Flow Object](#the-flow-object).\
|
||||
If no name is set, a name and key will be auto-generated.
|
||||
8. When done, click <span mi btn>done</span> in the Page Header to confirm and return to the Flow Grid Area.
|
||||
9. On the newly created Operation Panel:
|
||||
- Click <span mi icon>add</span> to add Operation after successful execution of the current Operation.
|
||||
- Click <span mi icon>remove</span> to add Operation after a failed execution of the the current Operation.
|
||||
10. Repeat steps 8-10 to create your Flow as desired.
|
||||
11. **Optional:** To edit a Trigger or Operation Panel, click <span mi icon>edit</span> and make edits as desired.
|
||||
12. **Optional:** To delete an Operation Panel, click <span mi icon>more_vert</span> and click
|
||||
<span mi icon dngr>delete</span>.
|
||||
|
||||
## The Flow Object
|
||||
|
||||
When a Flow is triggered, a JSON object is created to store all data generated within the Flow. When you create an
|
||||
Operation, a key is generated. This key is appended to the Flow Object when the Operation executes. It is used to add
|
||||
the associated Operation's data onto the Flows Object. As each Operation in the Flow executes, it has access to the Flow
|
||||
Object and therefore the data generated from preceding Operations.
|
||||
|
||||
The following JSON object is a simple example of a Flow with two Operations. The `$trigger`, `$last`, and
|
||||
`$accountability` keys are included on every Flow. An Operation key will be generated for each Operation that executes
|
||||
successfully.
|
||||
|
||||
<!--
|
||||
@TODO: Uncomment once Azzy's doc is live:
|
||||
For more details, see the API Reference for [Flows](reference/system/flows) and [Operations](reference/system/operations).
|
||||
-->
|
||||
|
||||
```JSON
|
||||
{
|
||||
"$trigger": {}, // Data generated by the Flow's Trigger.
|
||||
"$last": null, // Data from the last Operation in the flow, for easy access!
|
||||
"$accountability": {}, // Provides details on who/what tripped the Trigger and generated this Flow Object.
|
||||
"operation_key": { // The data (if any) generated by the first Operation.
|
||||
"some_nested_key": "Some nested value.",
|
||||
},
|
||||
"operation_key_2": null, // Value is null if no data was generated during an Operation.
|
||||
}
|
||||
```
|
||||
|
||||
### Flow Variables
|
||||
|
||||
The Flow Object keys serve as variables, allowing data access from every Flow Operation. Variables must be passed using
|
||||
the following double-moustache syntax. You can even use dot-notation to extract sub-nested values.
|
||||
|
||||
```JSON
|
||||
{
|
||||
"operation_key_3": {
|
||||
"user": "{{ $accountability.user }}",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Logs
|
||||
|
||||
<video autoplay muted loop controls title="">
|
||||
<source src="https://cdn.directus.io/docs/v9/configuration/flows/flows/flows-20220603A/logs-20220603A.mp4" type="video/mp4" />
|
||||
</video>
|
||||
|
||||
Logs, accessed from the Sidebar, store a log of information for each Flow execution. Each log will display information
|
||||
from Triggers as well as each Operation.
|
||||
168
docs/configuration/flows/operations.md
Normal file
168
docs/configuration/flows/operations.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Operations
|
||||
|
||||
> Operations are the actions performed after the Flow is triggered. Whether you need to access and create Data within
|
||||
> Directus, send information off to outside services, create time-oriented Flows, set conditional logic or even trigger
|
||||
> other Flows, these simple but powerful tasks can make it happen.
|
||||
|
||||
[[toc]]
|
||||
|
||||
:::tip Before You Begin
|
||||
|
||||
Please be sure to read the documentation on [Flows](/configuration/flows/flows) and [Triggers](flows/triggers).
|
||||
|
||||
:::
|
||||
|
||||
## Condition
|
||||
|
||||
|
||||
|
||||
Routes to the next success or failure Operation based on some conditional `if` / `else` logic defined by a Filter query.
|
||||
That means if the query condition is met, the Flow will move forward with the success Operation. Otherwise, the failure
|
||||
Operation will be initiated.
|
||||
|
||||
- **Condition Rules** — Create conditions with [Filter Rules](/configuration/filter-rules).
|
||||
|
||||
## Create Data
|
||||
|
||||
|
||||
|
||||
Creates some Item(s) in a Collection.
|
||||
|
||||
- **Collection** — Use the dropdown to select a Collection to create Items in.
|
||||
- **Permissions** — Set the scope of permissions used for this Operation.
|
||||
- **Emit Events** — Toggle whether the event is emitted.
|
||||
- **Payload** — Create Item(s) in a Collection. To learn more, see [API > Items](reference/items/).
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure the Operation is scoped with the [permissions](configuration/users-roles-permissions) necessary to create
|
||||
Items.
|
||||
|
||||
:::
|
||||
|
||||
## Delete Data
|
||||
|
||||
|
||||
|
||||
Deletes some Item(s) from a Collection by ID or query.
|
||||
|
||||
- **Permissions** — Set the scope of permissions used for this Operation.
|
||||
- **Collection** — Use the dropdown to set the Collection to delete Items from.
|
||||
- **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](/configuration/filter-rules).
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure the Operation is scoped with the [permissions](configuration/users-roles-permissions) necessary to delete
|
||||
Items.
|
||||
|
||||
:::
|
||||
|
||||
## Read Data
|
||||
|
||||
|
||||
|
||||
Reads Item(s) form a Collection and adds them onto the Flow Object. You may select Items by their ID or run a query to
|
||||
select the Items you wish to update.
|
||||
|
||||
- **Permissions** — Set the scope of permissions used for this Operation.
|
||||
- **Collections** — Select the Collection to read Items from.
|
||||
- **IDs** — Input ID for Item(s) you wish to read and press enter. Click the ID to remove.
|
||||
- **Query** — Select Items with a query. To learn more, see [Filter Rules](/configuration/filter-rules).
|
||||
|
||||
## Update Data
|
||||
|
||||
|
||||
|
||||
Updates Item(s) in a Collection. You may select Items by their ID or run a query to select the Items you wish to update.
|
||||
|
||||
- **Permissions** — Defines Role that this Operation will inherit permissions from.
|
||||
- **Collections** — Select the Collection to read Items from.
|
||||
- **IDs** — Input ID for Item(s) you wish to read and press enter. Click the ID to remove.
|
||||
- **Payload** — Updates Item(s) 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](/configuration/filter-rules).
|
||||
|
||||
## Log to Console
|
||||
|
||||
|
||||
|
||||
Output something to the console. This will appear in both the server side and in-app Sidebar Console Log. This is a key
|
||||
tool to help troubleshoot Flow configuration.
|
||||
|
||||
- **Message** — Sets a [log message](#configuration/flows/flows/logs).
|
||||
|
||||
:::tip
|
||||
|
||||
This will be delivered to your in-app Log Panel and also logged to the server-side console.
|
||||
|
||||
:::
|
||||
|
||||
## Send Email
|
||||
|
||||
|
||||
|
||||
Sends email(s). Flow Object keys can be used as variables. This means an array of emails from a previous step in Flows
|
||||
could be used.
|
||||
|
||||
- **To** — Sets email addresses. Hit `↵` to save the email. Click an email to remove it.
|
||||
- **Subject** — Set subject line.
|
||||
- **Body** — Provides WYSIWYG editor to create email body.
|
||||
|
||||
:::tip
|
||||
|
||||
If you are testing out this Operation locally from `localhost:8080`, be sure to check your spam box as your email
|
||||
provider may send it there automatically.
|
||||
|
||||
:::
|
||||
|
||||
## Send Notification
|
||||
|
||||
|
||||
|
||||
Sends a notification to an app user.
|
||||
|
||||
- **Users** — Defines a User by their primary key UUID. Use [Flow keys](/configuration/flows/flows/#the-flow-object) to
|
||||
set this dynamically.
|
||||
- **Permissions** — Defines Role that this Operation will inherit permissions from.
|
||||
- **Title** — Sets the notification title.
|
||||
- **Message** — Sets the main body of the notification.
|
||||
|
||||
## Webhook / Request URL
|
||||
|
||||
|
||||
|
||||
Makes a request to another URL.
|
||||
|
||||
- **Method** — Choose to make a GET, POST, PATCH, DELETE, or other type of request.
|
||||
- **URL** — Define the URL to send request to.
|
||||
- **Headers** — Create new `header:value` to pass along with the request.
|
||||
- **Request Body** — Set request body data. Use any string or JSON.
|
||||
|
||||
## Sleep
|
||||
|
||||
|
||||
|
||||
Pauses Operation Execution on the Flow for a given amount of milliseconds. Then continues to the next Operation.
|
||||
|
||||
- **Milliseconds** — Define the number of milliseconds to pause.
|
||||
|
||||
## Transform Payload
|
||||
|
||||
|
||||
|
||||
Transform Payload simply creates a new key on the Flow Object with nested JSON data. This provides a clean space where
|
||||
you can combine data from multiple Flow keys all into one object. So for example, if you needed to use the same data
|
||||
multiple times _(e.g. send it in a web request and also use it to create an Item in a Collection)_, you can combine the
|
||||
data one time with Transform Payload, then use its Operation key again and again.
|
||||
|
||||
- **JSON** — Define JSON to insert into the Flow Object.
|
||||
|
||||
## Trigger Flow
|
||||
|
||||
|
||||
|
||||
This Operation starts another Flow and passes data to it. It should be used in combination with the
|
||||
[Another Flow](/configuration/triggers/#another-flow) Trigger.
|
||||
|
||||
- **Flow** — Define a Flow by its primary key UUID.
|
||||
- **Payload** — Define JSON to insert into the Flow Object.
|
||||
59
docs/configuration/flows/triggers.md
Normal file
59
docs/configuration/flows/triggers.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Triggers
|
||||
|
||||
> Each Flow is triggered by some internal or external event.
|
||||
|
||||
[[toc]]
|
||||
|
||||
## Event Hook
|
||||
|
||||
|
||||
|
||||
Event Hooks are triggered by platform or data events. The logic is based on [Custom API Hooks](/extensions/hooks/).
|
||||
|
||||
- **Type** — Choose the type of Event Hook:
|
||||
- **Filter (Blocking)** — Fires "blocking" right before the database transaction is committed, allowing you to tweak
|
||||
the payload or even outright prevent completion.
|
||||
- **Action (Non-Blocking)** — Does not block anything. Therefore, this is mostly useful for doing things in response
|
||||
to an event, without slowing down the API.
|
||||
- **Scope** — Set the specific events which trip this Trigger.
|
||||
- **Collections** — Set the Collections which trip this Trigger.
|
||||
- **Response Body** — Send Data of last Operation, all Flow Object data, or Flow key.
|
||||
|
||||
## Webhook
|
||||
|
||||
|
||||
|
||||
Triggered by an incoming HTTP request to: `/flows/trigger/:this-webhook-trigger-id`.
|
||||
|
||||
- **Method** — Choose to make a GET, POST, PATCH, DELETE or other request from the dropdown.
|
||||
- **Asynchronous** — Toggle whether or not the Trigger responds asynchronously.
|
||||
- **Response Body** — Choose to send Data of last Operation, all Flow Object data, or some other key from the Flow
|
||||
object.
|
||||
|
||||
## Schedule
|
||||
|
||||
|
||||
|
||||
This Trigger allows you to create Data at scheduled intervals, via 6-point cron job syntax.
|
||||
|
||||
- **Interval** — Set the cron job interval to schedule when the Flow triggers.
|
||||
|
||||
## Another Flow
|
||||
|
||||
|
||||
|
||||
This Trigger executes a Flow via the [Trigger Flow](/configuration/flows/operations/#another-flow) Operation, allowing
|
||||
you to chain Flows together.
|
||||
|
||||
- **Response Body** — Select data to return in the response to Trigger Flow.
|
||||
|
||||
## Manual
|
||||
|
||||
|
||||
|
||||
Triggers on manual click of a button. Based on your **Location** configuration, a **Flows** menu will appear in the
|
||||
Sidebar of the Collection Page and/or Item Page. This will contain a button which starts the Flow when clicked.
|
||||
|
||||
- **Collections** — Choose the Collection(s) to add in this Button on to.
|
||||
- **Location** — Choose to add the button into the Item Page, Collection Page, or both.
|
||||
- **Asynchronous** — Toggle whether or not the Flow executes asynchronously.
|
||||
Reference in New Issue
Block a user