# 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 Session Id URL parameter and basic request headers. In the following examples, headers are omitted for clarity.

# Role JSON

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

### 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 Crosstabs
ShowExpressReports | boolean | Allow Creation/Editing of Express Reports
ShowExpressReportsGrouping | boolean | Show Grouping
ShowExpressReportsFormulas | boolean | Show Formula Button
(v2018.1+) AllowReportCustomSQLObjects | boolean | Allow Creation of Custom SQL Objects in Advanced Reports
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

### 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,
      "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.

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

## 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
Propogate | boolean | Whether this folder's subfolders share its ReadOnly property

### Example

    {
      "IncludeAll":      false,
      "ReadOnly":        false,
      "AllowManagement": true,
      "CreateFolders":   false,
      "Folders": [
        {
          "Name":      "Examples\Client",
          "ReadOnly":  true,
          "Propogate": 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,
          "Propogate": 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

### Example

    {
      "DataObjectRows": [
        {
          "Id":     "EMP",
          "Filter": "Admin"
        },
        {
          "Id":     "ETE",
          "Filter": "Admin"
        }
      ]
    }

# 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": "Admin"
        },
        ...
      ]
    }

# 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