Introduction to Server Events

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 server event 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 an event 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 a server event 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 server events click the Apply or Okay buttons

Server Event Handler Properties

Each Server Event Handler has the following properties:

Name

Provides a unique identifier for each Event Handler

Function

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.

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 dialog.

Custom Code dialog

 

Custom Code has three additional properties:

• Language: Code can be written in C#, JavaScript (in Windows only) 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 bin folder 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.

Note

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

• Namespaces: A semicolon-separated list of namespaces in the referenced DLLs or the Exago API library.
• 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.

.NET Assembly

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

Global Event

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.

Arguments

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.

.NET Assemblies

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 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 DLL is referenced by the assembly, then it must be recompiled to the current version whenever Exago is updated.