Exago’s Storage Management system replaces the legacy file system, cloud storage, folder management and web service (SOAP) storage methods with a relational database. All reports, templates, folders and themes are stored in this database. Microsoft SQL Server, MySQL, Oracle and PostgreSQL are supported out-of-the-box. Exago also supports a SQLite database for development, testing and demonstration purposes only.
As of v2020.1, all legacy storage methods are deprecated and are replaced with the Storage Management system. Storage Management enables a flexible folder and report permissions model and creates a future development platform for features such as collaboration, annotation, version control and more.
All reports, folders, report template files, report themes, chart themes, and GeoChart themes are stored in a relational database. This content is stored in a table with some metadata for easy access (e.g. name, description, exports) and general object management (e.g. updated by, saved date).
Report definitions and themes are stored as plain-text in the database. Template files are stored as binary data.
Two new folders will be available for each user in the system:
Review Permissions below to learn more about access controls with Storage Management.
If these folders already exist in the environment before upgrading, new ones will not be created. These folders can optionally be deleted if not desired.
Exago’s Storage Management implementation support the following database types for content storage:
Important
Exago recommends using the included SQLite database for development, testing and demonstration purposes only. Use MSSQL, MySQL, Oracle or PostgreSQL in a production environment.
Content permissions are based on pools of users called parties. The most specific is an individual user, the least is “everyone”. In between are various levels of control based on identity key values. For example, company level access can be granted based on the value of the companyId key. These keys are discussed in more detail in the Identity Keys section below and in Admin Support Lab — Storage Management Permissioning.
Identity keys work in a hierarchical structure that moves from less specific to more specific
When a user attempts to access content (e.g. a report), all of the access records that match the provided keys are sorted according to their priority. The first record from that set (the highest priority) provides the effective access to the content. That access may allow execution, editing, viewing, downloading or no access at all. If there are two content access records that apply to the same user (e.g. there is a match on their companyId and on their userId values) for a content item, the record with higher priority (userId) will apply over the other.
In the figure below, everyone except for user “Nicole” will be able to see “Tim’s Report” in their Report Tree. Only user “Tim” can read, write, rename or share “Tim’s Report”. Anyone in the same “Exago” company (“Travis”, “Tim” and “Alex”) can also write to it as well. Any user (except “Nicole” who is explicitly restricted from it), including those outside of “Exago”, can see the report.
This illustration provides a simplistic way of visualizing Storage Management access. In the actual implementation, access control flags such as “read_access” are bit flags in a single column. More information about these access flags follows.
For simplicity, each access flag is shown in it’s own column in this figure. In practice, access flags are expressed as a bitmap in a single access_flags column. Review the Storage Management: Database Schema article for more information.
A new set of variables called identity keys are used to identify ownership and access rights to content in the Storage Management system. These keys are similar in purpose to Exago’s system parameters @[email protected] and @[email protected] but are specific to the Storage Management mechanism.
Each time an Exago session is created via the API, values for both the system parameters and any Storage Management identity keys should be set. Values for the keys may be set with .NET API calls and through a new REST Web Service API endpoint. Values are case-sensitive, and should be unique across organizations.
Setting the identity keys is not mandatory. However, the Storage Management system will still process access rules with null
as the value for any unset key. Therefore, it is strongly recommended all identity keys are given values when accessing the application.
Four identity keys are implemented out of the box: User Id, Company Id, Class Id and Owner Id. Additional identity keys may be added by editing the configuration file and making appropriate changes to the Party Type table in the database.
For example, consider an employee named “Astro Boy” who works in the “Report Building” department of the company “Exago, Inc.” in Kingston, NY.
A unique identifier for a specific user of the application. For example, “Astro Boy” or “aboy”.
A unique identifier for the organization or company that the User Id belongs to. This key has second priority in the hierarchy above the User Id. For example, “Exago, Inc.” or “Kingston”.
A unique identifier for the user’s class. This key has third priority in the hierarchy above the User Id. For example, “administrator” or “report-builder”.
When a report or folder is created, the owner of that content is assigned to the value of the creator’s Owner Id. For example, “Astro Boy” or “aboy”.
When the Owner Id column of a content item matches the value of the Owner Id identity key, full permission (all access flags are set to true) is granted to that content item automatically.
In most cases Owner Id will have the same value as the User Id key, so that users have ownership of (and therefore full access rights to) content they create. This value doesn’t necessarily need to be an individual user. A company or class can also own content, and so those values are also valid.
Important
If the Owner Id is not set when content is created, Exago will use the value for User Id in its place.
Owners of content will see the Owner
Access Flags assigned to each content item enable or restrict functionality in the application.
Note
Content that has the Can Rename, Can Move, Can Delete and Can Edit permissions all set to false will be considered read-only and marked with the read-only
icon. Folders and reports need the Can View permission to appear in theReport Tree.
When content is created, access permissions are either inherited from their parent; or a single content access record is written based on the parent’s default party type and access flag settings. If the parent’s access flags are all disabled (or missing) then the new content will use the Default Access Flags from the system configuration.
Caution
The Report Tree should contain no more than 1,000 items in it for best user experience.
A new concept for permissions management has been introduced with Storage Management, called inheritance. Functionally, inheritance allows content to “emulate” roles without actually needing to use them. This is meant to provide a migration path away from roles for clients migrating from filesystem or cloud storage, who want to preserve filesystem behavior. However, clients migrating from folder management may want to turn inheritance off, as this behavior is not present in that system.
If a folder’s inherit flag is true, when new content is saved into the folder that content will be assigned all of the same permissions as the folder. All of the content access records assigned to the parent folder will be copied to the new content item.
If a folder’s inherit flag is false, new content in a folder will not inherit the permissions from the parent. Instead of all of the content access records being copied from parent to the new content, a new single content access record will be written with the default access flags and the default party type.
The new Default Folders Public and My Reports have the inherit_flag set to false.
When new content is created in the My Reports folder since the inherit flag is false, any content access records on the My Reports folder will not be copied to reports saved there. Instead, reports saved to the My Reports folder will have a single user level content access record written. The value of the User Id identity key will be saved into this access record, there by granting access to the content only to the current user.
When new content is created in the Public folder since the inherit flag is false, any content access records on the Public folder will not be copied to reports saved there. Instead, reports saved to the Public folder will have a single everyone level content access record written. Everyone access records apply to all users of the system, and therefore the access record will set access for all users.
If either folder’s inherit flag were true, then any content access record on the respective folder would be copied to reports saved in them. This could for example, grant access to another user of a report that should only be visible to a single user in the My Reports folder.
Consider a fictional folder for the “Sales Department” in a company. A simplified version of the content access records are shown in Table A to demonstrate how they work.
Content | Party Type | Party Value | Access Flags | Parent |
---|---|---|---|---|
Sales Department | 2 (company) | Sales Dept | 508 | root |
Sales Department | 4 (user) | Mike B | 511 | root |
When a new report, for example, Quarterly Report is saved to the Sales Department folder, all of the content access records in Table A would be copied on to the new report. Therefore, the resulting content access table looks like Table B below:
Content | Party Type | Party Value | Access Flags | Parent |
---|---|---|---|---|
Sales Department | 2 (company) | Sales Dept | 508 | root |
Sales Department | 4 (user) | Mike B | 511 | root |
Quarterly Report | 2 (company) | Sales Dept | 508 | Sales Department |
Quarterly Report | 4 (user) | Mike B | 511 | Sales Department |
Exago provides a database query tool called the Storage Management Utility that can read from the Storage Management database and display the content access records, access flags and inheritance on content in the system.
In v2021.1+, the utility is a separate download on the Support Site Downloads page. Documentation for this version can be found in Storage Management: Utility (v2021.1+).
The access controls built into Roles essentially sit on top of the Storage Management access flags. This means that Roles can be made more restrictive than the Storage Management mechanism but not less.
If a folder is marked read-only with a Role, a user will not be able to edit, save, delete or rename content in the folder regardless of the access flags or ownership.
Exago recommends choosing one permission model: either Roles or the Storage Management permissions system and not use both at the same time.
Content paths are determined by the access records, thus content can be in different locations for different parties.
Content names in the Storage Management system are case-sensitive.
If the parent’s access flags are all disabled, then the new content will use the Default Access Flags from the system configuration.
Creating new content requires it be saved into a folder. Folders may be saved in the top-most level called the root or may be children of other folders. Reports may only be saved into folders where the Can Save flag is true for that party.
Depending on system configuration, new content can either inherit permissions from their parent folder or default permissions can be set by the system administrator on a folder-by-folder basis.
Moving a content item is essentially the same as creating it in the new location. Content will pick up permissions based on that container’s settings. The existing access records for the content item will be removed, and new records will be written based on the new parent’s settings. Review Creating a New Report or Folder above.
If someone other than the owner of a content item moves it from one folder to another, the item is moved only for that user. A new user-specific access record is added for the content, with the new location.
If the owner of the content item moves it, it is moved for all users. The owner’s permissions are “sticky” for that item. The owner will retain the same level of permission they had before the item was moved. If the owner moves a folder to one where the permissions are different than its current location, they will be prompted how to handle the permissions after the move:
Folder Move confirmation prompt
These changes only affect content that the current user owns:
Folders may only be deleted if they are empty.
If someone other than the owner deletes a folder, the folder is only deleted for that particular user. This is accomplished by adding a Content Access record that restricts that user’s access to the item.
If the owner deletes a folder, it must be first empty for all users of the application. The folder will then by marked deleted for all users.
In both scenarios, the content item remains in the Storage Management database but becomes invisible to certain or all users.
If someone other than the owner of a report deletes it, the item is deleted only for that user. Essentially, it becomes invisible for that user while still remaining available for others.
If the owner of the report deletes it, it is removed for all users.
In both scenarios, the content item remains in the Storage Management database but becomes invisible to certain or all users.
The Storage Management system can cache the Report Tree, the Report Definition XML and the Theme List. Exago recommends that all three be enabled to reduce the load on the Storage Management database.
Information about Database Permissions required for Exago to access the Storage Management database can be found in the Storage Management: Database Schema article.
Information about controlling access to content can be found in the Permissions section of this article.
Exago has developed several tools for the transition of content from legacy storage mechanisms to Storage Management. The transitioning process and tools are documented in the Storage Management: Transitioning from Legacy Storage Methods article and in Admin Support Lab — Storage Management Migration.
To migrate from one Storage Management database to another, use the ImportExportStorageMgmt command line utility, documented in the Moving Files Between Storage Management Databases article.
To get up and running quickly with Storage Management, review the Storage Management: Getting Started article.
In addition to Exago’s out-of-the-box implementation clients may write their own implementation of the Storage Management assembly.
Full details are outlined in the Storage Management: Customization article and in Admin Support Lab — Storage Management Customization.