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. Throughout this document, the term host application is used to refer to the application that implements Exago BI as its reporting platform.
There are three main components to the Exago BI system:
- 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 in Windows; or Apache and NGINX in Linux. At minimum, there must be 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 infinitely and dynamically deployed in singleton or in clusters in any combination for:
- load balancing of on-demand report execution, called Remote Execution
- scheduling reports to be executed sometime in the future on either a periodically recurring or single-run basis
- e-mailing reports either immediately or sometime in the future to a single e-mail address, or a group of email addresses in either mass distribution or individually personalized output (similar to report bursting or mail merging, called batch scheduling in Exago BI)
- caching report execution data for frequently executed or data source intensive reports. See Data Model for more information
- API — The embedding host application interacts with Exago through one of two APIs — a .NET API or REST Web Service. Everything in the Exago BI configuration is accessible via an API endpoint. In order to support single sign-on, the host application passes user identity, roles, and configuration preferences to the Web Application through the API, which creates a single 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. REST requests can be encrypted via SSL and a several authentication methods are available for securing REST calls.
Each of these components is installed with a full-service installer package on both Windows or Linux. 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.
End users interact with Exago via a user session. User sessions are collections of settings and permissions that define what options, features and reportable data is available to them. When an end user accesses the embedding host application, it sends the user's identity to the Exago API, then the application's custom integration code determines what the 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, customizing the language, 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 in turn opens up a tailored version of a report, Dashboard, or the report building interface.
Sessions are single use. Once a user is launched into the session, it is considered to be consumed, and changes are no longer permissible. From a security perspective, this prevents any communication with Exago from happening outside of the host application or unintentional session reuse circumventing user authentication.
The Admin Console and Configuration Files
While a complete session configuration can be built programmatically from scratch for every new session, Exago utilizes 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 session setup. 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.
After installing Exago BI, the next logical step is to create this base configuration. This can be done with the Admin Console, an interactive interface to build Exago BI base configuration files.
On the very first launch of the Admin Console, the default configuration file
WebReports.xml and its encrypted counterpart
WebReports.xml.enc is created in the Web Application's
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
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 data 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. Therefore, it is inadvisable to modify configuration files that may be in use in a live environment, or risk closing sessions on users working with the application.
Think of the Admin Console as a configuration builder, not as a control panel or instrument cluster. Typically, the Admin Console is used to create the base configuration with some light modifications during testing and development. The plain-text
WebReports.xml file, and the entire Admin Console component itself can be removed from production servers for security, leave only the encrypted
WebReports.xml.enc file behind.
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.
Exago BI stores reports, folders, document template files and theme files in a robust and reliable relational database system called Storage Management. Out of the box Microsoft SQL Server, MySQL, Oracle and PostgreSQL are supported for Storage Management databases. Exago can also access a SQLite file use during testing and demonstration. Use of SQLite for a production storage solution is not recommended.
As access to the report and folder repository is essential to all Exago BI operations. setting up Storage Management should be the very first configuration step with the Admin Console. Shortcuts for creating the schema in the database, loading the chart and map themes and verifying the database's connection and schema make the initial configuration simple.
The Storage Management system implements a flexible permissions model for content based on the concept of parties and inheritance. By setting the value of variables called identity keys with an API, a logged in user will have certain access rights to content based on their parties' privileges. A series of bit-wise access flags enable or restrict access to individual reports, whole folders or the entire report repository. The content creator, called the owner, retains full access to the content regardless of the other access flags.
This model 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 in the database is referenced by a unique identifier instead of its name, although this is transparent to end-users. Therefore, reports or folders may have 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.
Moving from one database type to another or upgrading from a testing SQLite repository can be automated with the use of command line utilities provided by Exago. Exago's Storage Management Utility is available as a separate download for administrators to analyze and modify their Storage Management database contents, flags and access rules as needed.
To learn more about the storage of reports and files in Exago review the resources below or contact an Exago Sales Engineer.
After configuring Storage Management, the next step is typically to define the data model from which Exago generates its reports and visualizations. While other applications may ask for the construction of specific data sets or models, Exago's data model is defined in its entirety as an application-wide metadata layer. 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.
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 data sources are then queried as needed to compile the report's output. Exago does not store or cache data, working with data in an on-demand read-only basis. For very frequently executed reports or those with intense queries or database loads an optional Execution Cache can be enabled on a per-report basis.
The system administrator needs only to define the data model once, and end-users need not think about the data model at all. During the definition stage, the system administrator can optionally re-organize, re-name and simplify the data model to make it intuitive for end-user consumption.
Since the digestion of data is so fundamental to the application's function, it is important to carefully think about and consider how the data is made available to Exago BI. An extensive explanation of report data stewardship can be found in the Exago documentation and technical training resources. In general, to accentuate performance and end user experience consider these points:
- To reduce the size of the diff when building sessions, incorporate as much as the data model into the static base configuration as possible. Avoid building data objects programmatically, for a single use or on a per-session basis. The best performance will be realized when utilizing the same simple data objects for every session.
- Carefully plan out that data actually needs to be available for reporting
- Normalized data sources with a large number of joins can slow down report generation. However, keeping data in a single table is also not recommended. A good balance of de-normalized data spread across a few tables is ideal.
- Reduce the number of data columns in a data object, or use views to reduce the number of columns to only those needed for making reports
- Create a collection of views for ad-hoc reporting. This can de-normalize some of the data, and if done effectively, can make the data model easier to understand. This can also help build-in some filter and business logic that the data owners would expect for the reports.
- Make sure that fields and data objects are named in a clear way. Exago's metadata layer supports object and column aliases, descriptions and column visibility options. Organize data objects into folders. If there are many different data objects, it's a good idea to group similar purpose objects into folders that explain that purpose.
A data source as its name entails—is the origin holding the data. A myriad of data source types including flat files, relational databases, non-relational databases and data warehouses are supported. The best performance and compatibility will be achieved with relational SQL based data sources.
Exago BI uses a standard connection string to connect to a Data Source. The specific requirements for these strings are dictated by each database provider. In general, and at a minimum, the string contains the URL to the database, the database name and access credentials. As previously mentioned, Exago only requires read-only access to the reporting data source.
Use the Admin Console to supply the connection strings to the various reporting Data Sources. 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. Most environments utilize only a single data source, but there is no practical limit to the number of Data Sources that may exist in the configuration.
After at least one Data Source is added, objects (the tables, views, functions and stored procedures in the Data Source) and their joins can be added manually or automatically with the Automatic Database Discovery tool. Joins are created by examining the primary and foreign key constraints between objects. Views and other types of objects require manually configuring their primary keys and joins. Programmable objects (i.e. 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 in the configuration as well as custom data object columns written as Exago formulas.
Data objects are referenced in reports by an Exago field called the Id. In the same way that the Storage Management system references content with a unique identifier, data object IDs are meant to be permanent references to an object and transparent to end-users. Changing the object metadata (besides the Id) does not necessarily break reports, since the ID reference remains intact.
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 is stored with the report's definition. This allows further manipulation of joins at the report-level without modifying the underlying base configuration. Joins can even be constructed entirely in the reports themselves, without the need for any in the configuration if desired, depending on how data is structured in the Data Sources and what data is pertinent to a report. This level of customization may also be desired when there are multiple paths between objects.
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 Exago aggregates, builds SQL queries for reports, and can have an impact on performance.
Whenever possible Exago BI pushes 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 calculations. In certain circumstances, database aggregation is not possible when aggregating on the "one" side of a one-to-many join. Therefore, it is very important that the join configuration accurately reflect the relationship between columns.
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 by the host application, the user's identity can be passed to Exago through the API. A number of things can be accomplished by providing a user's identity to Exago, such as:
- customizing brand identity, language or cultural settings
- enabling or restricting availability of certain features based on the concept of a user Role
- customizing report output or behavior
- enabling or restricting access to certain folders or reports
- enabling or restricting access to certain data, called Data Tenancy, tenanting or a multi-tenant environment
While Exago does provide some layer of user identity and can limit access features and data as described in the following sections, it is important to remember that it is ultimately up to the embedding host application to authenticate and properly configure the session for each user's privileges.
It should also be noted that user identity and data tenancy are not the only layers of security available in in Exago. More details about security features such as sanitizing user input; preventing SQL injection attacks; securing communication between Exago components and the host application can all be found in their respective articles in the Exago documentation. This section is meant to introduce the core concepts of user identity and security layers in Exago, and not be a replacement for an exhaustive discussion on holistic application security, which should be handled on a case-by-case basis between engineering teams and Exago BI's Support and Client Experience groups.
There are two concepts of a user identity in the Exago BI system:
- The previously discussed Storage Management identity keys, and
- Exago BI parameters that identify the user to the other components in the application.
User Identification Parameters and Storage Management Identity Keys
There are two built-in variables, called parameters, that are used throughout the Exago system to identify a user, or more generically a user session. Named userId and companyId, they hold a user's identifier and a company or group identifier respectively.
While their name alludes to a specific use case, they can hold any identifying attribute about the currently logged in user or session. These parameter values can also be used in reports themselves, or in filters used to limit the returned data.
Although 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. Use of the userId and companyId parameters is optional, although recommended.
An Exago BI role is a set of customizable user characteristics that defines their environment. Use a role to override base configuration settings by simply activating one in the session with the API. Because activating a role requires only a single endpoint change versus the individual change of each individual endpoint, using roles is one way to decrease the diff size when creating sessions.
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.
A role can be independent, or used in conjunction with the userId and companyId parameters to customize the session's properties. Roles have been used for individuals, groups of users or entire companies or industries accessing the application.
Closely linked to the identification of a user, data tenancy refers to the ability of the application to limit data returned from a data source, while usually transparent to the end-user. Tenant filters are added automatically to the SQL statements sent off to the Data Sources during report execution and cannot be changed by the end users, as they are part of the session.
To accommodate a wide range of data models and tenancy schemes Exago BI supports four methods of data tenancy:
- Database-Based — if each individual client or user has data in their own unique database, the Data Source connection string can be changed dynamically while maintaining the same data objects, joins and metadata.
- Schema-Based — if a data source contains data objects with the same name but different schemas, use Schema-Based tenanting. The returned data will be limited to the data objects whose schema name matches the identifying filter value. For example, if tables are named client1.orders, client2.orders, clientn.orders, etc... then setting the tenant filter to client1 allows only that session access to the data in tables with the client1 schema name.
- Column-Based — if a data object contains a column with an identifying value in it, it can be used to filter only those records where this column matches a certain value. Foe example, showing an employee only the orders that they placed by filtering the orders table on the EmployeeID field for that employee's ID number.
- Row-Based — a filter SQL string can be entered to filter by rows. Use Row-Based tenanting to include
INclauses or sub-queries in the SQL SELECT statement executed on the Data Source. Using row based filtering requires the use of an Exago role.
A combination of tenancy methodologies can be combined to create a comprehensive data security layer. Tenanting data can also enhance performance, by limiting the amount of data returned and traversing the network.
There are four report types that are currently available and supported in the Exago system: Dashboards, ExpressView, Advanced Reports and Chained Reports.
- Dashboards combine one or more reports onto a canvas, providing a way to create a personalized arrangement and display of related reports.
- ExpressView is a tool to quickly get insight into vertically expanding data records and groups with a simple drag-and-drop interface. An ExpressView can optionally include a visualization. Due to this simplicity, ExpressView can get a report started very quickly, and then it may be transformed into an Advanced Report for further editing and design.
- The most powerful reporting tools are available with Advanced Reports, including geographic maps; CrossTabs; repeating groups; complex join, filter, and sort logic; drilldowns to linked child reports, and more. Advanced Reports are made using an spreadsheet-like cell-grid interface and used for creating pixel-perfect reports.
- Chained Reports combine multiple ExpressViews or Advanced Reports into a single multi-page document that can be downloaded, e-mailed or scheduled Dashboards may also be exported to a file in Chained Report format.
There are over 72 individually configurable settings that affect the end-user experience as it pertains to the use and application of the the report building tools. Each of these report design and execution tools, or portions thereof, can be turned on or off in any combination per session. For example, permitting only those users who have passed a training program to access Advanced Reports. Or, only allowing certain users to execute reports, while allowing others edit capabilities after saving a new copy of it for themselves.
Each report type may be exported as a downloadable file in PDF, Excel workbook, RTF or CSV format. Reports may individually restrict certain output types, or they may be disabled system or session wide.
Reports are stored as XML text documents in the Storage Management database with an Exago proprietary schema. Modification of the report XML contents is not recommended or supported. The .NET API can be used to programmatically manipulate reports if necessary.
Customizing User Experience
Exago is flexible with appearance and data presentation through the use of themes, languages and culture/locale settings.
All text strings including the names of application components, dialogs, messages, tooltips, function names and categories are translatable through the use of dictionaries called language files. Exago provides English and Spanish language files out-of-the-box, but translating Exago into other languages is easily accomplished by creating a new set of files. Once translated, changing the Exago interface from one language to another is as simple as changing a single configuration endpoint to point to the correct language file dictionary.
Optionally through the use of extensibility, automatic and dynamic data translation can be built in to the report execution cycle via third-party online translation services.
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 in the session.
Styling and Branding with Themes
Exago BI comes with a number of Element Themes built in to the different report designers and visualization builders. These themes can be added to, edited, or removed based on preference and branding requirements. The Default chart theme provided by Exago is WCAG level AA compliant and color blind accessible.
An application theme styles the entire Exago Web Application user interface.
An application theme builder built-in to the Admin Console creates the framework for the new theme. Accommodation for overriding icons and CSS styling rules are available to integrate Exago deeply into the embedding application's look and feel, or to meet branding requirements once the theme is created.
To learn more about customizing Exago review the Styling Exago article or contact an Exago Sales Engineer.
Mentioned several times throughout this article, the term extensibility refers to the ability to extend Exago's out-of-the-box functionality to customize its behavior and available options. Exago can be extended in a number of ways:
- Custom parameterized SQL data objects can be built at the configuration, session or report level without the need for a database administrator to be involved
- Programmable Data Objects, such as .NET Assembly Data Sources can be integrated into Exago's data model just as standard data sources can. Users will see no difference between a custom data source and a standard one. This is often used when reporting from custom non-traditional data stores or when needing to implement a custom existing business logic layer before data reaches Exago.
- Server Events are hooks into the application's runtime cycle that allow additional code to be executed alongside Exago's normal operation. For example, a Server Event that is triggered just as report execution starts could check to see if there are filters set on the report. If there are no filters, which could cause a tremendous amount of data to be returned, report execution can be programmatically cancelled and a dialog box displayed to the user asking them to add a filter. Another server event trigger at the end of the SQL generation phase could be used to log the generated SQL statement for tracking or debugging purposes, or even modify it. There are 28 of these built-in global server events, and additional triggers may be added to individual reports.
- Action Events are handlers on the client side of the application that allow users to take custom actions on user interface elements, such as the click of a toolbar icon, chart element or reports on a Dashboard. Like Server Events, they can be used to hook into normal application behavior. For example, catching the click of the Save icon in the Report Designer to display a custom message, save dialog, or re-direct the save operation entirely.
Exago will run on both Windows and Linux servers, both on-premises and in the cloud. Exago and its components have been successfully implemented on Azure virtual machines, AWS EC2, in Docker containers, in web farms and on standalone single servers. The three components (Web Application, Scheduler Service and REST Web Service API) need not be co-located, since they communicate over standard HTTP or TCP ports. The only requirement is that they have the same version and build number. This also means that they must use the same operating system for the entire deployment—Windows Web Application servers can only communicate with Windows Scheduler Services and REST Web Service API servers, for example.
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
A test application demonstrating the placement of non-Exago text content (top-left), an ExpressView visualization (top-right) and the Advanced Report Viewer (bottom) on the same page using
- The REST Web Service API provides access to Exago in a secure, familiar, platform agnostic and easy to scale way. However, because communication with Exago's Web Application occurs over the network, it may operate slightly slower than a .NET API application, all other things the same.
- The .NET API is an excellent choice when the host application is also .NET, as it will offer the best performance on a Windows system and a "close to the bare metal" approach to integration. If custom runtime manipulation of the report structure is required, using the .NET API is required as report manipulation endpoints are not exposed to the REST Web Service API.
Similar to a discussion on security, careful thought should be given to how Exago is to be deployed, embedded and integrated into a host application and how end users consume it. The technologies deployed in the host application and Exago will influence the embedding methodology chosen. An Exago sales engineer, Support Analyst or Professional Sales Engineer can make recommendations on specific use cases and technologies.
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.
In addition to the resources available online, contact an Exago Sales Engineer for personalized assistance.