Using the Administration Console and Exago API

Introduction: Understanding the Relationship

The Exago Administration Console and API are used to control and configure a set of metadata that customizes a given user's session.  That customization includes elements such as:

Each available setting has an XML representation in the Exago configuration schema, which means that at any given point in time the current state of a user session can be represented as a set of XML values corresponding to the values as set by the administrator and/or developer.

Administration Console: The Base

The Administration Console (or Admin Console) then is used to create a base configuration.  Think of Admin Console settings as (relatively) static and applying to all users.  When Admin Console data is saved it is stored both to XML as well as to a .enc file that contains an encrypted version of the same XML.  During the standard launch sequence this XML (or .enc) is part of the initial load, giving the host application the base config as a starting point.

API: The Delta

At runtime the host application then makes a series of API calls to customize the user session. These customizations represent the delta from the original base config.  When Exago is launched in this manner the effective user session is thus established as the combination of base and delta or base plus delta.

 

Bringing it all Together

Generally speaking, the Administration Console is used for things that apply universally, while the API is used for things that apply specifically for an individual user.  A few examples will help illustrate this point.

 

 

Example 1: Security at the Data Source Level

This example illustrates how to choose the user's data source (represented by a connection string) at runtime.  For simplicity, we assume that the entity-level schema (tables, views, joins, etc.) is consistent across users; they just need access to different databases.

We have:

Use the Administration Console to:

 At runtime assuming that User A is logged in, use something similar to the following in the API:

DataSource ds = api.DataSources.GetDataSource("dsName");
ds.DataConnStr = <Connection String for DS_A>;

All of User A's queries will use the connection string set at runtime.  However all of the metadata established in the Administration Console will be valid regardless of the connection string used in the Administration Console.

When user B needs to access Exago the same sequence is used, substituting the appropriate connection string of course.  The key point is that different physical data sources can be represented by a single Exago data source, in essence sharing metadata.

Of course if the schemas among the data sources differ, the metadata itself can be modified at runtime via the API's Entities and Joins collections.  When planning your integration consider setting common elements (such as data source type, in-common schema elements, etc.) in the Administration Console, and unique or distinguishing elements (such as connection string in this example) at runtime via the Exago API.

Example 2: Row-Level (AKA Multi-Tenant) Security

This example assumes you've added a Data Source with one or more entities and wish to enforce row-level security on an entity.  we assume for this example that the entity has a column called AccountId that is used for the filtering.

Use the Administration Console to:

Use the API to:

Assuming that the desired AccountId is "39524" use something similar to the following:

Parameter p = api.Parameters.GetParameter("AccountId");

p.Value = "39524";

Based on the association established in the Admin Console, Exago will ensure that any queries against this entity will include AccountId = '39524' in the Where clause.