Exago Logo
Search
Generic filters
Exact matches only

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:

NameTypeWritableDescription
Idstringrequired-createThe unique Id of this role
IsActivebooleanyes (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.

NameTypeDescription
IdstringThe 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.

NameTypeDescription
ReportPathstringReport Path
LanguageFilestringLanguage File
ServerTimeZoneOffsetintegerServer Time Zone Offset
ReadFilterValuesbooleanRead Database for Filter Values
DbTimeoutintegerDatabase Timeout
ScheduleManagerViewLevelenumScheduler Manager User View Level
DateFormatstringDate Format
TimeFormatstringTime Format
DateTimeFormatstringDateTime Format
SeparatorSymbolstringNumeric Separator Symbol
CurrencySymbolstringNumeric Currency Symbol
ShowGridbooleanShow Grid Lines in Report Viewer
ShowCrossTabReportsbooleanAllow Creation/Editing of CrossTab Reports
ShowExpressReportsbooleanAllow Creation/Editing of Express Reports
ShowExpressReportsGroupingbooleanShow Grouping in the Express Report Designer
ShowExpressReportsFormulasbooleanShow Formula Button in the Express Report Designer
AllowReportCustomSQLObjects v2018.1+booleanAllow Creation of Custom SQL Objects in Advanced Reports
ShowExpressReportsStylingbooleanShow Styling Toolbar in the Express Report Designer
ShowExpressReportsThemesbooleanShow Themes in the Express Report Designer
ShowScheduleReportsbooleanShow report scheduling options
ShowScheduleReportsManagerbooleanShow Schedule Manager in the main menu
ShowScheduleReportsEmailbooleanShow Email Report Options
DecimalSymbolstringNumeric Decimal Symbol

The following settings have been added to versions v2018.1.27+v2018.2.16+2019.1.2+ of Exago:

NameTypeDescription
ShowAdvancedReportsbooleanAllow Creation/Editing of Advanced Reports
ShowDashboardReportsbooleanAllow Creation/Editing of Dashboard Reports
ShowDashboardNewVisualizationButtonbooleanAllow Creation/Editing of Dashboard Visualizations
ShowExpressViewsbooleanAllow Creation/Editing of ExpressViews
AllowExpressViewLiveEditbooleanAllow Editing ExpressView with Live Data
ShowChainedReportsbooleanAllow Creation/Editing of Chained Reports
CacheVisibilityLevelwrCacheVisibilityCache 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.

NameTypeDescription
IncludeAllbooleanIf 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.
ReadOnlybooleanIf True, all folders are read-only except the folders marked ReadOnly = ‘true’. If false, only the folders marked ReadOnly = ‘true’ are read-only.
AllowManagementbooleanIf 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.
CreateFoldersbooleanIf 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.
Foldersarray of FolderThe 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:

NameTypeDescription
NamestringFull path from the root folder to this folder
ReadOnlybooleanWhether this folder is ReadOnly
PropagatebooleanWhether 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.

NameTypeDescription
IncludeAllbooleanIf 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.
Entitiesarray of Data ObjectThe 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:

NameTypeDescription
IdstringThe 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:

NameTypeDescription
DataObjectRowsarray of Row FilterThe 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:

NameTypeDescription
IdstringThe Id of the data object to filter
FilterstringThe 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. @[email protected]) or custom SQL including subqueries (e.g. IN (SELECT EmployeeID FROM Employees WHERE EmployeeID <4)). The Filter String must contain the actual name of objects in the Data Source (e.g. tables, views, columns, etc…) rather than their Exago aliases.

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
Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Table of Contents