Searching for Roles

The GET method without any role ID searches for and lists role definitions. It has options to search for roles by name or by user that belong to the role. If no search is specified, it returns all roles. The method has two forms:

• In the community edition of the server, or commercial editions without organizations, use the first form of the URL without an organization ID.
• In commercial editions with organizations, use the first URL to search or list all roles starting from the logged-in user’s organization (root for the system admin), and use the second URL to search or list all roles in a specified organization.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/roles?<arguments>

http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/roles?<arguments>

Argument

Type

Description
search

Optional
String

Specify a string or substring to match the role ID of any role. The search is not case sensitive.
user

Optional
String

Specify a username (ID) to list the roles to which this user belongs. Repeat this argument to list all roles of multiple users. In commercial editions with multiple organizations, specify users as <userID>%7C<orgID> (%7C is the | character).
hasAllUsers

Optional
Boolean

When set to true with multiple user arguments, this method returns only the roles to which all specified users belong (intersection of users’ roles). When false or not specified, all roles of all users are found (union of users’ roles).
include<br />SubOrgs

Optional
Boolean

Limits the scope of the search or list in commercial editions with multiple tenants. When set to false, the first URL form is limited to the logged-in user’s organization, and the second URL form is limited to the organization specified in the URL. When true or not specified, the scope includes the hierarchy of all child organizations.

Options

accept: application/xml (default)

accept: application/json

Return Value on Success

Typical Return Values on Failure

200 OK – The content is a set of descriptors for all roles in the result.

204 No Content – The search did not return any roles.

404 Not Found – When the organization ID does not match any organization. The content includes an error message.

The following example shows the first form URL on a commercial edition server with multiple organizations:

GET http://localhost:8080/jasperserver/rest_v2/roles

This method returns the set of all default system and root roles defined on a server with the sample data (no organization roles have been defined yet):

<roles>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_ADMINISTRATOR</name>
  </role>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_ANONYMOUS</name>
  </role>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_DEMO</name>
  </role>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_PORTLET</name>
  </role>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_SUPERMART_MANAGER</name>
  </role>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_SUPERUSER</name>
  </role>
  <role>
    <externallyDefined>false</externallyDefined>
    <name>ROLE_USER</name>
  </role>
</roles>

The externallyDefined property is true when the role is synchronized from a 3rd party such as an LDAP directory or single sign-on mechanism. For more information, see the JasperReports Server Authentication Cookbook.
Version: 
v5.5.2
v5.5.1
v5.5.0
Feedback
randomness