The users Service

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
String

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

requiredRole

Optional
String

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
Boolean

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
Boolean

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":

<users>
  <user>
    <externallyDefined>false</externallyDefined>
    <fullName>jasperadmin User</fullName>
    <username>jasperadmin</username>
  </user>
  <user>
    <externallyDefined>false</externallyDefined>
    <fullName>Joe User</fullName>
    <username>joeuser</username>
  </user>
</users>

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:

<users>
  <user>
    <externallyDefined>false</externallyDefined>
    <fullName>jasperadmin</fullName>
    <tenantId>Finance</tenantId>
    <username>jasperadmin</username>
  </user>
  <user>
    <externallyDefined>false</externallyDefined>
    <fullName>jasperadmin</fullName>
    <tenantId>Audit</tenantId>
    <username>jasperadmin</username>
  </user>
  <user>
    <externallyDefined>false</externallyDefined>
    <fullName>joeuser</fullName>
    <tenantId>Finance</tenantId>
    <username>joeuser</username>
  </user>
  <user>
    <externallyDefined>false</externallyDefined>
    <fullName>joeuser</fullName>
    <tenantId>Audit</tenantId>
    <username>joeuser</username>
  </user>
</users>

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

<user>
  <enabled>true</enabled>
  <externallyDefined>false</externallyDefined>
  <fullName>Joe User</fullName>
  <previousPasswordChangeTime>2013-04-19T18:53:07.602-07:00
  </previousPasswordChangeTime>
  <roles>
    <role>
      <externallyDefined>false</externallyDefined>
      <name>ROLE_USER</name>
    </role>
  </roles>
  <username>joeuser</username>
</user>

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/j...

{
  "fullName":"joeuser",
  "emailAddress":"",
  "externallyDefined":false,
  "enabled":true,
  "previousPasswordChangeTime":1366429181984,
  "tenantId":"Finance",
  "username":"joeuser",
  "roles":[
    {"name":"ROLE_USER","externallyDefined":false}]
}

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.

externallyDefined – Computed automatically by the server.

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:

{
  "fullName":"Joe User",
  "emailAddress":"juser@example.com",
  "enabled":false,
  "password":"mySecretPassword",
  "roles":[
    {"name":"ROLE_MANAGER", "tenantId":"organization_1"}]
}

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.

externallyDefined – Computed automatically by the server.

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:

{
  "enabled":true,
  "password":"newPassword",
  "roles":[
    {"name":"ROLE_USER"},
    {"name":"ROLE_STOREMANAGER", "tenantId":"organization_1"}]
}

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.

Version: 
Feedback
randomness