# Introduction to Action Events

Action Events can be grouped into two general categories: Local and Global events.

- Local events have two sub-categories:
  - Handlers attached to items in reports and set to fire automatically, or when the item is interacted with in the Report Viewer.
  - Handlers attached to items in the Exago UI and set to fire when that item is clicked.
- Global events are active throughout the application, and fire when specific events occur.

This article explains how to create Local and Global action events, describes the ways in which action events can interact with the Exago application, and lays out examples for common usages.

# Creating Event Handlers

Action event handlers are created using the Admin Console or by directly editing the WebReports.xml config file. They can also be added or modified on a per-session basis in a .NET configuration using the 'Api.SetupData.ActionEvents' server call.

- To create a new Event Handler expand ‘Extensions’ in the Main Menu, select ‘Action Events’, and click the add button.
- To edit an 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.

The Action Events tab will open and display the selected event or a New Action Event dialog:

Each Event Handler has the following properties:

- Name – 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 Writing Action Events for information on how to access the arguments for each Event. Press the green check mark to verify that the code compiles.

    Custom Code has four 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.

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

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

     > Note: The Assembly’s dll will be locked by Exago when it is first accessed. To replace the dll, unlock it by restarting the IIS App pool.

     > Note: If you want to utilize the sessionInfo object that is passed to all Event Handlers the Assembly must include a reference to WebReportsApi.dll. For more information see SessionInfo.

     > Note: All methods used as Event Handlers must be static.

- Event Type – Select an option in this dropdown to create an event that will be executed when certain client-side actions are taken.
  - None – This event handler is a Global Event. You must specify a Global Event Type in the following dropdown.
  - Load – The event handler will execute when a report item is loaded in the Report Designer, Viewer, or (v2016.2.5+) upon Export. This type of handler is typically used to interpret and then apply alterations to report data, e.g. conditionally changing the colors on charts or maps. As of v2016.2.5 Load events can affect Export formats (PDF, Excel, RTF, CSV).
  - Click – The event handler will execute when a user clicks on an item in a report or in the Exago UI. This type of handler is typically used to add additional interactive elements to reports or to the Report Designer. Click events will not function on Export formats.
    For information on adding action events to specific reports, see Adding Action Events to a Report.
- Global Event Type – Select an option in this dropdown to create an event that will be triggered when a condition is met in the Exago application. See Global Events.

  > Note: Selecting a Global Event Type will cause Exago to ignore any selected Local Event Type.

- Assigned UI Item(s) – This field designates a comma-separated list of UI item IDs for items in the Exago interface. These elements can be intercepted and modified by assigning them in this field. For a list of compatible UI items, see UI Elements.

  > Note: This selection field only applies when the Event Type is Click. This field will be ignored when any other options are selected.

# Writing Action Events

When an Action Event is fired, two primary parameter objects are passed: sessionInfo and clientInfo. These are the main points of interaction with the Exago application.

- sessionInfo – Provides access to all the elements of the current Exago session. This is the server-side information. For more information see SessionInfo. The most relevant elements are the following:
  Note: To access the sessionInfo from a .NET Assembly, you must include a reference to WebReportsApi.dll.
  - SetupData – The Admin Console options and data.
  - UserId and CompanyId
  - Report – The current report object.
  - JavascriptAction – This object is set when sessionInfo is called from an action event. It is primarily used to load the client-side Javascript:
    - JavascriptAction.SetJsCode(string JsCode) – Pass the client side code as a string. The action event must return the JavascriptAction object.

- clientInfo – A JavaScript object that is accessed from within the client-side script. Provides access to any specified client-side parameters and information about the item attached to the event handler. For a breakdown of the elements in clientInfo, see ClientInfo.

arguments array – The server-side portion of action events can also access an array of input values called args. These parameters are passed manually from client code to server code using the function `clientInfo.ServerCallback(eventName, args...)`.

## JavaScript

> Note: This is only available in Windows environments.

Both the server-side and client-side code for action events can be written in JavaScript. The client side code must still be passed to the sessionInfo.JavascriptAction object as a string. This can be done by calling toString() on a function, then concatenating the invocation operator, before passing it to the JavascriptAction.JsCode. This can be an easier way to write client scripts since the code is written natively, instead of as a string literal. However, note that writing server code in JS means that it cannot access any C#, .NET, or CLR libraries.

Selecting JavaScript from the Custom Code window

### Example of writing client-side JS in the Custom Code window

    // this function wraps the client-side code
    function debug() {
        debugger;
    }

    /* any other server-side processing can be done in JS */

    // call Function.toString() on the client-side function, then concatenate
    // the "invoke" operator (), before passing it to the JavascriptAction
    var jscode = "(" + debug.toString() + "());";
    sessionInfo.JavascriptAction.SetJsCode(jscode);
    return sessionInfo.JavascriptAction;

> Note: The clientInfo object is only accessible from within the client code, not on the server. However, it could be passed to the server in a callback as JSON using `clientInfo.ServerCallback("eventName", JSON.stringify(clientInfo));`. This will require either two separate action events - one to send the object, and one to receive it - or one with some conditional logic to handle both cases.