| | 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 | 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 | 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 | 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 | 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 | 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. | ||
Recommended Comments
There are no comments to display.