# An Overview of Exago Extensions

Exago extensions allow developers to access, extend and modify the platform's capabilities to suit particular needs that can't be handled "out-of-the-box".

The interface for most capabilities is via coded elements, done either via Code Editor in the Administration Console or external code modules provided via .NET Assemblies or Web Services. Other situation-specific options are also available, such as providing custom, parameterized SQL.

## Overview

The following extension types are supported. More information on each type is provided in the remainder of this document:

- Custom SQL
- Custom Functions and Filter Functions
- Server Events
- Action Events
- Custom Data Sources
- External Interface
- Custom Options

## Custom SQL

Exago supports a Custom SQL type Entity. Objects of this type are very similar to pre-defined database views. They consist of a SQL statement, have an implied field schema and return a relational value.

There are a few differences from traditional database views however.

- Exago Custom SQL statements can be parameterized. In other words Exago parameters can be embedded within the SQL statement. Parameters serve as placeholders for runtime values. Upon execution of a report any parameter values will be replaced with the value of the parameter at runtime. Any part of the SQL statement can be parameterized in this way.
- Exago Custom SQL statements behave like any other entity type. Administrators can attache column metadata. Report designers can filter, sort and layout fields from the entity, etc.
- Since the SQL is stored in the Exago configuration no intervention by database administrators is required.

### Adding Custom SQL

Add a new Data Object and select the Data Source from the dropdown. Instead of selecting a table or view from the name field, click the SQL button on the right of the name field.

You will be presented with the SQL code editor. Specify a name for your Data Object (no whitespace or special characters) then enter your SQL as shown.

Notice the @StartDate@ and @EndDate@ parameters. They can be manually typed or inserted by selecting from the list of Parameters and selecting the Add button.

When finished select Ok to save your object's information. You can then specify and Alias and select Unique Key Fields like any other object.

> ### The `SessionInfo` Object

> The global `SessionInfo` object is available to Custom Functions, Server Events, and Action Events. It is similar to the API object in that it contains the full running state of the Exago system during execution.

> Collections of metadata and settings normally set in the Administration Console and/or via the API are accessible through the `sessionInfo.SetupData` property. Note that for the most part the accessible properties are settable via SessionInfo.

> SessionInfo also contains a key object store accessible via two methods:

>     void sessionInfo.SetStoredValue(Object key, Object value)
>     Object sessionInfo.GetStoredValue(Object key)

## Custom Functions and Custom Filter Functions

Custom Functions and Custom Filter Functions allow developers to create abstracted high level language routines that are used by report designers. Standard Custom Functions appear in the Exago Formula Editor as if they were part of the product. Custom Filter Functions are available to use as values in user formulas.

Both types of functions have access to the SessionInfo object, creating powerful opportunities for context-sensitive processing as well as storage. In the case of Custom Functions, global storage can be used to maintain counts as the report is processing.

## Server Events

Server Events are handlers invoked on the server side during the normal execution lifecycle. They allow developers to inspect and/or modify running state to achieve situation-specific objectives. Server Event handlers also have access to the global `SessionInfo` object, providing the same global storage and state variables as mentioned above.

A commonly used event is the `OnReportExecuteStart` event, which allows the handler to make modifications to a report just prior to execution. Another commonly-used event is `OnExecuteSqlStatementConstructed` which is invoked after Exago generates SQL but before it is shipped to the data source. This event can be used to simply log the SQL for audit or diagnostics or to modify it to e.g. substitute actual fields for placeholders.

## Action Events

Action Events are handlers invoked on the client side during the normal execution lifecycle and include an abstracted interface for server-side callbacks to gather data as needed and perform similar tasks. They offer a rich interface for modify charts and dashboard reports in response to user actions. There are also specific interfaces to allow trapping and instrumentation of things like user saves.

## Custom Data Sources

In additional to traditional relational data sources Exago can consume data from programmable data sources such as .NET assemblies and SOAP-based web services. Connection to and marshalling of the data sources is handled at the metadata layer, just like standard sources. This capability provides two key benefits to end users:

- Data from multiple disparate sources can be combined into a single report, visualization or dashboard
- The end user view is the same regardless of the type of data source. Users will see no difference between relational and programmable data sources when building reports and dashboards.

Custom data sources are often used when it is desirable to make use of an existing business logic layer such as a means to pull data from non-traditional or distributed sources.

## External Interface

The External Interface is a set of pre-defined event types that can be trapped and instrumented. External Interface events are similar to Server Events with two key differences: External Interface can be invoked via web service (whereas Server Events require code developed using the Administration Console code editor or via .NET assemblies). As a result External Interface methods do not have access to the global SessionInfo object.

## Custom Options

Custom Options allow administrators to alter the Exago UI to capture custom input from report designers. The values chosen by the designer are available via the sessionInfo object and are thus accessible to Server Event and Action Event handlers.