Exago does not have native user authentication. User logins must be handled by a security layer in the embedding host application. After a user logs in, the host application should pass identification parameters to the Exago API, which can be used to set permissions on content and data objects within Exago.
Storage Management Identity Keys
Review the Storage Management: Introduction article's Identity Keys section to learn about how these keys affect the application. These keys should be set along with the System Parameters each time an Exago session is created via the API.
Setting the Identity Keys
ImportantThe identity key values are case-sensitive.
.NET API
Set the User Id:
api.SetupData.StorageMgmtConfig.SetIdentity(key,value)
Replace key with the name of one of the identity keys, either:
- userId
- companyId
- classId
- ownerId
Storage Management also allows for creating custom identity keys by modifying the XML configuration file and party type table. Any custom identity keys may also be set with this call.
REST Web Service API
Use the /rest/StorageMgmt endpoint to PATCH identity key values to the session. For example:
"Identities": {
"userId": "aboy",
"classId": "user",
"companyId": "Exago, Inc."
}
Reading Values of the Identity Keys
The embedding host application may want to read the values stored for each of the identity keys.
.NET API
The following call will return the corresponding value:
api.SetupData.StorageMgmtConfig.Identity(key);
Replace key with the name of one of the identity keys, either:
- userId
- companyId
- classId
- ownerId
REST Web Service API
Use the/rest/StorageMgmt endpoint to GET a complete Storage Management Configuration JSON object, then examine the object's Identities property. More information can be found in the REST — Storage Management article.Storage Management also allows for creating custom identity keys by modifying the XML configuration file and party type table. Any custom identity keys may also be read with this call.
System Parameters
Exago has two built-in parameters which are used to store identifying information: userId and companyId. These parameters are used in conjunction with the Scheduler Service and User Preferences, and they are automatically passed to any extensions which may need to access authentication. Folder Management, External Interface, Scheduler Queue, and any extension which can access sessionInfo (such as Assembly Data Sources or Server Events) can retrieve these parameters in relevant methods.
NoteThese are required parameters. They cannot be deleted through the Admin Console, and if they are not present in the Config, then they are automatically added at load time.
Often userId corresponds with a unique user or log-in, and companyId represents a group of users with shared characteristics. Either parameter can be used without the other.
userEmail v2018.2+
The userEmail parameter is a third built-in parameter that can specify an email to be set as the "Reply To" email for any scheduled reports. If using the userId or companyId parameters to identify the user, it is possible to change the default value of userEmail to be specific to the users identified by userId or companyId. See below for an example of this in the .NET API and REST API. For more information about this parameter see Scheduler Reply To Address.
Setting the current user
(v2017.2+)
The Id parameters are added by default in the base config file with blank values.
(pre-v2017.2)
The Id parameters are not instantiated by default, and must be created before use. They can be created in the Admin Console, config file, or in the API code. They must be created with the exact names of "userId" and "companyId" (which are case sensitive), with data type "string". Since the values are set in the API, if you create the parameters in the Admin Console or config, they should have blank default values.
Admin Console
As created in the Admin Console:
Config File
As created in the config file:
<parameter>
<id>userId</id>
<data_type>string</data_type>
<value />
<hidden>True</hidden>
<prompt_text />
</parameter>
<parameter>
<id>companyId</id>
<data_type>string</data_type>
<value />
<hidden>True</hidden>
<prompt_text />
</parameter>
The userEmail parameter (v2018.2+):
<parameter>
<id>userEmail</id>
<data_type>string</data_type>
<value />
<hidden>True</hidden>
<prompt_text />
</parameter>
.NET API
As created in the .NET API:
Note"DataType" defaults to DataType.String, so the call is omitted.
api.Parameters.GetItem("userId").Value = "ApiUser";
api.Parameters.GetItem("companyId").Value = "ApiCompany";
For setting the userEmail parameter (v2018.2+):
Parameter userId = api.Parameters.GetParameterById("userEmail");
userId.Value = "user_224@company_17.com";
REST API
As created in the REST API:
Note"DataType" defaults to "String", so the call is omitted.
POST /parameters
{
"Id": "userId",
"Value": "user_224"
...
}
POST /parameters
{
"Id": "companyId",
"Value": "company_17"
...
}
For setting the userEmail parameter (v2018.2+):
POST /parameters
{
"Id": "userEmail",
"Value": "user_224@company_17.com"
...
}
Basic sandboxing
Setting the userId and companyId parameters has several effects in the Exago interface.
Schedule Manager
By default, the 
Schedule Manager will show only schedules belonging to the current userId. This can be changed by modifying the following Admin Console setting:
Scheduler Manager User View Level (Scheduler Settings)
- Current User ('User'): Filters schedules by current userId parameter.
- All Users in Current Company ('Company'): Filters schedules by current companyId parameter.
- All Users in All Companies ('All'): No filtering.
This setting can also be overridden by a Role.
Execution Cache
The userId and companyId parameters are used to set permissions for which users can view cached report data. Users can choose whether a report cache is visible just for their userId, for everyone with the same companyId, or for all users. The options that are available to a user depends on the following setting:
User Cache Visibility Level (Scheduler Settings)
User Preferences
User preferences, including which reports should run on startup and User Reports (live report customization), are set by userId, and will only apply to that user.
Advanced permissions
userId and companyId can be used in many other application areas in order to handle security permissions.
Roles
Additional permissions are typically handled by Roles. A check can be made in the API which maps the current userId and/or companyId to the role which it belongs. This must be handled manually via a lookup table or a similar data structure. Then activate the role for the session.
.NET: api.Roles.GetRole("admin").Activate();
REST: PATCH /REST/Roles/admin?sid={sid} { "IsActive": true }
For more information, see Roles.
Tenanting
userId and companyId can be used as tenant parameters in your data objects.
If your data is set up such that each table, view and stored procedure has columns that indicate which user has access to each row, then you can use userId and/or companyId to match these columns and act as data row filters. (For this purpose, the parameters cannot be set to 'hidden').
For more information, see Multi-Tenant Environment Integration.
Accessing Ids in extensions
userId and companyId are passed to any custom extensions where relevant. For example, in an external interface assembly, you may wish to access the userId in order to log user executions. You could do so by implementing the ReportExecuteStart method, which passes the userId parameter.
public static void ReportExecuteStart(string companyId, string userId, string reportName)
{
string logText = string.Format("{0}: Report '{1}' executed by user '{2}'.", DateTime.Now, reportName, userId);
File.AppendAllText(logFile, logText + Environment.NewLine);
}
This would return the following text upon a report execution by userId "Alex":
2017-03-07 14:50:49: Report 'Test\Product Sales Report' executed by user 'Alex'.
Most extensions have methods which can access userId and companyId. In addition, the parameters are accessible through sessionInfo. So any extensions which can access sessionInfo can also access userId and companyId, even if methods do not explicitly implement them.
The following server event automatically adds the userId to the description text whenever a report is saved.
Global Event Type: OnReportSaveStart, References: WebReports.Api.Reports
Report report = sessionInfo.Report;
string userId = sessionInfo.UserId;
if (!report.Description.EndsWith(userId)) { report.Description += ("\n" + userId); }
return null;