The roles Service

The rest_v2/roles service provides methods that allow you to list, view, create, modify, and delete roles. The service provides improved search functionality, including user-based role searches. Every method has two URL forms, one with an organization ID and one without.

Only administrative users may access the roles service. System admins (superuser) can define and set roles anywhere in the server, and organization admins (jasperadmin) can define and set roles within their own organization or any sub-organizations.

Because the role ID and organization ID are used in the URL, this service can operate only on roles and organizations whose ID is less than 100 characters long and does not contain spaces or special symbols. Unlike resource IDs, the role ID is the role name and can be modified.

This chapter includes the following sections:

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:

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>

Viewing a Role

The GET method with a role ID retrieves a single role descriptor containing the role properties.

After adding roles to an organization, the following example shows the simple role descriptor for an organization role in JSON format:

GET http://localhost:8080/jasperserver-pro/rest_v2/organizations/Finance/rol...

{
  "name":"ROLE_MANAGER",
  "externallyDefined":false,
  "tenantId":"Finance"
}

Creating a Role

To create a role, send the PUT request to the roles service with the intended role ID (name) specified in the URL.

Roles do not have any properties to specify other than the role ID, but the request must include a descriptor that can be empty.

Modifying a Role

To change the name of a role, send a PUT request to the roles service and specify the new name in the role descriptor.

The only property of a role that you can modify is the role's name. After the update, all members of the role are members of the new role name, and all permissions associated with the old role name are updated to the new role name.

Setting Role Membership

To assign role membership to a user, set the roles property on the user account with the PUT method of the users service. For details, see Modifying User Properties.

Deleting a Role

To delete a role, send the DELETE method and specify the role ID (name) in the URL.

When this method is successful, the role is permanently deleted.