Dynamic event type calculation

Starting from system version 2024.11, dynamic event type calculation using a script is available. This functionality allows creating filters for events that trigger a specific handler.

Dynamic event type calculation is available in the following domains:

All Events.
App Items.

To configure dynamic event filtering by type, go to the event handler creation, select a domain, and enable the Define the event type dynamically with a script option. The Event field will be hidden.

Click Create to open the event handler settings page.

You will see the handler’s name and the specified event domain. You can’t change the domain after creating the handler.

In the Event field, the Calculated with a script link will appear. Click it to open the script containing the filtering method.

The event filter generation method has the following parameters:

Asynchronous.
Unchangeable name: filter().
Returns a Promise<EventsFilterType> object.

To ensure proper operation of dynamic filtering, do not modify the method’s name or parameters. Within the filter() method body, construct the event filter. If the method returns an empty value, the event handler is not triggered.

To specify filtering conditions, use the where() method. Depending on the event domain, various properties are available within where().

If the All Events domain is selected while creating the event handler, you can use:

any. A generic event that allows selecting events from different domains.
app. Events related to app items.

If the App Items domain is specified, only the app property is available, which allows you to add events related to app items in the filter.

Filters for app itmes

You can set us filtering using events from the App Items domain.

In this domain’s methods, you can pass:

A link to an app or a description of the app collection.

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

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

    return filter;
}

A workspace and app code as strings:

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

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

    return filter;
}

Filters for all events

In the All Events domain, you can create filters for app item events as well as for generic events.

When specifying a generic event, you can select certain system events from different domains. Their list is limited. Suggestions with possible values will appear when creating the filter.

To create a filter for generic events in where(), use the event() method of the any property.

Events are defined as an object with the following properties:

namespace and code. For generic events, specify the event domain. For app item events, indicate the workspace where the app is stored and the app itself.
name. Specify the event to be tracked.

Events in the App Items domain can be described as generic events in the following way:

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

    // Creating an app item of the `invoiceApp` app in the `ordersNamespace` workspace as a generic event
    filter.where(f => f.any.event({namespace:'ordersNamespace', code: 'invoicesApp', name:'item_create'}));

    // The filter above is exactly the same as this one
    filter.where(f => f.app.itemCreate('ordersNamespace', 'invoicesApp'));

    return filter;
}

Script examples for dynamic event filtering

The where() method can be called multiple times. Results within a single filter are combined.

Let’s consider some examples of dynamic filtering scripts.

List of values

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

After calling where(), you can use it again:

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

Combining conditions

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

Features of dynamic filtering

When you use dynamic filtering:

A filter can return any number of values.
If duplicate values are obtained during filtering, they are used only once.
With each call to the where() method, values in the filter are accumulated.
Filtering can retrieve events of different types, so the script configured in the Run Script type handler should also verify the event type to trigger the appropriate actions.
If no values are found during filtering, the event handler is not triggered.
If script changes introduce an error in the filtering script, the last successfully formed filter is used.

When the dynamic filtering script is executed

The script-defined filter is generated:

When the module is enabled: all dynamic filtering scripts of published event handlers are executed.
When module settings are saved: all dynamic filtering scripts of published event handlers are executed.
When an event handler is published, if the module is enabled: the handler’s filtering script is executed.

Afterward, the generated filter is used to select events for which the handler is triggered.

Errors during script execution

If an error occurs during script execution, an error icon will appear in the Event Handling tab next to the handler.

You can click the icon to view the error message and go to script editing.

General filtering restrictions

If filter values are passed as strings, empty strings or the * symbol cannot be used. Doing so will result in an error during script execution.