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 Session Id URL parameter and basic request headers. In the following examples, headers are omitted for clarity.
A role's base status is represented as a JSON object with the following properties:
Name | Type | Writeable | Description |
Id | string | required-create | The unique Id of this role |
IsActive | boolean | yes (true) | Whether this role is active |
{ "Id": "Client", "IsActive": false }
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 |
curl http://{webservice}/rest/roles?sid={sid} -X GET
Status: 200 OK [ { "Id": "Admin" }, { "Id": "Client" }, ... ]
POST /rest/roles
Creating a new role activates it by default.
curl http://{webservice}/rest/roles?sid={sid} -X POST ^ -d "{'Id':'User'}"
Status: 201 Created
Location: /{webservice}/rest/Roles/User { "Id": "User", "IsActive": true }
GET /rest/roles/{Id}
curl http://{webservice}/rest/roles/{Id}?sid={sid} -X GET
Status: 200 OK { "Id": "User", "IsActive": true }
PATCH /rest/roles/{Id}
Only supply the properties to be edited.
curl http://{webservice}/rest/roles/{Id}?sid={sid} -X PATCH ^ -d "{'IsActive':false}"
Status: 204 No Content
DELETE /rest/roles/{Id}
curl http://{webservice}/rest/roles/{Id}?sid={sid} -X DELETE
Status: 204 No Content
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 Crosstabs |
ShowExpressReports | boolean | Allow Creation/Editing of Express Reports |
ShowExpressReportsGrouping | boolean | Show Grouping |
ShowExpressReportsFormulas | boolean | Show Formula Button |
ShowExpressReportsStyling | boolean | Show Styling Toolbar |
ShowExpressReportsThemes | boolean | Show Themes |
ShowAdvancedReports | boolean | Allow Creation/Editing of Advanced Reports |
ShowScheduleReports | boolean | Show Report Scheduling Option |
ShowScheduleReportsManager | boolean | Show Schedule Reports Manager |
ShowScheduleReportsEmail | boolean | Show Email Report Options |
DecimalSymbol | string | Numeric Decimal Symbol |
{ "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, "ShowScheduleReports": true, "ShowScheduleReportsManager": true, "ShowScheduleReportsEmail": true, "DecimalSymbol": "." }
GET /rest/roles/{Id}/settings
Show the settings for the role specified by its Id.
curl http://{webservice}/rest/roles/{Id}/settings?sid={sid} -X GET
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", ... }
PATCH /rest/roles/{Id}/settings
Only supply the properties to be edited.
curl http://{webservice}/rest/roles/{Id}/settings?sid={sid} -X PATCH ^ -d "{'ShowAdvancedReports':false}"
Status: 204 No Content
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.
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 | Whether this role is allowed folder management |
CreateFolders | boolean | Whether this role is allowed to create folders |
Folders | array of Folder | The folders with properties specific to this role |
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 |
Propogate | boolean | Whether this folder's subfolders share its ReadOnly property |
{ "IncludeAll": false, "ReadOnly": false, "AllowManagement": true, "CreateFolders": false, "Folders": [ { "Name": "Examples\Client", "ReadOnly": true, "Propogate": true } ] }
GET /rest/roles/{Id}/folders
Show the folder permissions for the role specified by its Id.
curl http://{webservice}/rest/roles/{Id}/folders?sid={sid} -X GET
Status: 200 OK { "IncludeAll": false, "ReadOnly": false, "AllowManagement": true, "CreateFolders": false, "Folders": [ { "Name": "Examples", "ReadOnly": true, "Propogate": true } ] }
PATCH /rest/roles/{Id}/folders
Only supply the properties to be edited. Supplying a Folders property will overwrite the entire collection.
curl http://{webservice}/rest/roles/{Id}/folders?sid={sid} -X PATCH ^ -d "{'ReadOnly':true}"
Status: 204 No Content
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 |
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 |
{ "IncludeAll": true, "Entities": [ { "Id": "EMP" }, { "Id": "ETE" } ] }
GET /rest/roles/{Id}/entities
Show the data object permissions for the role specified by its Id.
curl http://{webservice}/rest/roles/{Id}/entities?sid={sid} -X GET
Status: 200 OK { "IncludeAll": false, "Entities": [ { "Id": "EMP" } ] }
PATCH /rest/roles/{Id}/entities
Only supply the properties to be edited. Supplying an Entities property will overwrite the entire collection.
curl http://{webservice}/rest/roles/{Id}/entities?sid={sid} -X PATCH ^ -d "{'IncludeAll':false}"
Status: 204 No Content
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 |
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 |
{ "DataObjectRows": [ { "Id": "EMP", "Filter": "Admin" }, { "Id": "ETE", "Filter": "Admin" } ] }
GET /rest/roles/{Id}/dataobjectrows
Show the row filters for the role specified by its Id.
curl http://{webservice}/rest/roles/{Id}/dataobjectrows?sid={sid} -X GET
Status: 200 OK { "DataObjectRows": [ { "Id": "EMP", "Filter": "Admin" },
... ] }
PATCH /rest/roles/{Id}/dataobjectrows
This will overwrite the entire filter collection.
curl http://{webservice}/rest/roles/{Id}/dataobjectrows?sid={sid} -X PATCH ^ -d "{'DataObjectRows':[{'Id':'EMP','Filter':'Client'}]}"
Status: 204 No Content