REST – Role Security
Roles are collections of security settings for users of the application. They are used to distinguish classes of users by access rights. Setting an active role will cause it to take effect for the application session, once the AppUrl is launched in the browser. Once in an application session, the active role cannot be changed. Only one role can be active at a time.
Roles do not affect your access to the API.
Note
All requests require a Session ID URL parameter and basic request headers. In the following document, headers are omitted in the interest of brevity.
Role JSON
A role’s base status is represented as a JSON object with the following properties:
Name | Type | Writable | Description |
---|---|---|---|
Id | string | required-create | The unique Id of this role |
IsActive | boolean | yes (true) | Whether this role is active |
Example
{ "Id": "Client", "IsActive": false }
List Roles
GET /rest/Roles
List all the roles in the current configuration. Output is an array of objects, each representing an individual role.
Name | Type | Description |
---|---|---|
Id | string | The unique Id of this role |
Using curl
curl http://{webservice}/rest/Roles?sid={sid} -X GET
Example response
Status: 200 OK [ { "Id": "Admin" }, { "Id": "Client" }, ... ]
Create a Role
POST /rest/Roles
Creating a new role activates it by default.
Using curl
curl http://{webservice}/rest/Roles?sid={sid} -X POST ^ -d "{'Id':'User'}"
Example response
Status: 201 Created Location: /{webservice}/rest/Roles/User { "Id": "User", "IsActive": true }
Show Role Status
GET /rest/Roles/{Id}
Using curl
curl http://{webservice}/rest/Roles/{Id}?sid={sid} -X GET
Example response
Status: 200 OK { "Id": "User", "IsActive": true }
Activate or Deactivate a Role
PATCH /rest/Roles/{Id}
Only supply the properties to be edited.
Using curl
curl http://{webservice}/rest/Roles/{Id}?sid={sid} -X PATCH ^ -d "{'IsActive':false}"
Example response
Status: 204 No Content
Delete a Role
DELETE /rest/Roles/{Id}
Using curl
curl http://{webservice}/rest/Roles/{Id}?sid={sid} -X DELETE
Example response
Status: 204 No Content
Role Settings JSON
Each role has a group of settings that may be used to override the base config. Each key corresponds with a setting in the Admin Console, which is noted in the Description field. If a setting is blank or null, then the value from the base config is not overridden for this role. The settings are represented as a JSON object with the following properties:
Note
All properties are read/write. No properties are required. Default values are inherited from the base config.
Name | Type | Description |
---|---|---|
ReportPath | string | Report Path |
LanguageFile | string | Language File |
ServerTimeZoneOffset | integer | Server Time Zone Offset |
ReadFilterValues | boolean | Read Database for Filter Values |
DbTimeout | integer | Database Timeout |
ScheduleManagerViewLevel | enum | Scheduler Manager User View Level |
DateFormat | string | Date Format |
TimeFormat | string | Time Format |
DateTimeFormat | string | DateTime Format |
SeparatorSymbol | string | Numeric Separator Symbol |
CurrencySymbol | string | Numeric Currency Symbol |
ShowGrid | boolean | Show Grid Lines in Report Viewer |
ShowCrossTabReports | boolean | Allow Creation/Editing of CrossTab Reports |
ShowExpressReports | boolean | Allow Creation/Editing of Express Reports |
ShowExpressReportsGrouping | boolean | Show Grouping in the Express Report Designer |
ShowExpressReportsFormulas | boolean | Show Formula Button in the Express Report Designer |
AllowReportCustomSQLObjects v2018.1+ | boolean | Allow Creation of Custom SQL Objects in Advanced Reports |
ShowExpressReportsStyling | boolean | Show Styling Toolbar in the Express Report Designer |
ShowExpressReportsThemes | boolean | Show Themes in the Express Report Designer |
ShowScheduleReports | boolean | Show report scheduling options |
ShowScheduleReportsManager | boolean | Show Schedule Manager in the main menu |
ShowScheduleReportsEmail | boolean | Show Email Report Options |
DecimalSymbol | string | Numeric Decimal Symbol |
The following settings have been added to versions v2018.1.27+, v2018.2.16+, 2019.1.2+ of Exago:
Name | Type | Description |
---|---|---|
ShowAdvancedReports | boolean | Allow Creation/Editing of Advanced Reports |
ShowDashboardReports | boolean | Allow Creation/Editing of Dashboard Reports |
ShowDashboardNewVisualizationButton | boolean | Allow Creation/Editing of Dashboard Visualizations |
ShowExpressViews | boolean | Allow Creation/Editing of ExpressViews |
AllowExpressViewLiveEdit | boolean | Allow Editing ExpressView with Live Data |
ShowChainedReports | boolean | Allow Creation/Editing of Chained Reports |
CacheVisibilityLevel | wrCacheVisibility | Cache Visibility Level |
Example
{ "ReportPath": "C:\\Exago\\Reports", "LanguageFile": null, "ServerTimeZoneOffset": 0, "ReadFilterValues": true, "DbTimeout": 0, "ScheduleManagerViewLevel": "All", "DateFormat": "MM/dd/yyyy", "TimeFormat": "hh:mm:ss a", "DateTimeFormat": "MM/dd/yyyy hh:mm:ss a", "SeparatorSymbol": ",", "CurrencySymbol": "$", "ShowGrid": true, "ShowCrossTabReports": true, "ShowExpressReports": true, "ShowExpressReportsGrouping": true, "ShowExpressReportsFormulas": true, "ShowExpressReportsStyling": true, "ShowExpressReportsThemes": true, "ShowAdvancedReports": true, "ShowDashboardReports": true, "ShowDashboardNewVisualizationButton": true, "ShowExpressViews": true, "AllowExpressViewLiveEdit": true, "ShowChainedReports": true, "CacheVisibilityLevel": "Global", "ShowScheduleReports": true, "ShowScheduleReportsManager": true, "ShowScheduleReportsEmail": true, "DecimalSymbol": "." }
Show Role Settings
GET /rest/Roles/{Id}/Settings
Show the settings for the role specified by its Id.
Using curl
curl http://{webservice}/rest/Roles/{Id}/Settings?sid={sid} -X GET
Example response
Status: 200 OK { "ReportPath": "C:\\Exago\\Reports", "LanguageFile": null, "ServerTimeZoneOffset": 0, "ReadFilterValues": true, "DbTimeout": 0, "ScheduleManagerViewLevel": "All", "DateFormat": "MM/dd/yyyy", "TimeFormat": "hh:mm:ss a", ... }
Edit Role Settings
PATCH /rest/Roles/{Id}/Settings
Only supply the properties to be edited.
Using curl
curl http://{webservice}/rest/Roles/{Id}/Settings?sid={sid} -X PATCH ^ -d "{'ShowAdvancedReports':false}"
Example response
Status: 204 No Content
Folder Permissions JSON
Each role has a set of folder permissions which allow or disallow access to folders for the current session. The permissions are represented as a JSON object with the following properties:
Note
All properties are read/write. No properties are required.
Caution
The Report Tree should contain no more than 1,000 items in it for best user experience.
Name | Type | Description |
---|---|---|
IncludeAll | boolean | If True, all folders are visible to this role except the ones specified in Folders. If False, only the folders specified in Folders are visible to this role. |
ReadOnly | boolean | If True, all folders are read-only except the folders marked ReadOnly = ‘true’. If false, only the folders marked ReadOnly = ‘true’ are read-only. |
AllowManagement | boolean | If True, users will be able create, rename and delete folders via the user interface. If False, users cannot take action on folders and the Add Folder buttons are hidden from the user interface. |
CreateFolders | boolean | If True, when adding Folders to the Role via the API, Exago will check if the folder exists and add it if not. If False no check will be performed. Once the session is launched, this property no longer applies. |
Folders | array of Folder | The folders with properties specific to this role |
Folder JSON
Each folder in the Folders property is represented as a JSON object with the following properties:
Name | Type | Description |
---|---|---|
Name | string | Full path from the root folder to this folder |
ReadOnly | boolean | Whether this folder is ReadOnly |
Propagate | boolean | Whether this folder’s subfolders share its ReadOnly property |
Example
{ "IncludeAll": false, "ReadOnly": false, "AllowManagement": true, "CreateFolders": false, "Folders": [ { "Name": "ExamplesClient", "ReadOnly": true, "Propagate": true } ] }
List Folder Permissions
GET /rest/Roles/{Id}/Folders
Show the folder permissions for the role specified by its Id.
Using curl
curl http://{webservice}/rest/Roles/{Id}/Folders?sid={sid} -X GET
Example response
Status: 200 OK { "IncludeAll": false, "ReadOnly": false, "AllowManagement": true, "CreateFolders": false, "Folders": [ { "Name": "Examples", "ReadOnly": true, "Propagate": true } ] }
Edit Folder Permissions
PATCH /rest/Roles/{Id}/Folders
Only supply the properties to be edited. Supplying a Folders property will overwrite the entire collection.
Using curl
curl http://{webservice}/rest/roles/{Id}/folders?sid={sid} -X PATCH ^ -d "{'ReadOnly':true}"
Example response
Status: 204 No Content
Data Object Permissions JSON
Each role has a set of data object permissions which allow or disallow access to data objects for the current session. The permissions are represented as a JSON object with the following properties:
Note
All properties are read/write. No properties are required.
Name | Type | Description |
---|---|---|
IncludeAll | boolean | If true, all data objects are available to this role except the ones specified in Entities. If false, only the data objects specified in Entities are visible to this role. |
Entities | array of Data Object | The data objects with properties specific to this role |
Data Object JSON
Each Data Object in the Entities property is represented as a JSON object with the following properties:
Name | Type | Description |
---|---|---|
Id | string | The unique Id of this data object |
Example
{ "IncludeAll": true, "Entities": [ { "Id": "EMP" }, { "Id": "ETE" } ] }
List Data Object Permissions
GET /rest/Roles/{Id}/Entities
Show the data object permissions for the role specified by its Id.
Using curl
curl http://{webservice}/rest/Roles/{Id}/Entities?sid={sid} -X GET
Example response
Status: 200 OK { "IncludeAll": false, "Entities": [ { "Id": "EMP" } ] }
Edit Data Object Permissions
PATCH /rest/Roles/{Id}/Entities
Only supply the properties to be edited. Supplying an Entities property will overwrite the entire collection.
Using curl
curl http://{webservice}/rest/roles/{Id}/entities?sid={sid} -X PATCH ^ -d "{'IncludeAll':false}"
Example response
Status: 204 No Content
Row Filters JSON
You can add security filters to data objects so that users can only view specific rows in the data object. The collection of row filters for this role is represented as a JSON object with the following properties:
Name | Type | Description |
---|---|---|
DataObjectRows | array of Row Filter | The row filters for this role |
Row Filter JSON
Each row filter in the DataObjectRows property is represented as a JSON object with the following properties:
Name | Type | Description |
---|---|---|
Id | string | The Id of the data object to filter |
Filter | string | The filter string.
The filter string should be valid, standard SQL to be added to the ‘WHERE’ clause sent to the Data Source. This filter string can include Exago system parameters (e.g. @userId@) or custom SQL including subqueries (e.g. |
Example
{ "DataObjectRows": [ { "Id": "EMP", "Filter": "EmployeeID = 1" }, { "Id": "ETE", "Filter": "EmployeeID = 2" } ] }
List Row Filters
GET /rest/Roles/{Id}/DataObjectRows
Show the row filters for the role specified by its Id.
Using curl
curl http://{webservice}/rest/Roles/{Id}/DataObjectRows?sid={sid} -X GET
Example response
Status: 200 OK { "DataObjectRows": [ { "Id": "EMP", "Filter": "EmployeeID = 3" }, ... ] }
Edit Row Filters
PATCH /rest/Roles/{Id}/DataObjectRows
This will overwrite the entire filter collection.
Using curl
curl http://{webservice}/rest/Roles/{Id}/DataObjectRows?sid={sid} -X PATCH ^ -d "{'DataObjectRows':[{'Id':'EMP','Filter':'Client'}]}"
Example response
Status: 204 No Content