# Event handling in modules

> [HTML Version](events_processing.html)

You can configure the handling of various system events in a custom module.

An** event handler** triggers a specific action in the system after an event occurs. It can be useful when creating complex modules. 

When an event occurs, the following actions can be performed:

- Executing a [script](type-script.md) created in the handler.

- Starting a [business process associated with the module](extention-processes.md).

- Sending a message to an [external microservice](custom_services.md). It is available only in [BRIX On-Premises](elma365-on-premises.md).

For example, you can create a handler in a module that launches a process after a user edits an app item.

## Configure an event handler

Creating and configuring an event handler in the module consists of several steps. Let’s take a closer look at each one.

### Step 1. Create the handler and select its type

1. Go to **Administration > Modules**.

2. Hover the mouse over a module and click the gear icon.

3. Go to the **Event Handling** tab.

4. Click **+Handler** and enter the information in the window that opens.

**(event-handling-1.png)**

- **Name**\*. Enter the name of the handler.

- **Handler type**\*. Select an activity that will occur after each event:

	- **Run Script**. Executes a script created in the handler.

	- **Run Process**. Executes a business process created in the module on the **Processes** tab.

	- **Send Message to Service**. Sends a message to an external microservice. This activity is available only in [BRIX On‑Premises](elma365-on-premises.md).

### Step 2. Select the domain and event to handle

1. In the** Event domain **field, select an area where the handler will listen for events. You can choose from the following domains:

- **All Events**. The handler tracks events from all domains in the system.

- **App Items**. Select the app whose events are to be processed in the **Object type filter** field that appears. If you do not select an app, the module will track the events of all existing apps in the system. It is possible to record the creation, update, status change, and removal of an item, and comments added to an item’s activity stream.

If you have set event tracking for the creation, update, or deletion of an item and specified an app, the \[OBJECT\] property is added to the script. It contains strictly typed data of the app item and the corresponding event.

Please note that if an app is selected, it is impossible to [export](export_extention.md) the module. This is due to the restriction on exporting a module associated with an app that is not part of the module. You can [create a solution](create-solution.md) and export the module and the app as part of it.

- **Live Chats**. The handler records the receipt of incoming and sending of outgoing messages in a session, as well as system messages about session state changes. 

- **Tasks**. The domain is only available when the CRM solution is activated with [CRM tasks](360012911980.md) enabled. The handler will record events related to the creation, modification, cancelation, or termination of CRM tasks. In the **Task type filter** field that appears, specify the type of activity whose changes will be tracked by the module:

	- **Call**, **Email**, **Webinar**, **Meeting** or a [custom task type](create-custom-crm-task.md): for CRM tasks of the selected type.

	- **All CRM Tasks**: for all of the above tasks at once.  
  
To learn more about setting up a handler of this type, see the [Event handling in CRM tasks](crm-events-processing.md) article.

- **Apps**. The handler tracks events of exporting or importing data from the system apps.

- **Files**. Allows you to record the creation, editing, and deletion of a file, adding comments to it, and changing access settings.

- **Directories**. Tracks the creation, editing, deletion, and changing of access settings for folders in the **Files** workspace.

- **Duplicates**.You can customize the handler if you have activated the **BRIX Contractor Management** solution, either separately or as part of one of the CRM solutions that includes the search for duplicates, i.e., app items with the same data. The action in the handler is triggered when duplicate records are merged. You can see an example of such a handler in [Event processing in duplicates](duplicates-events-processing.md) article.

- **Modules**. Allows you to track:

	- Events of enabling and disabling modules.

	- Events of installing and updating modules. Please note that these events are recorded only if the handler already exists in the system, not when it is added as part of a module.

- **Settings**. Records the editing of [additional parameters](360009207779.md) associated with the company, a workspace, or an app.

- **Users**. The events related to [user account management](360004833572.md) are tracked, as well as the user's actions, such as status changes, authorization error, logout, etc.

2. Starting from system version 2025.1, for the  **All Events** or **App Items** domains, the Define the event type dynamically with a script option is available. This option allows you to filter events. Enable the option so that the handler tracks multiple event types defined in the filtering script. Event filtering is performed before the handler itself is started. For example, you can configure one handler to track events for items in different apps.

3. In the **Event** field, select the event that will trigger the handler. When dynamic event type calculation is enabled, this field is not displayed, because the events to track are defined in the script.

4. Click the **Save** button. 

### Step 3. Add a script of business process

After you have filled in the required fields for the handler and saved them, the action configuration window for when the event is triggered will open. Depending on the handler type, do the following:

1. For the **Run** **Script** type.  
  
Write a script on the **Scripts** tab. In the script, you can:

1. Access variables from other workspaces and custom modules by configuring [optional dependencies](optional-dependencies.md).  
  
To create a dependency on the top panel, click **Settings** and add workspaces and modules to the list. They can then be accessed via the [Imports](optional-dependencies.md#use-imports) global constant. A module with optional dependencies can be exported without restrictions.**(event_handler2.png)**

2. Access variables from apps using the `Namespace` [global constant](global-constants.md).  
  
To do this, create an **App**-type field in the module's **Settings** tab and specify the target app. Then, in the event handler script, you can use methods available for performing operations on app items.   
  
When using the `Namespace` global constant, the module can only be exported as part of a [custom solution](create-solution.md) along with the app being monitored in the event handler.

3. Access libraries from [npm packages with server dependencies](npm-package.md) if you added them in advance on the **Files** tab. This feature is only available for BRIX On-Premises starting with version 2026.4.

2. For the **Run Process** type.  
  
Select the business process created within the module. Then, on the **Input Variables** tab, map variables from the process context to the event properties: object, name, author, and so on.  
  
A limited set of system fields is provided for events: identifier, name, description, event time, object name, author, etc. There are also individual properties for each event, referring to the selected domain and action type.  
  
The configuration on the **Input Variables** tab allows you to define data sources for properties from the process context. It is done depending on the handler to be implemented and the final user’s need.  
**(event-handling-2.png)**

**Important**: The **Input Variables** tab displays properties that are present in the process context at the time the process is linked to the handler. If the process context has been changed, the new variables will not appear in the handler settings. You must recreate and configure the event handler by linking the same business process to it.

3. For **Send Message to Service** type.  
  
Specify the microservice.

### Step 4. Configure event filtering with dynamic calculation

This step is performed if, when creating the handler, you selected the **All Events** or **App Items** domain and enabled the **Define the event type dynamically with a script **option.

1. Set a filter to select the events that the handler tracks. To do this, on the **Settings** tab, click the **Calculated** **with a script** link.**(events_processing-5.png)**

2. The **Scripts** tab will open. In the \[OBJECT\] method, specify the event types to be tracked. The available options depend on the domain selected when creating the handler:

- **All Events**. You can specify event types from different domains. The list is limited. When you create a filter, you will see tooltips with possible values.

- **App Items**. Only events for app items are available.

Read more about scripting and the peculiarities of dynamic filtering in [BRIX TS SDK](https://tssdk.brix365.com/en/latest/pages/quick-start/intro_dynamic-filtration.html).

The generated filter will be applied after the event handler is published and the module is enabled. The handler will be triggered by system events that match the specified conditions.

### Step 5. Publish and enable the handler

On the top toolbar of the settings page, click **Save**, then click **Publish** to activate the event handler. Then go to the module settings page and enable it.

This way you can add several event handlers to a custom module. For example, when you change the item status in the **Orders** app, a business process will be launched. By using a [script](360027203731.md) or a [gateway](360012495911.md) you can activate different process branches depending on the status that the app item acquires.

You can also learn about using handlers with domains associated with the **CRM** system solution in the following articles: [Event handling in CRM tasks](crm-events-processing.md) and [Event processing in duplicates](duplicates-events-processing.md).

## Trace handler scripts

If tracing is enabled for a handler of the **Run Script** type in the **Administration > Developer Tools** workspace, you can analyze the execution of its script. This allows you to evaluate the duration of individual requests, optimize the code, and identify the causes of errors.

To view the traces list, open the **Event Handling** tab in the module settings. To view entries:

- For all handlers in the module: click **View tracing** in the upper right corner of the page.

- For a specific handler: click on its name and select **Tracing** in the upper panel.

For more information about tracing configuration and information on the trace page, see the [Trace server scripts](server-script-tracing.md) article.

## Disable a handler

To disable a handler, go to the **Event Handling** tab and click on the three dots icon opposite the handler’s name. Select **Cancel Publication**. Now the handler will not be triggered when the event occurs. 

You can also delete an event handler. To do this, go to the **Event Handling** tab, check the box next to one or more handlers, and click the **Delete** button in the upper right corner of the page.

(event-handling-3.png)