Триггер

Концепт триггеров для МойСклад.

Триггер - это обработчик, который срабатывает на изменение документа или иное событие в МойСклад.

Общие настройки

Жирным выделены обязательные условия

Наименование	Поле в конфигурации	Тип данных	Описание
Название	name	`string`	Название триггера для удобного просмотра в списке
Код	code	`string`	Уникальный код тригера для идентификации тригера в сообщениях ошибок и логах
Активен	active	`boolean`	Указывает на то, активен ли текущий триггер
Типы сущностей	entity_types	`string[]`	Массив типов сущностей на изменения которых подписан триггер
Скриптовый язык	script_lang_name	`string`	Скриптовый язык на котом будут записаны выражения (Фильтр, Условие и др.). По умолчанию упрощенная версия языка Python.
Версия скриптового языка	script_lang_version	`string`	Версия скриптового языка
Версия контекста	script_context_version	`string`	Версия контекста в котором работают выражения на выбранном скриптовом языке (глобальные переменные, вспомогательные функции)
Фильтр	filter	`string`	Выражение с предварительным условием на срабатывание триггера
Условие	condition	`string`	Выражение с основным условием на срабатывание триггера
Загрузка полей	expand	`string`	Список полей документа, которые необходимо загрузить для того, чтобы они были доступны в выражениях
Действия	actions	`Actions[]`	Список объектов `Action`, каждый из которых описывает отдельное действие, которое необходимо выполнить, если выражения в Фильтре и Условии триггера и вернули `true` (либо если выражения не заданы)
Окно	window	`number`	Время в секундах, которое должно обязательно пройти после того как документ изменился, прежде чем триггер получит это событие (удобно для тех случаев, когда документ может несколько раз обновляться за короткий промежуток времени в процессе редактирования или изменения через API и важно убедится, что работа над документом окончена перед тем как запускать триггер)

Пример триггера

Нужно проверить, что значение пользовательского поля Тип оплаты за заказ в отгрузке совпадает со значением того же поля в родительском заказе покупателя к которому привязана отгрузка.

И если поля не соответствуют, то создать задачу сотруднику (указанному в документе отгрузки) из связанного заказа с текстом Ошибка: неправильно указан тип оплаты за заказ в отгрузке [название отгрузки]. Нужно указать "[тип_оплаты_в_заказе]".

Событие

Можно указать несколько сущностей или даже реагировать на все события.

Подпишемся на события изменения отгрузки.

- demand

Фильтр

Будем проверять только те отгрузки, которые проведены и которые либо созданы, либо у которых изменилось поле Тип оплаты за заказ

o.applicable == true and (event.event_type == 'create' or ИЗМЕНИЛОСЬ_ПОЛЕ("Тип оплаты за заказ"))

o - объект текущего документа
o.applicable - признак того, что документ проведен
event - объект текущего события на которое сработал триггер
event.event_type - тип события: created, updated, deleted
ИЗМЕНИЛОСЬ_ПОЛЕ([название_поля]) - функция которая проверяет изменилось ли указанное поле (пользовательское или встроенное) в текущем документе в рамках текущего изменения

Условие

Если отгрузка прошла предварительную фильтрацию в разделе Фильтр, то проверяем, что поле Тип оплаты за заказ соответствует связанному заказу покупателя

тип_оплаты_в_отгрузке = НАЙТИ_АТРИБУТ(o, "Тип оплаты за заказ").value.name

тип_оплаты_в_заказе = НАЙТИ_АТРИБУТ(o.customerOrder, "Тип оплаты за заказ").value.name

тип_оплаты_в_отгрузке != тип_оплаты_в_заказе

НАЙТИ_АТРИБУТ([документ], [пользовательский_атрибут]) - функция ищет и возвращает пользовательский атрибут в указанном документе

Действия

В разделе действия прописываем все действия которые необходимо выполнить, если триггер сработал.

Действия могут быть разные: Создать задачу, Отправить сообщение в Телеграм, Отправить SMS, создать или изменить документ, отправить webhook и многое другое.

Создать задачу

Наименование	Поле в конфигурации	Тип данных	Описание
Описание	description	`string`	Описание задачи.
Срок	dueToDate	`string`	Срок задачи.
Ответственный	assignee	`href`	Ссылка на сущность сотрудника `employee`, ответственного за выполнение задачи
Контрагент	agent	`href`	Контрагент или юрлицо, связанное с задачей.
Документ	operation	`href`	Документ, связанный с задачей.
Комментарии	notes	`href`	Отметка о выполнении задачи

Пример:

type:

Менеджер
```
o.owner
```

Описание

тип_оплаты_в_заказе = НАЙТИ_АТРИБУТ(o.customerOrder, "Тип оплаты за заказ").value.name

ФОРМАТ("Ошибка: неправильно указан тип оплаты за заказ в отгрузке {o.name}. Нужно указать '{тип_оплаты_в_заказе}'")

Выполнено - не указано (по умолчанию false)
Контрагент - не указано

wmakeev/moysklad-triggers.md