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

Решаемая задача

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

Вводные данные

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



Контекст приложения:

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

Условия

Если статус поставщика изменился на Действующий, автору элемента приложения приходит письмо на электронную почту с указанием изменения статуса и ссылкой на элемент приложения.
Если статус изменён на Договор расторгнут — аналогично, но дополнительно письмо отправляется ответственному за поставщика.

Реализация

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

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



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



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



5. На вкладке Обработка событий создадим новое событие:

• Домен события — элементы приложений.
• Событие — изменение статуса элемента приложения.
• Тип обработчика — запуск скрипта.
• Фильтр типа объекта — наше приложение Поставщик.

Важно

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

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})
      }
    }
  }
}

7. Запускаемый процесс Оповещение о изменении статуса (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. Особенности работы с данным блоком в официальной справке ELMA365.



Полученное письмо пользователем письмо в результате выполнения настроек может выглядеть следующим образом:



Более подробно особенности работы с обработчиками событий и его контекстом можно ознакомиться в связанной статье в ELMA365 Community, где рассматривается другой пример.