Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

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

    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.

    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:

    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:

    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.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...