The organizations Service

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

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

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:

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

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.

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

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.