# Introduction to Server Events

This section explains how to create Events Handlers that run custom code when certain actions occur in the Exago BI runtime.

- To add a new Event Handler select ‘Server Events’ in the Main Menu then click the add button.
- To edit an existing Event Handler either double click it or select it and click the edit button.
- To delete an Event Handler select it and click the delete button.

# Event Handlers

Event Handlers provide code that Exago can execute when certain events happen during the application runtime. This code can either come from a .NET Assembly or within the Exago configuration file.

All existing Event Handlers are listed in the Main Menu under Server Events. All the Event Handlers you are adding or editing will be displayed in a Tab entitled Server Events.

Each Event Handler has the following properties:

- Name – Provides a unique identifier for each Event Handler
- Function – Can either be Custom Code or a .NET Assembly method.
  - Custom Code – To save code directly in Exago, select Custom Code from the first function dropdown. Clicking on the second dropdown opens the custom code menu.
    See Custom Code for information on how to access the arguments for each Event. Click the green check mark to verify the code compiles.
    Custom Code has three properties:
    - Language – Code can be written in C#, VB.NET, or JavaScript (Windows only).
    - References – A semicolon-separated list of any .NET Assembly dlls that need to be referenced by the Event Handler (JavaScript code cannot access .NET libraries).

> NOTE. System.dll does not need to be listed as a reference as it is already available.

- Code – The code that will be executed by Exago when called.

  ### C# Example

      System.Data.DataTable dt = (System.Data.DataTable)args[0];
      if (dt.Columns.Contains("Employees.BirthDate"))
        foreach (System.Data.DataRow row in dt.Rows)
          for (int i = 0; i < row.ItemArray.Length; i++)
            row["Employees.BirthDate"] = DbNull.Value;

      return dt;

- .NET Assembly Method – There are two ways to reference a .NET Assembly method.
  1. Create a .NET Assembly Data Source. Select the desired assembly from the first Function dropdown. Clicking on the second dropdown will open a list of available methods.
  2. Add the .NET Assembly to the \Bin folder (for ExagoWeb, WebServiceApi, and all Schedulers, if applicable). Then in the Custom Code, add the assembly as a reference, then invoke the method, e.g.
     `return Extensions.Events.CensorEmployeeBirthYear(sessionInfo, args);`
     See .NET Assemblies for info on how to access the arguments for each Event.

- Global Event – In this dropdown select an Event to indicate that the Event Handler should be called whenever this event occurs for all report execution. Leave Global Event set to ‘None’ to indicate the Event Handler is meant for a specific report.
  E.g. Selecting OnReportExecuteStart from this dropdown will cause the Event Handler to be called at the start of any Report Execution.

- None – The Event Handler will not be called automatically for all reports, but can be set to run for the execution of specific reports. See Setting Event Handlers on Specific Reports for more information.

# Arguments

Server events can access the following information in order to inspect the session state, and utilize built-in methods:

- sessionInfo – The sessionInfo object provides access to elements of Exago's current session such as parameters, filters, and the current report.
- args – Events may have access to an array of values called args. For each Event the content of the array will be different. For details on the arguments that each event provides, see Full Description of Events.

# .NET Assemblies

The following are important details for using .NET Assemblies as Event Handlers.

- The Assembly dll will be locked by Exago when it is first accessed. To replace the dll, unlock it by restarting the IIS App pool (and Scheduler services, if needed).
- The first argument of all Event Handlers is the sessionInfo object which can be used to access elements within the Exago session. To make use of this object the assembly must reference WebReportsApi.dll.
  If the code does not need to make use of sessionInfo then the method signature in the assembly can declare sessionInfo as an object instead of as a sessionInfo data type.
- All methods used as Event Handlers must be static.

> Note: If WebReportsApi.dll or another Exago BI dll is referenced by the assembly, then it must be recompiled to the current version whenever Exago BI is updated.