User Roles API

• Overview
• General workflow
• Submit Report Endpoint (asynchronous)
• View Report Endpoint (synchronous)
• Sample reference reports

Overview

General workflow

1. Report Filters:
   • ReportName → Name of the report.
   • Users → Specify users.
   • Departments → Filter by departments.
   • Scopes → Choose role scope:
     • 160 = Application-Level
     • 161 = Department-Level
2. Scope Behavior:
   • Scopes = 160 (Application-Level Roles)
     • Filters roles assigned at the application level.
     • Returns roles that apply across the entire system, not tied to departments.
     • Output: Users with application-wide role assignments.
   • Scopes = 161 (Department-Level Roles)
     • Filters roles assigned at the department level.
     • Combines with the Departments filter if supplied.
     • Output: Users with department-specific role assignments.
   • Scopes = (Both Together)
     • Returns both application-level and department-level roles in one report.
     • Useful for a complete view of all role assignments.
   Notes:
   • All filters use AND logic (they combine together).
   • Report shows current assignments only, not historical snapshots.

Submit Report Endpoint (asynchronous)

• This API submits the report generation request which executes asynchronously. The result of this API contains the identifier for the report, status, and location for retrieving the report data.
• The report identifier and locations in the result can be used to track the report generation operation.

1. Call the UserRolesAsync API to submit a report generation request.
   This asynchronous API supports GET and POST query methods. Use any of the following as needed:
   • GET https://<Reporting endpoint base URL>/OData/UserRolesAsync?ReportName=<Name of the report>&Users=[list of comma-separated values]&Departments=[list of comma-separated values]&Scopes=[list of comma-separated values]
   • POST https://<Reporting endpoint base URL>/OData/UserRolesAsync
   Sample Input
   • GET https://<Reporting endpoint Base URL>/odata/ UserRolesAsync?ReportName=<Name of the report>Users=[1247,3821]
   • POST https://<Reporting endpoint base URL>/OData/UserRolesAsync
   Parameter/Filters
   The following parameters/filters can be used with the UserRolesAsync API when invoked using the GET and POST methods. The system uses the AND operator between the filters to return the result based on the specified filters.

   Parameter	Required	Description
   ReportName	Mandatory	Specify the name of the report you want to generate.
   		Limitations:
   		- The report name can be up to a maximum of 256 characters long.
   		- Special characters are not allowed; only alphanumeric values are permitted.
   Departments	Optional	Specifies IDs of the departments to which users and their roles belongs to.
   		Limitations:
   		This API can pass a maximum of 100 Departments IDs as input.
   		Data Type: JSON array of integers 'id' (identifier fields) that is Departments.
   		Note: To get the Department IDs, See Departments API. Refer to the departmentId field only.
   Scopes	Optional	Specifies the scope of the users roles. Possible values are: 160 for application-level roles and 161 for department-level roles.
   		Data Type: JSON array of integers 'id' (identifier fields) that is Scopes.
   Users	Optional	Specifies IDs of the users.
   		Limitations:
   		This API can pass a maximum of 100 User IDs as input.
   		Data Type: JSON array of integers 'id' (identifier fields) that is Users.
   		Note: To get the User IDs, See Users API. Refer to the userId field only.

   Scenario 1: When Users are mentioned, but Departments and Scopes are not specified
   Sample input:
   POST https://<Reporting endpoint base URL>/OData/UserRolesAsync
{
"ReportName":"TestUserRolesReport",
"Departments":[],
"Scopes":"[],
"Users":[3821]
}
   Sample response:
   
   The following table explains the parameters showcased in the response to a User Roles Async API request.

   Name	Description
   reportId	Displays report ID. It is generated upon successful execution of API.
   reportName	Displays report name. It is generated upon successful execution of API.
   reportType	Displays the report type as User Roles.
   reportDate	Displays the date of report generation after successful execution of API.
   reportStatus	Displays report status. For more information on statuses, see Report Status API .
   info	Displays a message if the report request has queued successfully or not.
   newReportInstanceQueued	Specifies whether a new report generation request has been submitted or not. The Rate Limiting feature restricts submission of multiple requests with identical input parameters if attempted within one minute.
   	It returns the following values:
   	True: The value is shown as True, if the new report request has been queued successfully.
   	False: The value is shown as False, if the input parameters of the current request are identical to the parameters of the already submitted request within one minute, a new report will not be queued. As a result, the details of the existing report request are returned.
   reportStatusLocation	Displays a URL with report ID.
   	To view the status of this report, use the same URL.
   reportDataLocation	Displays a URL for the location of report data.
   	To access the report data, use the same URL.

   Scenario 2: When Departments are mentioned, but Users and Scopes are not specified
   Sample input:
   POST https://<Reporting endpoint base URL>/OData/UserRolesAsync
{
"ReportName":"TestUserRolesReport",
"Departments":[23],
"Scopes":"[],
"Users":[]
}
   Sample response:
   
   Scenario 3: When Departments, Users, and Scopes are mentioned
   Sample input:
   POST https://<Reporting endpoint base URL>/OData/UserRolesAsync
{
"ReportName":"TestUserRolesReport",
"Departments":[23],
"Scopes":"[160,161],
"Users":[55,67]
}
   Sample response:
   
   Scenario 4: When Departments, Users and Scopes are mentioned, but ReportName is not specified
   Sample input:
   POST https://\<Reporting endpoint base URL\>/OData/UserRolesAsync
{
"ReportName":"",
"Departments":[23],
"Scopes":"[160],
"Users":[3821]
}
   Sample response:
   
2. Call the ReportStatus API to get the status of the UserRolesAsync API report. See Report Status API.
3. Once the report is ready, call the UserRoles synchronous API to get the report data from the asynchronous API.

View Report Endpoint (synchronous)

• GET https://<Reporting endpoint Base URL>/odata/UserRoles?reportid=<ID of the UserRolesAsync API report>
• GET https://<Reporting endpoint Base URL>/odata/UserRoles?reportid=d53960f0-dbd0-4aa9-b7cf-23bd6ab7875f

Sample reference reports