Exploring Exago Technology

Welcome to Exago! We’re happy to have you here. Exago BI is a .NET web-based, white-labeled, embedded business intelligence application.

Use this document to understand how the Exago platform works.

Components

There are three main components to the Exago BI environment:

• Web Application — As the primary component, the Web Application is responsible for serving the user interface, executing reports, and maintaining session state. The Web Application runs on IIS (Windows), Apache or NGINX (Linux). At minimum, an Exago implementation must contain at least one web application server. Multiple web applications can be deployed in a web farm with a state server and load balancer.
• Scheduler Services — Scheduler Services are optional report execution engines that can be deployed in clusters for load balancing (this is known as Remote Execution). The Exago implementation must contain at least one Scheduler Service if support for scheduled executions, emailing, or report bursting are needed.
• API — The embedding host application interacts with Exago through one of two APIs — a .NET API or REST Web Service. In order to support single sign-on, the host application passes user identity, roles, and preferences to the Web Application through an API which creates a one-time use user session.
  • The .NET API integrates the embedding host application with Exago using standard .NET assemblies.
  • The REST Web Service API provides methods for language- and platform-agnostic integration using encrypted network queries without the need to use .NET.

Each of these components is installed with a full-service installer package for both Windows and Linux operating systems. On Linux, the installer can install Exago’s system dependencies including the mono framework.

In addition to these components, Exago BI also supports a wide array of Extensibility options to extend out-of-the-box functionality.

Review the Application Architecture diagram for a visual representation.

User Sessions

End users interact with Exago via a user session. User sessions are collections of settings and permissions that define what options and data available to them. When an end user accesses Exago through the embedding host application, it sends the user’s identity to the Exago API, then the application’s custom integration code determines what this user should have access to. This could range from turning report designers on or off, enabling or disabling features, applying different sets of data tenancy, and even customizing the branding and styling of the end user interface.

All of this happens dynamically—Exago has no additional authorization layer and does not store user data. It is completely transparent from an end-user’s perspective. Users simply click a link in the host application, which opens up a tailored version of a report, Dashboard, or the report building interface.

The Admin Console and Configuration Files

While a complete session configuration can be built programmatically from scratch for every new session, Exago supports a base plus diff model which can be more convenient and performant.

The base configuration files can contain all or parts of the Exago BI configuration. This base configuration is then used as the basis for user sessions as they are created with an API. The APIs make session-specific modifications to the configuration that only last for the duration of that session.

Basic block diagram demonstrating how the settings a, b and c from the base configuration file form the basis of the two user sessions generated by API calls. The API calls modify their own settings (d, e, f, g and h) based on the needs of that particular user or session, and the resulting session is a combination of these settings

After installing Exago BI, the next logical step is to begin the creation of this base configuration. This can be done with the Admin Console, an interactive control panel to build Exago BI base configuration files.

Broadly speaking, the configuration information needed for a session includes:

• Storage Management settings
• the data model and database driver settings
• data tenancy
• cultural/locale settings
• user security settings
• general settings, such as enabled/disabled components

On the very first launch of the Admin Console, the default configuration file WebReports.xml is created in the Web Application’s /Config directory. Creating a session through the API starts from the base configuration and then creates a diff based on the programmatically made changes in the session. The diffs are packaged up and stored on the state server, one for each session. Therefore, the base configuration file is best used for storing static session information such as the date model, roles and collection of default settings.

Whenever an action in the user interface requires retrieving configuration data, Exago BI reconstructs the configuration by diffing the base configuration with the session specific data. The larger the diff, the longer this process takes. Therefore, minimizing the dynamic API changes increases user interface performance.

Additionally, this means that if the base configuration were to go missing or be modified, any currently running sessions would be unable to reconstruct the configuration and become invalid. For this reason, it is inadvisable to use the Admin Console to modify configuration files that may be in use in a live production environment, or risk closing sessions on users working with the application.

To learn more about user sessions, configuration files and Admin Console, review the Modifying Configs in a Production Environment article, Admin Console documentation or contact an Exago Sales Engineer.

Content Storage

Exago BI stores folders, reports, document template files and theme files in a relational database system called Storage Management.  Microsoft SQL Server, MySQL, Oracle and PostgreSQL are supported for Storage Management databases, as well as a SQLite file for testing and demonstration purposes.

Access to the Storage Management database is required for any use of the application, so setting up Storage Management is one of the very first configuration steps when building a configuration with the Admin Console. After specifying the connection string, the Admin Console features shortcuts for creating the schema in the database, loading the themes for charts and maps and checking the connection to the database.

The Storage Management system implements a flexible permissions model based on the concept of parties. By setting the value of identity keys with an API, a logged in user will have certain access rights to content based on their parties’ privileges.

This allows, for example, the creation of a My Reports folder that saves only reports created by and accessible to a single user; and a Public folder available to all users of the system. Depending on administrator preference and implementation, content may be moved freely in and out of these and other folders in the repository. Content such as reports or folders may have a unique parents depending on the logged in user. For example, a sales report may appear in a “Sales” folder for all employees of a company except for the Sales Manager, where it appears in the “My Reports” folder.

Additional Resources

To learn more about the storage of reports and files in Exago review the resources below or contact an Exago Sales Engineer.

• Storage Management: Introduction
• Admin Support Lab — Storage Management Overview (video)
• Application Settings
• Accessing the Log File

Data Model

The first step in defining the base configuration is to define the data model. While other applications may ask for the construction of specific data sets or models to be used for specific groups of reports, Exago’s data model is defined in its entirety as an application-wide metadata layer. When a report is created in the a Report Designer, the most efficient data model for that report is constructed automatically depending on the data required. The system administrator needs only to define the data model once, and end-users need not think about the data model at all.

Data Sources

A data source as its name entails—is the origin holding the data. A myriad of data source types including relational and non-relational databases, flat files and data warehouses are supported.

Use the Admin Console to supply the connection strings to the various reporting Data Sources. Of course, Data Source connection strings may also be set programmatically in their user session when each user or client has their own Data Source specific to them.

Data Objects

Once at least one Data Source is added, the data discovery interface allows for quickly adding all of the objects and joins. Tables and their joins can be added automatically by simply selecting the objects to add. Joins are created by examining the primary and foreign key constraints between them. Views and other types of objects require manually configuring their primary keys and joins. Programmable objects (e.g. stored procedures, functions) may require some additional configuration in order to ensure optimal performance.

Since the entire data model in Exago BI is metadata, all SQL and joins are constructed dynamically when reports are executed. The model in Exago doesn’t necessarily even need to match the model in the Data Source, and joining objects across Data Sources is possible. Exago supports custom data objects, written as custom SQL statements as well as custom data object columns written as Exago formulas.

By keeping the data model in a metadata layer, Exago can access critical information such as data source or data object schema with virtually no latency it would otherwise encounter by querying the Data Source each time.

Joins

A join is a relationship between data objects based on an equality (or inequality with the Advanced Joins feature) between fields in those objects. Any number of joins may exist in the system, and cross-data source joining is possible, although less performant. Joins are added manually or can be discovered when using the aforementioned Automatic Database Discovery Tool. Automatic discovery requires that primary key and foreign key constraints be well defined on data objects that support them.

Joins are unique to the other data model items in that when a report is created, a version of the join configuration in the base configuration file gets stored in the report’s definition. This allows further manipulation of joins at the report-level without modifying the underlying base configuration.

Each join in the configuration has the following properties:

• to and from columns
• the join type — either inner, left outer, right outer or full outer (depending on types supported by the Data Source)
• the relationship type — either one-to-one or one-to-many
• weight — a designation of priority when there is more than one join path between columns

The join type, relationship type and weight will affect how the application aggregates, builds SQL queries for reports and can have an impact on performance.

Whenever possible, and when the feature is enabled, Exago BI attempts to push as much aggregation and formula processing off to the Data Sources. This minimizes the amount of returned data that must traverse the network and the amount of in-memory calculation that must be done when generating report output. In some circumstances, when aggregating on the “one side” of a one-to-many join,

Tenancy

Tenancy refers to the ability of the application to limit data returned from a data source based on some kind of identifying filter, while being transparent to the end-user. Tenant filters are defined for each session.

Exago BI supports four methods of data tenancy:

• Schema-Based — if a data source contains data objects with the same name but different schemas based on a tenant value, use Schema-Based tenanting. The returned data will be limited to the data objects whose schema name matches the identifying filter value.
• Database-Based — an extension of Schema-Based tenanting. If the tenant data is stored in an entirely unique database, the connection string can be set on a session-by-session basis and still maintain the same data objects, joins and metadata.
• Column-Based — if a data object contains a column with the tenant filter value in it, a parameter can be used to filter only those records where this column matches the parameter value. This provides a simple and effective way of including the rows from the data object that are relevant to the current user.
• Row-Based — A filter SQL string is entered directly for this tenanting type. Use Row-Based tenanting to include IN clauses or sub-queries in the generated SQL.

A combination of tenancy methodologies can be combined to create a comprehensive data security layer. Tenanting data can also enhance performance. Consider a table with millions of patient visit records for a medical group. By tenanting the data so Exago BI only returns the patient visits relevant to Dr. Dukane’s office, network latency and system resource demand is reduced.

Additional Resources

To learn more about the data model and the different options available, review the resources below or contact an Exago Sales Engineer.

• Data Sources
• Data Objects
• Join Configuration
• Advanced Reports: Joins
• Admin Support Lab — Joins (video)

User Identity and Data Security

As an embedded application, Exago BI provides no login authentication logic of its own—it is up to the embedding host application to request and verify user credentials. Once authenticated, Exago does need to know who the user is and what they should or should not have access to.

User Identity

There are two main concepts of a user identity in the Exago BI system. The first are the previously discussed Storage Management identity keys. The second are Exago BI parameters that identify the user to the other components in the application.

User Identification Parameters and Storage Management Identity Keys

There are three built-in variables, called parameters, that are used throughout the Exago system to identify a user. Named userId and companyId, they hold a user’s identifier and their company or group identifier respectively. These values are set with one of the APIs as the session is beginning. The third, userEmail, is available for use with the Scheduler Service. Any number of additional parameters may be added later.

While they share similar names, the User Id, Company Id, Class Id and Owner Id Storage Management identity keys work separately from these parameters. The Storage Management identity keys only affect content storage while the userId and companyId parameters are referred to by other parts of the application.

Roles

An Exago BI role is a set of user characteristics that defines their environment. Use a role to override base configuration settings by simply activating one in the session with the API. Roles can be used to restrict access to folders in the Report Tree, to filter the available data objects in the Report Designers, set certain culture or locale values amongst other things. A single role may be active in an individual user session, but any number of roles may be added to the configuration and active simultaneously in other sessions.

For example, a ‘sales-manager’ role may only be able to access the data objects related to sales figures or run and edit reports from the Sales folder in the Report Tree, while the ‘ceo’ role can see all of the reports for the company.

A role can be independent of the userId and companyId parameters.

Customizing User Experience

Exago is flexible with its appearance and how it presents data through the use of themes and culture/locale settings.

Themes

There are two types of themes in Exago BI: Element Themes that style parts of reports such as charts or map visualizations and Application Themes which style the user interface itself.

Element Themes

Exago BI comes with a number of Element Themes built in to the different report designers. These themes can be added to, edited, or removed based on preference. A default theme can be applied automatically in some instances.

Application Themes

The included Basic blue application theme can be changed on a per-session, per-role or per-system basis to another color. Creating new application themes can be as simple as choosing a new color from the Admin Console, or as detailed as generating all new icons for the application. Exago BI allows for overriding all of its CSS styles.

The Report Filters dialog in the Advanced Report Designer with the default Basic Application Theme (top) and the same dialog with a custom Application Theme using a chocolatey brown (#744400) as the main color

Localization

Text strings including the names of application components, dialogs, messages, tooltips and more are translatable through the use of dictionaries called language files. Exago provides English and Spanish language files from the factory but translating Exago into other languages is easily accomplished. When translating Exago it is easiest if the translator speaks English and the translated language.

In addition to language, Exago BI can display different currency symbols, decimal separator symbols, thousands separator symbols and accommodate time zone changes through the use of the General settings available at both the base configuration level and the Role level.

Additional Resources

To learn more about customizing Exago review the Styling Exago article or contact an Exago Sales Engineer.

Embedding

As previously mentioned Exago BI is designed to be embedded into a host application. Exago supports several different embedding techniques, but the most popular are the use of inline frames (iframes) or placing components into <div> elements with the Exago JavaScript API.

The Inline Frame or JavaScript API? article provides an explanation of the differences between embedding methods and weighs the pros vs. cons of each.

Getting Help

Review the Where To Find Documentation, Support, and Training Resources article for a comprehensive list of resources available to both end-users, administrators and developers.