Note

This version of the .NET API documentation is deprecated. A new version can be found at https://www.exagoaccess.com/api-docs/.

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:

• Data Security: controlling access at the source, entity, row, column or custom level
• Report Security: controlling read/write and visibility of reports through folders
• Culture Settings: such as language, date and time format, currency symbol, etc.
• Available Features: toggle on/off designers and other features

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:

• User A, using Data Source DS_A
• User B, using Data Source DS_B

Use the Administration Console to:

• Create a single Data Source, using either the connection string for DS_A or DS_B 
• Build the metadata, normally using the Admin Discovery capability

 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:

• Create an Exago Parameter named "AccountId"

• Use the Data Objects tab to associate the AccountId Parameter with the AccountId field of the entities you want to secure

Use the API to:

• Set the AccountId parameter's value to the appropriate one for the currently logged-in user

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.