Канфігурацыя аўтаматызацыі
Даведнік YAML і JSON: расклад, Сістэмныя падзеі і падзеі сэрвісаў, крыніцы, прызначэння і паўторы.
Пераклад пакуль недаступны. Паказаны арыгінал.
Конфигурация определяет порядок работы автоматизации. Редактор принимает YAML и JSON, проверяет известные поля и не пропускает опечатки в их названиях.
Размер конфигурации не должен превышать 256 КБ. Поддерживаются версии схемы 1 и 2. Версия 2 нужна для запуска по событиям Synchra24.
Верхний уровень
| Поле | Обязательно | Назначение |
|---|---|---|
version |
да | Версия схемы: 1 или 2. Для событий нужен 2. |
trigger |
да | Ручной запуск, запуск по расписанию или по событию. |
source |
для простого режима без события | Один HTTP-источник или артефакт. Для event не используется. |
destination |
для простого режима | Одно HTTP-назначение, артефакт или подтверждённый чат MAX. |
steps |
для расширенного режима | Несколько источников и назначений. |
transform |
нет | Настройки JavaScript-обработчика. |
retry |
нет | Повтор отправки данных в назначение. |
conditions |
нет | Условия для входных данных, события и подключённых артефактов. |
artifacts |
нет | Алиасы имён артефактов компании, доступных на всех этапах запуска. |
Для ручного запуска и расписания используйте либо пару 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 или event. |
cron |
для schedule |
Пять полей cron: минута, час, день месяца, месяц, день недели. |
timezone |
нет | Название часового пояса IANA. По умолчанию Europe/Moscow. |
event |
для event |
Точное имя системного события (employee.late) или полный код события сервиса (custom.service_42.report_ready). |
Примеры расписаний:
| Задача | 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 * * * * будет отклонён при проверке конфигурации.
Один запуск по расписанию или событию может выполняться не более 60 секунд. В этот срок входят получение данных из всех источников, JavaScript-обработка, отправка во все назначения, задержки и повторные попытки. По истечении лимита выполнение останавливается и в истории появляется ошибка. Интервал 30 минут применяется только к триггеру schedule; ручные и проверочные запуски им не ограничиваются.
Запуск по событию
version: 2
trigger:
type: event
event: employee.late
В этом режиме входные данные уже содержатся в событии, поэтому source и шаги с kind: source указывать нельзя. Нужны только обработчик и одно или несколько назначений. Полный список событий и пример условий приведены в разделе Запуск по событиям Synchra24.
Для события собственного сервиса укажите полный код из вкладки События,
например custom.service_42.report_ready. В редакторе доступен выбор события
из каталога сервисов компании. Сам сервис вызывает локальное имя report_ready
через synchra.emitEvent; этот вызов не создаёт определение события.
Регистрация, ограничения и полный пример конфигурации:
Пользовательские события сервисов.
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 или artifact. |
method |
нет | HTTP-метод. Для источника по умолчанию используется GET. |
url |
для HTTP | Абсолютный адрес с http:// или https://. |
headers |
нет | До 50 HTTP-заголовков. В значениях можно использовать секреты. |
body |
нет | Тело запроса источника. Используется, если API получает фильтр через POST. |
response |
для HTTP | Правила чтения ответа. |
Если задан 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-сервис, артефакт или подтверждённый чат MAX.
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 или artifact. |
method |
нет | HTTP-метод. Для назначения по умолчанию используется POST. |
url |
для HTTP | Абсолютный HTTP- или HTTPS-адрес. |
headers |
нет | До 50 заголовков. Пользовательский Content-Type будет заменён типом выбранного формата. |
request |
для HTTP | Правила кодирования результата. |
body |
нет | Явное тело HTTP-назначения; без него отправляется результат transform. |
Назначение считается успешным при HTTP-статусе от 200 до 299. Тело ответа назначения не используется.
Назначение artifact
Вместо HTTP-запроса результат можно сохранить в Synchra24:
destination:
type: artifact
name: warehouse.stock
Для этого назначения допускаются только type и name. HTTP-поля не указываются. Подробнее: Артефакты автоматизаций.
Отправка в MAX через общего бота
В облачной Synchra24 можно отправлять уведомления через общего бота платформы. Для этого откройте Администратор → Автоматизации → Чаты MAX. Нужны лицензия API-интеграция и право управления интеграциями. Если окно сообщает, что бот ещё не подключён, сохраните автоматизацию выключенной и вернитесь к настройке после подключения бота оператором.
Добавьте указанного в окне бота в групповой чат или канал MAX с правом отправки сообщений. Отправьте в этом чате команду /chatid и скопируйте полученный ID. В Synchra24 укажите имя подключения и ID, нажмите Отправить код в MAX, затем введите шесть цифр из сообщения бота. Код действует 10 минут; после пяти неверных попыток потребуется новый. Доступно до пяти запросов кода за час на компанию и на чат, включая неудачные отправки. В компании может быть до 20 подключений.
Если готовое расширение отправляет уведомления в MAX, перед его включением проверьте подключение в Чаты MAX. Установка расширения сама по себе не подключает чат. Если список подключений не загрузился, повторите открытие раздела; не создавайте дубликаты автоматизации.
Для готовых расширений оставьте имя default. Если уведомления должны идти в разные чаты, создайте подключения с разными именами и выберите нужное имя в конфигурации. Токен общего бота вводить и передавать продавцу не нужно. Сведения о подключениях доступны только внутри своей компании.
Для разработчика автоматизации назначение выглядит так:
destination:
type: max
name: default
В этом назначении допустимы только type и name. ID чата и токен в коде не задаются. Обработчик возвращает простой текст до 4000 символов. Допускается одна строка из одной или двух кнопок-ссылок на разделы текущей компании в облачной веб-версии:
function transform(input, context) {
return {
text: 'В Synchra24 появился новый инцидент.',
attachments: [{
type: 'inline_keyboard',
payload: {buttons: [[{
type: 'link', text: 'Открыть инциденты',
url: 'https://app.synchra24.com/activity/' + context.provider_id + '/incidents'
}]]}
}]
};
}
Проверочный запуск показывает результат обработчика без отправки в MAX. Перед включением требуется подтверждённый чат. После реального события проверьте сообщение и историю автоматизации. Успех означает подтверждение API MAX, а не прочтение человеком. Для MAX повторная отправка автоматически не выполняется даже при настройке retry: неопределённый ответ может означать, что сообщение уже отправлено. Проверяйте чат перед повторными действиями.
Чтобы остановить уведомления, выключите автоматизацию или удалите её подключение в Чаты MAX. Если это имя используют несколько автоматизаций, отправка остановится у каждой из них. Уже отправленные сообщения не удаляются. После удаления бота из чата подключение отзывается; для повторной работы подтвердите чат заново. Замена общего бота также требует нового подтверждения. Ссылки на отдельные коробочные серверы этим назначением не поддерживаются.
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 | Пауза между попытками в секундах. |
Повторы относятся к отправке в HTTP-назначения. Для общего бота MAX автоматических повторов нет. Ошибочный запрос к источнику не повторяется в рамках текущего запуска.
Полный пример 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 КБ.
Входные артефакты на всех этапах
Подключите artifacts: {settings: service.settings} в корне конфигурации. Значения доступны в source, conditions, transform и destination. Источник type: artifact с name возвращает сохранённое значение; HTTP поддерживает ${artifacts.settings.field} в URL, заголовках и JSON-теле. В steps назначение может выбрать input: ${artifacts.settings}. Условия используют path: artifacts.settings.field или input.field; value может ссылаться на подключённый артефакт. В обработчике читайте context.artifacts.settings.
Входные значения загружаются один раз на начало запуска, включая проверочный. При отсутствии артефакта запуск завершается ошибкой. Для событий источник остаётся конвертом события, но блок artifacts работает так же. Полный пример, правила типов, ограничения и ошибки — в артефактах автоматизаций.
Импорт и экспорт ZIP-шаблона автоматизации
В веб-администраторе откройте Автоматизации → Из ZIP-шаблона. Загрузите пакет и проверьте показанные параметры: идентификатор и версию шаблона, тип запуска, ссылки на секретные переменные, артефакты и событие. Перед созданием можно изменить название. Для импорта нужны доступ к администратору, лицензия API и admin_edit_provider_integrations; лицензия AI не нужна.
Кнопка Создать автоматизацию добавляет новую выключенную запись. Существующие автоматизации не заменяются, даже если имя или идентификатор шаблона совпадают. Код, HTTP-запросы и назначения при импорте не выполняются; расписание и события не начинают запускать pipeline. В редакторе проверьте адреса, часовой пояс, секретные переменные, артефакты и код события текущей компании. Затем выполните нужные проверки и отдельно включите автоматизацию.
Стандартная кнопка скачивания в шапке редактора — Экспортировать ZIP-шаблон автоматизации — упаковывает текущие конфигурацию, обработчик, название и описание, включая несохранённые правки. Экспорт не сохраняет изменения в автоматизации и не запускает её.
Формат пакета
automation.json
pipeline.yaml
transform.js
{
"format": "synchra.automation-template",
"schema_version": 1,
"template": {
"id": "com.example.exchange",
"version": "1.0.0",
"description": "Обмен данными с учётной системой"
},
"automation": {
"name": "Обмен данными",
"description": "Получить данные, преобразовать и сохранить результат"
},
"files": {
"pipeline": "pipeline.yaml",
"transform": "transform.js"
}
}
schema_version — версия формата ZIP; template.version — версия конкретного шаблона; version внутри YAML — версия схемы pipeline. Эти три значения имеют разное назначение. Экспорт редактора использует локальный идентификатор local.automation и версию 1.0.0; для распространения задайте собственные значения. Идентификатор — 3–128 строчных латинских букв, цифр, точек, _ или -, начинается с буквы; версия имеет вид 1.0.0, допускается суффикс -beta.1.
automation.name обязателен: от 2 символов до 100 байт UTF-8. automation.description необязателен, до 4000 символов. Описание шаблона — до 2000 символов. Файлы в files обязательны: конфигурация .yaml, .yml или .json и отдельный обработчик .js. Для pipeline без JavaScript-преобразования оставьте файл обработчика пустым. Поле transform.script не нужно: код хранится в отдельном файле, как в редакторе.
Допускаются вложенные каталоги и одна общая папка с automation.json. Пути считаются относительно конфигурации пакета. Можно добавить README.md, LICENSE и LICENSE.txt; служебные файлы macOS игнорируются. Другие файлы не импортируются.
Доступность и ограничения
ZIP — до 1 МиБ, automation.json — до 64 КиБ, конфигурация и обработчик — до 256 КиБ каждый. Всего до 32 записей вместе с каталогами и до 640 КиБ суммарного заявленного распакованного размера. Требуется UTF-8. Поддерживается обычный ZIP с STORE/DEFLATE без пароля, ZIP64, нескольких томов и символических ссылок. Нельзя использовать абсолютные пути, .., обратные слеши и дублирующиеся имена. Проверяются фактические размеры и CRC, распаковка ограничена даже при неверном размере в ZIP-каталоге.
Перед созданием система проверяет архив и настройки автоматизации. Если найдена ошибка, запись не создаётся: можно исправить пакет и выбрать его повторно, не закрывая окно. Отдельный файл YAML или JSON загружается кнопкой загрузки конфигурации в редакторе.
Значения секретных переменных из хранилища, содержимое артефактов, история запусков, идентификаторы записей и авторов не экспортируются. В конфигурации остаются ссылки ${secrets.NAME}, имена артефактов и код события. Показанный список артефактов включает чтение и назначения: входной артефакт должен существовать, а артефакт-назначение будет создан обычным успешным запуском. Такие зависимости не создаются автоматически. Для события сервиса проверьте и при необходимости выберите код сервиса именно этой компании.
Исходники экспортируются без редактирования. Если адрес, идентификатор компании или секретное значение прописаны прямо в YAML или JavaScript, они останутся в файлах. До передачи архива замените секретные значения ссылками на переменные. Флаг enabled, provider_id, секретные значения и другие поля установленной записи в automation.json не допускаются.
ZIP-шаблон или магазин
ZIP-шаблон создаёт отдельную копию автоматизации. После импорта её нужно настроить для своей компании; обновления продавца к такой копии не привязываются.
Если нужны готовые продукты с публикациями и обновлениями, используйте магазин расширений.