This article applies to the Admin Console > Extensions > Server Events settings.
Server 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 be written in a high-level programming language.
Create, Edit, Delete Server Event Handlers
- To add a new custom function click Extensions > Server Events in the Main Menu and either:
- click the Add icon at the top of the main menu
- right-click and select Add from the context menu
- To edit a function either:
- double click it
- select it and click the Edit icon at the top of the main menu
- right-click it and select Edit from the context menu
- To delete an object either:
- select it and click the Delete icon at the top of the main menu
- right-click it and select Delete from the context menu
- To save changes and new functions click the Apply or Okay buttons
Server Event Handler Properties
Each Server Event Handler has the following properties:
Provides a unique identifier for each Event Handler
Choose between Custom Code or the name of a .NET Assembly. If there are no .NET Assembly Data Sources available, Custom Code will be the only available option.
To save code directly in Exago, select Custom Code from the first function dropdown. Clicking on the second dropdown opens the custom code dialog.
Custom Code has three additional properties:
- Language: Code can be written in C# or VB.NET.
- References: A semicolon-separated list of any DLLs that need to be referenced by the code. The DLLs must be present in the
\binfolder of the Exago Web Application, Scheduler Services, and the Web Service API if applicable. This folder can be found in the installation directory of the respective component.
System.dlldoes not need to be listed as a reference as it is already available.
- Code: The code that will be executed by Exago when called. See Arguments for information on how to access the arguments for each Event. When finished, click the Test Custom Code icon to check if the code compiles.
An example of C# Custom Code:
System.Data.DataTable dt = (System.Data.DataTable)args; if (dt.Columns.Contains("Employees.BirthDate")) foreach (System.Data.DataRow row in dt.Rows) row["Employees.BirthDate"] = DbNull.Value; return dt;
There are two ways to reference a .NET Assembly method.
- 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.
- Add the .NET Assembly to the
\binfolder of the Exago Web Application, Scheduler Services, and the Web Service API if applicable. This folder can be found in the installation directory of the respective component. Then in the Custom Code window, add the assembly as a reference and invoke the method, for example:
return Extensions.Events.CensorEmployeeBirthYear(sessionInfo, args);
Determine when this Server Event Handler will be called, either whenever specific event type occurs, or only when that event occurs for specific reports.
- Select a Global Event from the list to indicate that the Event Handler should be called whenever this event occurs in the application for all report executions.
- Leave Global Event set to None to indicate the Event Handler is meant for a specific report. See Setting Event Handlers on Specific Reports for more information. For example, selecting OnReportExecuteStart from this dropdown will cause the Event Handler to be called at the start of any Report Execution.
Server Event Handlers 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.
The following are important details for using .NET Assemblies as Server 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 applicable).
- 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
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.
WebReportsApi.dllor another Exago DLL is referenced by the assembly, then it must be recompiled to the current version whenever Exago is updated.
Visit the How-To Guides > Server Events section of our documentation for examples of Server Event implementations.