The rest_v2/users service provides methods that allow you to list, view, create, modify, and delete user accounts, including setting role membership. The service provides improved search functionality, such as organization-based searches in commercial editions licensed to use organizations. Every method has two URL forms, one with an organization ID and one without.
Only administrative users may access the users service. System admins (superuser) can define and modify users anywhere in the server, and organization admins (jasperadmin) can define and modify users within their own organization or any sub-organizations.
Because the user ID and organization ID are used in the URL, this service can operate only on users and organizations whose ID is less than 100 characters long and does not contain spaces or special symbols. As with resource IDs, the user ID is permanent and cannot be modified for the life of the user account.
This chapter includes the following sections:
| • | Searching for Users |
| • | Viewing a User |
| • | Creating a User |
| • | Modifying User Properties |
| • | Deleting a User |
Searching for Users
The GET method without any user ID searches for and lists user accounts. It has options to search for users by name or by role. If no search is specified, it returns all users. 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 list all users starting from the logged-in user’s organization (root for the system admin), and use the second URL to list all users in a specified organization. |
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/users?<arguments> http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/users?<arguments> | ||
| Argument | Type | Description | |
| search | Optional | Specify a string or substring to match the user ID or full name of any user. The search is not case sensitive. | |
| requiredRole | Optional | Specify a role name to list only users with this role. Repeat this argument to filter with multiple roles. In commercial editions with multiple organizations, specify roles as <roleName>%7C<orgID> (%7C is the | character). | |
| hasAll Required Roles | Optional | When set to false with multiple requiredRole arguments, users will match if they have any of the given roles (OR operation). When true or not specified, users must match all of the given roles (AND operation). | |
| include SubOrgs | Optional | Limits the scope of the search or list in commercial editions with multiple organizations. 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 users in the result. 204 No Content – The search did not return any users. | 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 of the URL on a community edition server:
GET http://localhost:8080/jasperserver/rest_v2/users?search=j
The response is a set of summary descriptors for all users containing the string "j":
The next example shows the second form of the URL on a commercial edition server with multiple organizations:
GET http://localhost:8080/jasperserver/rest_v2/organizations/Finance/users
On servers with multiple organizations, the summary user descriptors include the organization (tenant) ID:
Viewing a User
The GET method with a user ID (username) retrieves a single descriptor containing the full list of user properties and roles.
| • | 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 specify users of the root organization. |
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/users/userID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/users/userID | ||
| 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 user. | 404 Not Found – When the user ID or organization ID does not match any user or organization. The content includes an error message. | ||
The full user descriptor includes detailed information about the user account, including any roles. The following example shows the descriptor in XML format:
GET http://localhost:8080/jasperserver/rest_v2/users/joeuser
In servers with multiple organizations, the full descriptor includes the organization (tenant) ID. The following example shows the descriptor in JSON format:
GET http://localhost:8080/jasperserver/rest_v2/organizations/Finance/users/joeuser
Creating a User
To create a user account, put all required information in a user descriptor, and include it in a PUT request to the users service, with the intended user ID (username) 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 users in the root organization. |
To create a user, the user ID in the URL must be unique on the server or in the organization. If the user ID already exists, that user account will be modified, as described in Modifying User Properties.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/users/userID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/users/userID | ||
| Content-Type | Content | ||
| application/xml application/json | A user descriptor that includes at least the fullName and password for the user. The role ROLE_USER is automatically assigned to all users, so it does not need to be specified. Do not specify the following properties: username – Specified in the URL and cannot be modified in the descriptor. tenantID – Specified in the URL and cannot be modified in the descriptor. previousPasswordChangeTime – Computed automatically by the server. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 201 Created – The user was successfully created using the values in the descriptor. The response contains the full descriptor of the new user. | 404 Not Found – When the organization ID cannot be resolved. | ||
The descriptor sent in the request should contain all the properties you want to set on the new user, except for the username that is specified in the URL. To set roles on the user, specify them as a list of roles that includes the name and organization of each role. The following example shows the descriptor in JSON format:
| | The externallyDefined property is true when the user is synchronized from a 3rd party such as an LDAP directory or single sign-on mechanism. When creating a user through the REST API, this property should be set to false. For more information, see the JasperReports Server External Authentication Cookbook. |
Modifying User Properties
To modify the properties of a user account, put all desired information in a user descriptor, and include it in a PUT request to the users service, with the existing user ID (username) 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 modify users of the root organization. |
To modify a user, the user ID in the URL must already exist on the server or in the organization. If the user ID doesn’t exist, a user account will be created, as described in Creating a User.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/users/userID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/users/userID | ||
| Content-Type | Content | ||
| application/xml application/json | A user descriptor that includes the properties you want to change. Do not specify the following properties: username – Specified in the URL and cannot be modified in the descriptor. tenantID – Specified in the URL and cannot be modified in the descriptor. previousPasswordChangeTime – Computed automatically by the server. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The user properties were successfully updated. | 404 Not Found – When the organization ID cannot be resolved. | ||
To add a role to the user, specify the entire list of roles with the desired role added. To remove a role from a user, specify the entire list of roles with the desired role removed. The following example shows the descriptor in JSON format:
Deleting a User
To delete a user, send the DELETE method and specify the user ID 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 users of the root organization. |
When this method is successful, the user is permanently deleted.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/users/userID http://<host>:<port>/jasperserver[-pro]/rest_v2/organizations/orgID/users/userID | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – The user was successfully deleted. | 404 Not Found – When the ID of the organization cannot be resolved. | ||
Recommended Comments
There are no comments to display.