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 |
| • | Viewing a Role |
| • | Creating a Role |
| • | Modifying a Role |
| • | Setting Role Membership |
| • | Deleting a Role |
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 | Specify a string or substring to match the role ID (name) of any role. The search is not case sensitive. | |
| user | Optional | 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 | When set to true with multiple user arguments, this method returns only the roles to which all specified users belong (intersection of all users' roles). When false or not specified, all roles of all specified users are found (union of all users' roles). | |
| include | Optional | 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):
| | 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 External Authentication Cookbook. |
Viewing a Role
The GET method with a role ID retrieves a single role descriptor containing the role properties.
| • | In the community edition of the server, or commercial editions without organizations, use the first form of the URL. |
| • | In commercial editions with organizations, use the second URL to specify the role’s organization. When specifying the organization, use its unique ID, not its path. When logged in as the system admin (superuser), use the first URL to specify roles of the root organization. |
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/roles/roleID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/roles/roleID | ||
| Options | |||
| accept: application/xml (default) accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is the descriptor for the given role. | 404 Not Found – When the role ID or organization ID does not match any role or organization. The content includes an error message. | ||
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/roles/ROLE_MANAGER
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.
| • | In the community edition of the server, or commercial editions without organizations, use the first form of the URL. |
| • | In commercial editions with organizations, use the second URL to specify the user’s organization. When specifying the organization, use its unique ID, not its path. When logged in as the system admin (superuser), use the first URL to create roles in the root organization. |
Roles do not have any properties to specify other than the role ID, but the request must include a descriptor that can be empty.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/roles/roleID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/roles/roleID | ||
| Content-Type | Content | ||
| application/xml application/json | An empty role descriptor, either <role></role> or {}. Do not specify the following properties: name – Specified in the URL and should not be modified in the descriptor. tenantID – Specified in the URL and cannot be modified in the descriptor. externallyDefined – Computed automatically by the server. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 201 Created – The role was successfully created. The response contains the full descriptor of the new role. | 404 Not Found – When the organization ID cannot be resolved. | ||
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.
| • | In the community edition of the server, or commercial editions without organizations, use the first form of the URL. |
| • | In commercial editions with organizations, use the second URL to specify the user’s organization. When specifying the organization, use its unique ID, not its path. When logged in as the system admin (superuser), use the first URL to modify roles in the root organization. |
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.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/roles/roleID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/roles/roleID | ||
| Content-Type | Content | ||
| application/xml application/json | A role descriptor containing a single property: name – The new name for the role. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The role was successfully updated. The response contains the full descriptor of the updated role. | 404 Not Found – When the organization ID cannot be resolved. | ||
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.
| • | In the community edition of the server, or commercial editions without organizations, use the first form of the URL. |
| • | In commercial editions with organizations, use the second URL to specify the user’s organization. When specifying the organization, use its unique ID, not its path. When logged in as the system admin (superuser), use the first URL to delete roles of the root organization. |
When this method is successful, the role is permanently deleted.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/roles/roleID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/roles/roleID | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – The role was successfully deleted. | 404 Not Found – When the ID of the organization cannot be resolved. | ||
Recommended Comments
There are no comments to display.