Jump to content
JasperReports Library 7.0 is now available ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    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
    String

    Specify a string or substring to match the role ID (name) of any role. The search is not case sensitive.

    user

    Optional
    String

    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
    Boolean

    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
    SubOrgs

    Optional
    Boolean

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

    note-icon-ns_28x28.png.6a7fa6b8058f8c1c087c53efaef06f78.png

    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.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...