Обработчик события в модуле: отправка письма на эл. почту при изменении статуса элемента приложения

Решаемая задача:
При изменении статуса элемента приложения необходимо отправить оповещение на электронную почту определённому списку пользователей системы.

Вводные данные:
Приложение Поставщик в разделе Склад с тремя статусами Потенциальный, Действующий, Договор расторгнут.

Контекст приложения:
- Название (__name), Строка,
- Ответственный (otvetstvennyi), Пользователи-Один.

Условия:
В случае, если статус Поставщика изменился на "Действующий", автору элемента приложения должно прийти письмо на электронную почту с указанием изменения статуса и ссылкой на элемент Поставщик.
Если статус изменён на "Договор расторгнут" - аналогично, но дополнительно письмо отправляется Ответственному за поставщика.

Реализация:

Создаём свой модуль в разделе Администрирование-Модули.

В настройки модуля добавляем переменную Поставщик с нашим типом приложения и переменную Базовый URL (тип Строка) - понадобится для формирования ссылки на элемент приложения.
Настройка Базовый URL нужна только для версии 2023.7 и ниже.


Далее можно задать значение по умолчанию для настройки Базовый URL, указав URL системы:


Изменить форму настроек, вынести на форму только настройку Базовый URL, чтобы в дальнейшем можно было менять это значение.


На вкладке «Обработка событий» создадим новое событие.
Домен события: элементы приложений.
Событие: Изменение статуса элемента приложения.
Тип обработчика: запуск скрипта.
Фильтр типа объекта: наше приложение Поставщик.

Важно

Внимание! Настройка "Фильтр типа объекта" доступна начиная с версии 2023.6 (но данный пример адаптирован и под версии ниже 2023.6, и будет работать без этой настройки)

Перейдём на вкладку «Сценарии» созданного обработчика. На данной вкладке будет создан метод по умолчанию

async function action(): Promise<void> {}

Код обработчика необходимо реализовать в данном методе.

Код:

async function action(): Promise<void> {

  //проверяем по коду раздела и приложения, что обработчик сработал при изменении элемента нужного нам приложения
  if (Context.data.__item!.namespace === 'sklad' && Context.data.__item!.code === 'postavshik') {
    //выполняем поиcк элемента по id, где postavshik - контекстная переменная из настроек модуля
    let postavshik = await Namespace.params.fields.postavshik.app.search().where(a => a.__id.eq(Context.data.__item!.id)).first();
    if (postavshik) {
      let fromID = Context.data.fromID //id статуса до изменения
      let toID = Context.data.toID //id статуса после изменения
      let fromCode = postavshik!.fields.__status.all.find(s=>s.id == fromID)!.code //ищем код статуса до изменения по его id
      let toCode = postavshik!.fields.__status.all.find(s=>s.id == toID)!.code //код статуса после изменения
      //продолжаем только в том случае, если статус изменён на "Договор расcторгнут" или "Действующий"
      if (toCode == postavshik!.fields.__status.variants.dogovor_rastorgnut.code ||
      toCode == postavshik!.fields.__status.variants.deistvuyushii.code)
      {

        //Запускаем процесс, в процесс передаём элемент приложения Поставщик, код статуса до изменения и код статуса после изменения
          await Namespace.processes.opoveshenie_o_izmenenii_statusa.run({postavshik: [postavshik.data.__id] as any, fromstatuscode: fromCode, tostatuscode: toCode})
      }
    }
  }
}

Запускаемый процесс "Оповещение о изменении статуса" (opoveshenie_o_izmenenii_statusa) создан заранее в этом же модуле на вкладке Процессы.


Контекст процесса:


Карта процесса:



Задача "Проверить сформированные данные" нужна только для отладки процесса и проверки корректности выполнения предыдущих сценариев. На форму задачи вынесены все переменные процесса.
Переменные postavshik, tostatuscode, fromstatuscode являются входными и заполняются из сценария обработчика при запуске процесса.
Переменная poluchateli_pisma (Пользователи-Несколько) заполняется в сценарии "Сформировать список получателей":

Код:

//формируем список получателей письма и записываем их в переменную Context.data.poluchateli_pisma
async function setRecipients(): Promise<void> {
  let postavshik = await Context.data.postavshik!.fetch()//получаем элемент приложения
  Context.data.poluchateli_pisma = []
  Context.data.poluchateli_pisma = Context.data.poluchateli_pisma.concat(postavshik.data.__createdBy)//автор всегда в списке получателей
  if (Context.data.tostatuscode == postavshik.fields.__status.variants.dogovor_rastorgnut.code)//если статус изменен на "Договор расторгнут"
  {
    Context.data.poluchateli_pisma = Context.data.poluchateli_pisma.concat(postavshik.data.otvetstvennyi!)//добавляем в получатели Ответственного
  }

}

Переменная link заполняется в следующем сценарии "Сформировать ссылку на элемент":

Код:

async function setLink(): Promise<void> {
  let baseURL = system.getBaseUrl()//получаем базовый URL системы (для версии 2023.8 и выше)
 // let baseURL = Namespace.params.data.baseURL//получаем базовый URL из настроек модуля для версии 2023.7 и ниже
  let namespace = Context.data.postavshik!.namespace//раздел
  let code = Context.data.postavshik!.code//приложение
  let id = Context.data.postavshik!.id
  let link = baseURL + '/(p:item/' + namespace + '/' + code + '/' + id + ')'
  Context.data.link = link
}

Весь контекст сформирован! Настраиваем блок "Оповещение на Email". Особенности работы с данным блоком в справке по системе https://elma365.com/ru/help/platform/360011443400.html



Пример, как выглядит полученное письмо:


Более подробно особенности работы с обработчиками событий и его контекстом я рассказывала ранее в статье по ссылке https://community.elma365.com/ru/threads/96/