Конфигурация автоматизации

Конфигурация определяет порядок работы автоматизации. Редактор принимает YAML и JSON, проверяет известные поля и не пропускает опечатки в их названиях.

Размер конфигурации не должен превышать 256 КБ. Поддерживаются версии схемы 1 и 2. Версия 2 нужна для запуска по событиям Synchra24.

Верхний уровень

Поле	Обязательно	Назначение
version	да	Версия схемы: 1 или 2. Для событий нужен 2.
trigger	да	Ручной запуск, запуск по расписанию или по событию.
source	для простого режима без события	Один HTTP-источник данных. Для event не используется.
destination	для простого режима	Одно HTTP-назначение результата.
steps	для расширенного режима	Несколько источников и назначений.
transform	нет	Настройки JavaScript-обработчика.
retry	нет	Повтор отправки данных в назначение.
conditions	нет	Условия, которым должно соответствовать внутреннее событие.

Для ручного запуска и расписания используйте либо пару source + destination, либо массив steps. Для события входом служит его payload, поэтому укажите только destination или шаги назначений. Смешивать обычные поля и steps в одной автоматизации нельзя.

version

version: 1

Поле обязательно и позволяет системе однозначно интерпретировать конфигурацию после появления новых версий формата.

trigger

Ручной запуск

trigger:
  type: manual

Автоматизация выполняется по кнопке Запустить. Поля cron и timezone в этом режиме не используются.

Запуск по расписанию

trigger:
  type: schedule
  cron: "30 8 * * 1-5"
  timezone: Europe/Moscow

Поле	Обязательно	Значение
type	да	manual или schedule.
cron	для schedule	Пять полей cron: минута, час, день месяца, месяц, день недели.
timezone	нет	Название часового пояса IANA. По умолчанию Europe/Moscow.
event	для event	Название внутреннего события, например employee.late.

Примеры расписаний:

Задача	Cron
Каждый день в 00:00	0 0 * * *
Каждый день в 08:30	30 8 * * *
По будням в 21:00	0 21 * * 1-5
Каждый час	0 * * * *
В первый день месяца в 03:15	15 3 1 * *

Расписание рассчитывается в указанном часовом поясе, а время запусков внутри системы хранится в UTC.

Плановый запуск можно настроить не чаще одного раза в 30 минут. Например, */30 * * * * допустим, а */15 * * * * будет отклонён при проверке конфигурации. На сервере действует дополнительная защита: даже для старой конфигурации или повторной постановки в очередь два запуска по расписанию не начнутся с интервалом меньше 30 минут.

Один запуск по расписанию или событию может выполняться не более 60 секунд. В этот срок входят получение данных из всех источников, JavaScript-обработка, отправка во все назначения, задержки и повторные попытки. По истечении лимита выполнение останавливается и в истории появляется ошибка. Интервал 30 минут применяется только к триггеру schedule; ручные и проверочные запуски им не ограничиваются.

Запуск по событию

version: 2
trigger:
  type: event
  event: employee.late

В этом режиме входные данные уже содержатся в событии, поэтому source и шаги с kind: source указывать нельзя. Нужны только обработчик и одно или несколько назначений. Полный список событий и пример условий приведены в разделе Запуск по событиям Synchra24.

source

Источник — HTTP-адрес, из которого автоматизация получает данные.

source:
  type: http
  method: GET
  url: https://api.example.com/v1/orders
  headers:
    Authorization: "Bearer ${secrets.SOURCE_TOKEN}"
    Accept: application/json
  response:
    format: json
    encoding: utf-8

Поле	Обязательно	Значение
type	да	Сейчас поддерживается только http.
method	нет	HTTP-метод. Для источника по умолчанию используется GET.
url	да	Абсолютный адрес с http:// или https://.
headers	нет	До 50 HTTP-заголовков. В значениях можно использовать секреты.
body	нет	Тело запроса источника. Используется, если API получает фильтр через POST.
response	да	Правила чтения ответа.

Если задан body, он отправляется как JSON. Если принимающий API требует заголовок Content-Type: application/json, добавьте его в headers явно. Для обычного GET поле лучше не добавлять.

Источник считается успешным только при HTTP-статусе от 200 до 299.

response

response:
  format: xml
  encoding: windows-1251
  options:
    delimiter: ";"
    header: true

Поле	Обязательно	Значение
format	нет	json, xml, csv, tsv или text. Если поле пустое, формат определяется по Content-Type.
encoding	нет	utf-8 или windows-1251. По умолчанию UTF-8.
options.delimiter	нет	Один символ-разделитель для CSV. По умолчанию ;.
options.header	нет	Считать ли первую строку CSV заголовком. По умолчанию true.
options.root	нет	Для чтения не используется; применяется при создании XML.

Подробнее: Форматы данных.

transform

transform:
  type: javascript
  timeout_seconds: 2

Поле	Обязательно	Значение
type	нет	Пустое значение или javascript.
timeout_seconds	нет	Лимит выполнения функции от 1 до 5 секунд. По умолчанию 2 секунды.

Если type не указан, данные передаются в назначение без JavaScript-преобразования. Если указан javascript, во вкладке Обработчик должна быть функция transform(input, context).

destination

Назначение — HTTP-адрес, куда автоматизация отправляет итоговые данные.

destination:
  type: http
  method: POST
  url: https://receiver.example.com/v1/orders/import
  headers:
    Authorization: "Bearer ${secrets.DESTINATION_TOKEN}"
  request:
    format: json
    encoding: utf-8

Поле	Обязательно	Значение
type	да	Сейчас поддерживается только http.
method	нет	HTTP-метод. Для назначения по умолчанию используется POST.
url	да	Абсолютный HTTP- или HTTPS-адрес.
headers	нет	До 50 заголовков. Пользовательский Content-Type будет заменён типом выбранного формата.
request	да	Правила кодирования результата.

Назначение считается успешным при HTTP-статусе от 200 до 299. Тело ответа назначения не используется.

request

Структура совпадает с response:

request:
  format: csv
  encoding: windows-1251
  options:
    delimiter: ";"

Если формат не указан, результат отправляется как JSON.

retry

retry:
  attempts: 3
  delay_seconds: 10

Поле	Диапазон	Значение
attempts	от 0 до 5	Общее количество попыток отправки. Значения 0 и 1 означают одну попытку.
delay_seconds	от 0 до 3600	Пауза между попытками в секундах.

Повторы относятся к отправке в назначения. Ошибочный запрос к источнику не повторяется в рамках текущего запуска.

Полный пример YAML

version: 1

trigger:
  type: schedule
  cron: "0 2 * * *"
  timezone: Europe/Moscow

source:
  type: http
  method: GET
  url: https://accounting.example.com/export/employees
  headers:
    X-API-Key: "${secrets.ACCOUNTING_API_KEY}"
  response:
    format: xml
    encoding: windows-1251

transform:
  type: javascript
  timeout_seconds: 3

destination:
  type: http
  method: POST
  url: https://hr.example.com/api/employees/import
  headers:
    Authorization: "Bearer ${secrets.HR_TOKEN}"
  request:
    format: json
    encoding: utf-8

retry:
  attempts: 3
  delay_seconds: 15

Тот же пример в JSON

{
  "version": 1,
  "trigger": {
    "type": "schedule",
    "cron": "0 2 * * *",
    "timezone": "Europe/Moscow"
  },
  "source": {
    "type": "http",
    "method": "GET",
    "url": "https://accounting.example.com/export/employees",
    "headers": {
      "X-API-Key": "${secrets.ACCOUNTING_API_KEY}"
    },
    "response": {
      "format": "xml",
      "encoding": "windows-1251"
    }
  },
  "transform": {
    "type": "javascript",
    "timeout_seconds": 3
  },
  "destination": {
    "type": "http",
    "method": "POST",
    "url": "https://hr.example.com/api/employees/import",
    "headers": {
      "Authorization": "Bearer ${secrets.HR_TOKEN}"
    },
    "request": {
      "format": "json",
      "encoding": "utf-8"
    }
  },
  "retry": {
    "attempts": 3,
    "delay_seconds": 15
  }
}

Кнопка форматирования в редакторе приводит YAML или JSON к читаемому виду. Кнопка загрузки позволяет выбрать готовый файл .yaml, .yml или .json размером до 256 КБ.