The organizations Service

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

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

<organizations>
  <organization>
    <alias>Finance</alias>
    <id>Finance</id>
    <parentId>organizations</parentId>
    <tenantDesc></tenantDesc>
    <tenantFolderUri>/organizations/Finance</tenantFolderUri>
    <tenantName>Finance</tenantName>
    <tenantUri>/Finance</tenantUri>
    <theme>default</theme>
  </organization>
  <organization>
    <alias>Accounts</alias>
    <id>Accounts</id>
    <parentId>Finance</parentId>
    <tenantDesc></tenantDesc>
    <tenantFolderUri>/organizations/Finance/organizations/Accounts</tenantFolderUri>
    <tenantName>Accounts</tenantName>
    <tenantUri>/Finance/Accounts</tenantUri>
    <theme>default</theme>
  </organization>
</organizations>

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:

{
  "id":"Finance",
  "alias":"Finance",
  "parentId":"organizations",
  "tenantName":"Finance",
  "tenantDesc":" ",
  "tenantNote":null,
  "tenantUri":"/Finance",
  "tenantFolderUri":"/organizations/Finance",
  "theme":"default"
}

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:

{
  "id":"Audit",
  "alias":"Audit",
  "parentId":"Finance",
  "tenantName":"Audit",
  "tenantDesc":"Audit Department of Finance",
  "theme":"default"
}

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:

{
  "alias":"HR"
}

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:

{
  "tenantName":"Audit Dept",
  "tenantDesc":"Audit Department of Finance Division"
}

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

{
  "theme":"jasper_dark"
}

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.

Version: 
Feedback