seomix.

Как работать с Flow в Directus

Как работать с Flow в Directus

В Directus Flow — это встроенная автоматизация: у него есть один trigger, дальше идёт цепочка operations, а между шагами передаётся общий data chain. Идея простая: что-то произошло → Flow запустился → несколько шагов обработали данные → при необходимости что-то записали, отправили или вернули обратно. (directus.io)

Как это понимать на практике:

  1. Trigger — что запускает Flow. В актуальной документации Directus есть 5 типов trigger: event hook, webhook, schedule (CRON), another flow и manual. То есть flow можно запускать по событию в коллекции, по входящему HTTP-запросу, по расписанию, из другого flow или вручную из Studio. (directus.io)

  2. Operations — шаги внутри сценария. Operations — это отдельные действия: проверка условия, преобразование данных, вызов другого flow, работа с данными, отправка наружу и т.д. Directus прямо описывает их как building blocks потока. (directus.io)

  3. Data chain — общий JSON-контекст всего выполнения. В начале выполнения Directus создаёт объект данных, куда кладёт $trigger, $accountability, $env и $last. После выполнения каждого operation его результат добавляется под ключом этого operation, а $last всегда указывает на результат последнего выполненного шага. (directus.io)

Самая важная мысль для работы с Flow: ты не “передаёшь переменные вручную” между шагами, а читаешь их из data chain. Например, можно ссылаться на значения через шаблоны вроде {{ $trigger.payload }}, {{ $accountability.user }} или {{ myOperation.result }}. Directus поддерживает dot notation и индексацию массивов. (directus.io)

Какие trigger’ы использовать

Event Hook Подходит, когда нужно реагировать на события внутри Directus: создание, обновление, удаление, логин и подобное. У него есть два режима:

  • Filter (Blocking) — останавливает транзакцию, даёт flow обработать payload, при необходимости изменить его или вообще отменить операцию.
  • Action (Non-Blocking) — не блокирует событие; подходит для побочных действий, вроде уведомлений или логирования. (directus.io)

Это ключевое различие. Если тебе нужно провалидировать данные до записи — выбирай blocking filter. Если нужно после сохранения отправить webhook, письмо или создать лог — обычно лучше non-blocking action. Это следует из того, как Directus описывает поведение этих режимов. (directus.io)

Webhook Нужен, когда внешний сервис должен вызвать твой flow через HTTP. Можно настроить GET или POST, синхронный или асинхронный ответ, и выбрать, что возвращать в response body: $last, весь data chain или конкретный operation. (directus.io)

Schedule (CRON) Используется для задач по расписанию: ночная синхронизация, чистка данных, рассылки, отчёты. Directus относит его к штатным типам триггеров. (directus.io)

Another Flow Позволяет строить композицию: один flow вызывает другой. Это полезно, когда хочется вынести общую логику в переиспользуемый сценарий. Directus прямо указывает, что этот trigger выполняется через operation вызова другого flow. (directus.io)

Manual Запуск вручную из Data Studio. Можно даже включить confirmation dialog и собрать пользовательский ввод; эти данные потом будут доступны в $trigger.body. (directus.io)

Как обычно собирают Flow

Базовый шаблон почти всегда такой:

Trigger → Condition → действие/действия → логирование/ответ

Например, сценарий: “При создании заказа со статусом paid отправить данные во внешний сервис”

  • Trigger: Event Hook
  • Type: Action (Non-Blocking)
  • Scope: событие создания/обновления нужной коллекции
  • Дальше Condition: проверить, что status = paid
  • Если условие true — выполнить нужную operation
  • Если false — закончить flow без действий

Почему так: condition в Directus строит ветвление через success/reject path, а rules валидируются через Filter Rules. Если условие не выполнено, поток уходит по reject path. (directus.io)

Как работать с Condition

Condition — это развилка. Она не генерирует полезные данные сама по себе, а определяет, по какой ветке пойдёт выполнение. Важный нюанс из документации: если поле, на которое ссылается правило, отсутствует в payload, а не равно null, operation уходит по reject path. Это частая причина “почему условие не сработало”. (directus.io)

То есть если ты проверяешь что-то вроде:

{{ $trigger.payload.status }}

убедись, что status действительно есть в payload этого trigger. Для event hooks payload очень зависит от типа события и момента выполнения. Например, для blocking flow на items.created у объекта ещё может не быть id, потому что запись ещё не создана. (directus.io)

Как работать с Run Script

Run Script нужен, когда no-code логики уже мало. В Directus он выполняется в изолированном sandbox, принимает data chain и возвращает результат, который попадёт под ключ этого operation. При этом у скрипта нет доступа к файловой системе и нет возможности делать network requests. (directus.io)

Пример идеи:

module.exports = function (data) {
  return {
    isVip: data.$trigger.payload.total > 1000,
    customerId: data.$trigger.payload.customer
  };
};

После этого в следующих шагах можно ссылаться на:

{{ myScript.isVip }}
{{ myScript.customerId }}

Ещё один важный момент: если Run Script выбрасывает ошибку, выполнение flow останавливается; а если это blocking event hook, ошибка отменяет исходную транзакцию в БД. (directus.io)

Как читать data chain без боли

Самые полезные ключи:

  • $trigger — что пришло от trigger: payload, headers, body, токены и т.п.
  • $accountability — кто/что запустил flow: user, role, ip и прочее
  • $env — разрешённые переменные окружения из FLOWS_ENV_ALLOW_LIST
  • $last — результат последнего operation (directus.io)

Практическое правило:

  • нужно обратиться к исходному событию → смотри $trigger
  • нужен пользователь, от имени которого всё идёт → смотри $accountability
  • нужен результат предыдущего шага → чаще всего $last
  • нужен конкретный результат конкретного шага → обращайся по ключу operation

Первый полезный flow, который стоит сделать

Вариант: валидация slug перед сохранением статьи

Задача: не давать сохранить статью без slug.

Конфигурация:

  • Trigger: Event Hook
  • Type: Filter (Blocking)
  • Collection: posts
  • Scope: создание/обновление
  • Operation: Condition
  • Проверка: slug существует и не пустой
  • Если reject — отменить транзакцию

Почему это хороший первый кейс: он сразу показывает разницу между blocking и non-blocking flow и даёт почувствовать, что flow может не только “реагировать”, но и влиять на запись данных. Документация Directus прямо говорит, что blocking filter может валидировать payload, заменить его или предотвратить транзакцию. (directus.io)

Вариант: уведомление после создания записи

Задача: после создания лида отправить данные во внешний сервис.

Конфигурация:

  • Trigger: Event Hook
  • Type: Action (Non-Blocking)
  • Collection: leads
  • Operation 1: Condition — проверить, что email заполнен
  • Operation 2: отправка/вызов интеграции
  • Operation 3: логирование результата

Такой flow не тормозит запись в Directus, потому что trigger работает как action. (directus.io)

Что чаще всего ломает flow

1. Неправильное ожидание структуры payload У разных trigger payload разный. Нельзя вслепую писать {{ $trigger.payload.id }} и надеяться, что это поле всегда есть. Особенно в blocking flows на create. (directus.io)

2. Путаница между $last и конкретным operation key $last меняется после каждого шага. Если в середине добавил ещё одну operation, ссылка на $last уже может указывать не туда. Для стабильности в важных местах лучше ссылаться на конкретный operation key. Это следует из описания $last в data chain docs и логах flow. (directus.io)

3. Использование Condition по полям, которых нет Если поля нет в payload, condition уйдёт в reject path. (directus.io)

4. Попытка делать HTTP-запросы внутри Run Script В sandbox Directus это нельзя. Для интеграций наружу надо использовать подходящие operations, а не надеяться на fetch внутри script. (directus.io)

5. Отсутствие логов Directus хранит логи выполнения flow и показывает отдельно trigger/options/payload/accountability и payload каждого operation. Это лучший способ дебажить, что реально пришло и что реально вернул каждый шаг. (directus.io)

--

Если совсем кратко

Чтобы работать с Flows в Directus, тебе нужно запомнить 4 вещи:

  • Trigger запускает сценарий. (directus.io)
  • Operations выполняют шаги сценария. (directus.io)
  • Data chain хранит всё, что пришло и что вернули шаги. (directus.io)
  • Logs — главный инструмент отладки. (directus.io)

Теги:

  • Directus
  • Flow
  • Headless CMS