Динамическое вычисление типа события

Начиная с версии системы 2024.11 доступно динамическое вычисление типа события при помощи скрипта. Оно позволяет сформировать фильтр для событий, при наступлении которых срабатывает определённый обработчик.

Динамическое вычисление типа события доступно в доменах:

Все события;
Элементы приложений.

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

Нажмите Создать. Откроется страница настройки обработчика событий.

Вы увидите название обработчика и указанный домен события. Изменение домена после создания обработчика недоступно.

В поле Событие отобразится ссылка Вычисляется скриптом. Нажмите на неё, чтобы открыть скрипт с методом фильтрации.

Метод формирования фильтра событий имеет следующие параметры:

асинхронный;
имеет фиксированное имя filter();
возвращает объект Promise<EventsFilterType>.

Для корректной работы динамической фильтрации не изменяйте имя и параметры метода. В теле метода filter() сформируйте фильтр по событиям. Если метод возвращает пустое значение, обработчик событий не вызывается.

Чтобы определить условия для фильтрации, используйте метод where(). В зависимости от домена события, внутри where() доступны различные свойства.

Если при создании обработчика событий выбран домен Все события, вы можете использовать:

any — произвольное событие, которое позволяет выбрать события из различных доменов;
app — события по элементам приложений.

При указании домена Элементы приложений доступно только свойство app, которое позволяет включить в фильтр события по элементам приложений.

Фильтры по элементам приложений

Для фильтрации доступны события из домена Элементы приложений.

В методы этого домена можно передать:

ссылку на приложение или описание коллекции приложения:

async function filter (): Promise<EventsFilterType> {
    const filter = System.events.filter();

    filter.where(f => f.app.itemCreate(Namespace.params.fields.invoicesApp.app));

    return filter;
}

раздел и код приложения в виде строк:

async function filter (): Promise<EventsFilterType> {
    const filter = System.events.filter();

    filter.where(f => f.app.itemCreate("ordersNamespace", "invoicesApp"));

    return filter;
}

Фильтры по всем событиям

Доступно создание фильтра для событий по элементам приложений, а также для произвольных событий.

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

Для формирования фильтра по произвольным событиям в where() нужно обратиться к методу event() свойства any.

События задаются в виде объекта со свойствами:

namespace и code — для произвольного события задайте домен события. Для события по элементам приложения укажите раздел, в котором хранится приложение, и само приложение;
name — укажите событие, которое будет отслеживаться.

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

async function filter (): Promise<EventsFilterType> {
    const filter = System.events.filter();

    // Произвольное событие по созданию приложения `invoicesApp` в разделе `ordersNamespace`
    filter.where(f => f.any.event({namespace:"ordersNamespace", code: "invoicesApp", name:"item_create"}));

    // Полностью соответствует записи
    filter.where(f => f.app.itemCreate("ordersNamespace", "invoicesApp"));

    return filter;
}

Варианты написания скрипта для динамической фильтрации событий

Метод where() можно вызывать любое количество раз: в рамках одного фильтра его результаты складываются.

Рассмотрим примеры скриптов для динамической фильтрации событий.

Список значений

async function filter (): Promise<EventsFilterType> {
    const filter = System.events.filter();

    filter
        .where(f => [
            f.any.event({namespace:"system", code: "users", name: "login_failed"}),
            f.app.addComment("ordersNamespace", "invoicesApp"),
            f.app.itemCreate("ordersNamespace", "contractsApp")
        ]);

    return filter;
}

Строитель (Builder)

После вызова метода where() можно использовать его повторно:

async function filter (): Promise<EventsFilterType> {
    const filter = System.events.filter();

    filter
        .where(f => f.any.event({namespace:"system", code: "users", name: "login_failed"}))
        .where(f => f.app.addComment("ordersNamespace", "invoicesApp"))
        .where(f => f.app.itemCreate("ordersNamespace", "contractsApp"));

    return filter;
}

Комбинирование условий

async function filter (): Promise<EventsFilterType> {
    const filter = System.events.filter();

    switch (Namespace.params.data.string_condition) {
        case "invoices_events":
            filter.where(f => [
                f.app.itemCreate("ordersNamespace", "invoicesApp"),
                f.app.itemUpdate("ordersNamespace", "invoicesApp"),
            ]);
            break;
        case "order_events":
            filter.where(f => f.app.itemCreate("ordersNamespace", "contractsApp"));
            filter.where(f => f.app.itemUpdate("ordersNamespace", "contractsApp"));
            break;
        default:
            filter.where(f => f.app.itemCreate("ordersNamespace", "ordersApp"));
            break;
    }

    filter.where(f => [
        f.app.itemCreate("ordersNamespace", "suppliersApp"),
        f.app.itemUpdate("ordersNamespace", "suppliersApp")
    ]);

    return filter;
}

Особенности динамической фильтрации

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

фильтр может возвращать любое количество значений;
если в ходе применения фильтров какое-то из полученных значений дублируется, оно используется только один раз;
при каждом вызове метода where() значения в фильтре суммируются;
при фильтрации можно получить события разных типов, поэтому в скрипте обработчика типа Запуск скрипта также нужно проверить тип события для запуска нужных действий;
если при фильтрации значения не найдены, обработчик событий не вызывается;
если после формирования фильтра в скрипт фильтрации вносятся изменения, которые приводят к ошибке его исполнения, то используется предыдущий успешно сформированный фильтр.

Когда выполняется скрипт динамической фильтрации

Заданный в скрипте фильтр формируется:

при включении модуля — выполняются все скрипты динамической фильтрации опубликованных обработчиков событий;
при сохранении настроек модуля — выполняются все скрипты динамической фильтрации опубликованных обработчиков событий;
при публикации обработчика событий, если модуль включён — выполняется скрипт фильтрации этого обработчика.

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

Ошибки при исполнении скрипта динамической фильтрации

Если при исполнении скрипта фильтрации возникает ошибка, то на вкладке Обработка событий напротив обработчика отобразится значок ошибки.

При нажатии на значок вы увидите текст ошибки и сможете перейти к редактированию скрипта.

Общие ограничения в фильтрации

Если значения передаются в метод фильтрации в виде строк, нельзя передавать пустую строку или символ *. Это приведёт к ошибке при выполнении скрипта.