directus/docs/app/flows/triggers.md

description, readTime

description	readTime
A Trigger initiates a Flow on some internal or external event, such as an in-app activity, incoming webhook, cron job, execution of Operation(s) from other Flows, and beyond!	3 min read

Triggers

A trigger defines the event that starts your flow. This could be from an internal or external activity, such as changes to data, logins, errors, incoming webhooks, cron jobs, operations from other flows, or even the click of a button within the Data Studio.

::: tip Before You Begin

Please be sure to read the overview documentation on Flows.

:::

Event Hook

Event Hooks are triggered by events within the platform. The logic is based on Custom API Hooks. Any data generated by the event will be nested in the $trigger.

• Type — Choose the type of event hook:
  • Filter (Blocking) — This pauses the transaction and passes the payload to your flow, allowing you to validate or transform payload or even prevent the event transaction.
  • Action (Non-Blocking) — Actions do not block the event. A non-blocking action is mostly useful for completing tasks in response to an event, without modifying the event or slowing the API.
• Scope — Set the types of events that trip this trigger.
• Collections — Set the collections whose events trip this trigger.
• Response Body — This is optional. Its also only for Filter (Blocking) events. Defines data to replace the event's original payload. Choose to return:
  • Data of Last Operation — Replaces event payload with value from $last.
  • All Data — Replaces event payload with the entire data chain.
  • Other — Replaces event payload with value from an <operationKey>.

::: tip Events with Multiple Items

If you create items in a single request, the Flow will trigger once for each and every item. If you create three items, the flow runs three separate times. On each run, just one item will be in the payload.

:::

Filters

A Filter will halt the event transaction, copy the event payload into the flow, let the whole flow run, optionally replace the original payload by configuring Response Body, then resume the event's transaction to the database.

For example, let's say you configure the scope to be item.create.

• A request to create an item is sent to Directus.
• The create item event halts.
• The event's payload is copied into the $trigger of the flow.
• The flow runs.
• Optional: If you defined a Response Body, this replaces the event's payload.
• The event transaction is committed or cancelled, based on your flow's logic.

::: tip Response Body

If no Response Body is configured, the original payload will not be modified, but you'd still have the ability to cancel the transaction.

:::

::: tip Cancelling Transactions

To completely cancel a transaction, you'll need to throw an error within a script operation or end the flow on a failure path.

:::

Actions

An Action lets the event commit its transaction to the database without waiting for the flow to finish. Therefore, Actions give you a more performant API, but you have no ability to validate or transform the payload before the transaction is committed to the database. However, a copy of the payload is still added into $trigger to use as desired.

For example, let's imagine once more that you configure the scope to be item.create.

• A request to create an item is sent to Directus.
• The create item event is transacted.
• The event's payload is copied into the $trigger of the flow.
• The flow runs.

To recap, Filters let you modify the original payload of an event but block the API until the flow finishes. Actions still provide the payload to the flow, but don't let you modify it before transaction; so you get a faster API but no control over the event transaction.

Webhook

Triggers on an incoming HTTP request to: /flows/trigger/:this-webhook-trigger-id which you can copy from the webhook trigger panel.

• Method — Choose whether the flow will be triggered by a GET or POST request from the dropdown.
• Asynchronous — Toggle whether or not the trigger responds asynchronously.
• Response Body — Optional. Defines data to return as a response. Choose to return:
  • Data of Last Operation — Responds with value from $last.
  • All Data — Responds with the entire data chain.
  • Other — Responds with value from an <operationKey>.
• Cache — Choose whether responses to GET requests should be stored and served from cache or the cache should be bypassed.

::: tip Response Body

If no data is defined in Response Body, the response is empty.

:::

::: tip Asynchronous

If Asynchronous is enabled, the flows system will immediately resolve/respond to the request without returning a Response Body, which frees up the API immediately. If it is disabled, the flows system will wait for the flow to finish and return whatever value is in Response Body. This slows the API, but lets you send data.

:::

Schedule (CRON)

This trigger enables 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.

Syntax Explanation

 ┌────────────── second (0-59)
 │ ┌──────────── minute (0-59)
 │ │ ┌────────── hour (0-23)
 │ │ │ ┌──────── day of month (1-31)
 │ │ │ │ ┌────── month (1-12)
 │ │ │ │ │ ┌──── day of week (0-7)
 │ │ │ │ │ │
 │ │ │ │ │ │
 * * * * * *

Another Flow

This trigger executes by the trigger flow operation, allowing you to chain flows.

• Response Body — Optional. Defines data to return and append under the <operationKey> of trigger flow operation that tripped the trigger. Choose to return:
  • Data of Last Operation — Responds with value from $last.
  • All Data — Responds with the entire data chain.
  • Other — Responds with value from an <operationKey>.

::: tip Flows for-loops

If you pass an array to this trigger, it will run once for each item in the array.

:::

Manual

This Trigger starts your flow on a manual click of a button within the Data Studio. When you use this trigger, a Flows menu containing a button will appear in the sidebar of the specified collection page(s) and/or its item pages.

The manual trigger must take in item ID(s) before you can click it. So on the collection page, the button will be grayed out until you select some number of items. From the item page, the current item's ID is passed in automatically. These item IDs are passed in to $trigger.

• Collections — Choose the Collection(s) to add the button to.
• Location — Choose to display the button on the Item Page, Collection Page, or both.
• Asynchronous — Toggle whether the Flow executes asynchronously. If enabled, you can immediately trigger the flow again. If not, you must wait for the flow to complete to use it again.
• Collection Page (Requires Selection) — Toggle whether a selection is required in the Collection Page to trigger.
• Require Confirmation - Toggle whether a confirmation dialog will be shown before the flow is executed.

After the operation runs, a toast notification will appear in your sidebar indicating whether the flow ran successfully.

Confirmation Dialog

If enabled, a confirmation dialog will be shown in a modal before the flow is executed. There are further options to set up a confirmation dialog.

• Confirmation Description - Text shown at the top of the modal.
• Confirmation Input Fields - Set up one or more inputs to be filled by users before executing the flow.

Each input field can have its own data type, interface, and display options. Some convenience options are also provided to immediately alter the user input (such as trimming whitespace and slugifying text).

Data provided by users when triggering a manual flow with a confirmation dialog will be accessible in $trigger.body in the data chain.