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

    pro-only-icon_28x28.png.9239ffafe39a7ce97180d532fa12c1f0.png

    This section describes functionality that can be restricted by the software license for JasperReports Server. If you don’t see some of the options described in this section, your license may prohibit you from using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

    The rest_v2/organizations service provides methods that allow you to list, view, create, modify, and delete organizations (also known as tenants). Search functionality allows you to find organizations by name and retrieve hierarchies of organizations.

    Because the organization ID is used in the URL, this service can operate only on organizations whose ID is less than 100 characters long and does not contain spaces or special symbols. As with resource IDs, the organization ID is permanent and cannot be modified for the life of the organization.

    Only administrative users may access the organizations service. System admins (superuser) can operate on top-level organizations, and organization admins (jasperadmin) can operate on their own organization or any sub-organizations.

    This chapter includes the following sections:

    Searching for Organizations
    Viewing an Organization
    Creating an Organization
    Modifying Organization Properties
    Setting the Theme of an Organization
    Deleting an Organization

    Searching for Organizations

    The GET method without any organization ID searches for organizations by ID, alias, or display name. If no search is specified, it returns a list of all organizations. Searches and listings start from but do not include the logged-in user’s organization or the specified base (rootTenantId).

    Method

    URL

    GET

    http://<host>:<port>/jasperserver-pro/rest_v2/organizations?<arguments>

    Argument

    Type

    Description

    q

    Optional
    String

    Specify a string or substring to match the organization ID, alias, or name of any organization. The search is not case sensitive. Only the matching organizations are returned in the results, regardless of their hierarchy.

    include
    Parents

    Optional
    Boolean

    When used with a search, the result will include the parent hierarchy of each matching organization. When not specified, this argument is false by default.

    rootTenantId

    Optional
    String

    Specifies an organization ID as a base for searching and listing child organizations. The base is not included in the results. Regardless of this base, the tenantFolderURI values in the result are always relative to the logged-in user’s organization. When not specified, the default base is the logged-in user’s organization.

    sortBy

    Optional
    String

    Specifies a sort order for results. When not specified, lists of organizations are in the order that they were created. The possible values are:

    name – Sort results alphabetically by organization name.

    alias – Sort results alphabetically by organization alias.

    id – Sort results alphabetically by organization ID.

    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 organizations in the result.

    204 No Content – The search did not return any organizations.

     

    The following example shows a search for an organization and its parent hierarchy:

    GET http://localhost:8080/jasperserver-pro/rest_v2/organizations?q=acc&includeParents=true

    This request has the following response, as viewed by superuser at the root of the organization hierarchy:

    Viewing an Organization

    The GET method with an organization ID retrieves a single descriptor containing the list of properties for the organization. When you specify an organization, use its unique ID, not its path.

    Method

    URL

    GET

    http://<host>:<port>/jasperserver-pro/rest_v2/organizations/organizationID

    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 organization.

    404 Not Found – When the ID does not match any organization. The content includes an error message.

    403 Forbidden – When the logged-in user does not have permission to view the given organization

    The organization descriptor is identical to the one returned when searching or listing organization, but only a single descriptor is ever returned. The following example shows the descriptor in JSON format:

    Creating an Organization

    To create an organization, put all information in an organization descriptor, and include it in a POST request to the organizations service, with no ID specified in the URL. The organization is created in the organization specified by the parentId value of the descriptor.

    Method

    URL

    POST

    http://<host>:<port>/jasperserver-pro/rest_v2/organizations?<argument>

    Argument

    Type

    Description

    create
    Default
    Users

    Optional
    Boolean

    Set this argument to false to suppress the creation of default users (joeuser, jasperadmin) in the new organization. When not specified, the default behavior is true and organizations are created with the standard default users.

    Content-Type

    Content

    application/xml

    application/json

    A partial or complete organization descriptor that includes the desired properties for the organization.

    Return Value on Success

    Typical Return Values on Failure

    201 Created – The organization was successfully created using the values in the descriptor or default values if missing.

    404 Not Found – When the ID of the parent organization cannot be resolved.

    400 Bad Request – When the ID or alias of the new organization is not unique on the server, or when the ID in the description contains illegal symbols. The following symbols are not allowed:

    id and alias: ~!+-#$%^|

    tenantName: |&*?<>/

    The descriptor sent in the request should contain all the properties you want to set on the new organization. Specify the parentId value to set the parent of the organization, not the tenantUri or tenantFolderUri properties. The following example shows the descriptor in JSON format:

    However, all properties have defaults or can be determined based on the alias value. The minimal descriptor necessary to create an organization is simply the alias property. In this case, the organization is created as a child of the logged-in user’s home organization. For example, if superuser posts the following descriptor, the server creates an organization with the name, ID, and alias of HR as a child of the root organization:

    Modifying Organization Properties

    To modify the properties of an organization, use the PUT method and specify the organization ID in the URL. The request must include an organization descriptor with the values you want to change. You cannot change the ID of an organization, only its name (used for display) and its alias (used for logging in).

    Method

    URL

    PUT

    http://<host>:<port>/jasperserver-pro/rest_v2/organizations/organizationID/

    Content-Type

    Content

    application/xml

    application/json

    A partial organization descriptor that includes the properties to change. Do not specify the following properties:

    id – The organization ID is permanent and can never be modified.

    parentId – Organizations cannot change parents.

    tenantUri – Organizations cannot change the organization hierarchy.

    tenantFolderUri – The organization folder is automatically based on its parent, which cannot be changed.

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The organization was successfully updated.

    400 Bad Request – When some dependent resources cannot be resolved.

    The following example shows a descriptor sent to update the name and description of an organization:

    Setting the Theme of an Organization

    A theme determines how the JasperReports Server interface appears to users. Administrator can create and set different themes for each organization. To set a theme through web services, use the PUT method of the REST organizations service to modify the corresponding property of the desired organization.

    For example:

    PUT http://localhost:8080/jasperserver-pro/rest_v2/organizations/Audit

    For more information about themes, see the JasperReports Server Administrator Guide.

    Deleting an Organization

    To delete an organization, use the DELETE method and specify the organization ID in the URL. When deleting an organization, all of its resources in the repository, all of its sub-organizations, all of its users, and all of its roles are permanently deleted.

    Method

    URL

    DELETE

    http://<host>:<port>/jasperserver-pro/rest_v2/organizations/organizationID/

    Return Value on Success

    Typical Return Values on Failure

    204 No Content – The organization was successfully deleted.

    400 Bad Request – When attempting to delete the organization of the logged-in user.

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