The rest_v2/export service works asynchronously: first you request the export with the desired options, then you monitor the state of the export, and finally you request the output file. Each step requires a different service call.
You must be authenticated as the system admin (superuser) for the export services.
This chapter includes the following sections:
| • | Requesting an Export |
| • | Polling the Export Status |
| • | Fetching the Export Output |
| • | Canceling an Export Operation |
Requesting an Export
Use the following method to specify the export options for your export request:
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/export/ | ||
| Content-Type | Content | ||
| application/json | A JSON object that describes the export options. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Returns a JSON object that gives the ID of the running export operation. | 401 Unauthorized – Export is available only to the system admin user (superuser). | ||
The content to send describes the export options, for example:
As shown above, commercial editions must use the organization syntax for all roles, users, and URIs.
The following table describes the options you can list in the request.
| Export Options | Description |
|---|---|
| roles | A list of role names to export. Specify the role-users parameter to also export all users who have these roles. |
| users | A list of user names to export. |
| uris | A list of resources or folders to export, specified as repository URIs. When a folder is specified, all its contents and all its subfolders recursively are included. To export all resources in the repository or in an organization, specify "/" (root) in this list. When you specify an organization ID below, the URIs in this list are all relative to the organization. |
| scheduledJobs | A list of report URIs for which all scheduled jobs are exported. If you specify a folder URIs, the scheduled jobs for all reports in the folder, recursively, are exported. |
| resourceTypes | A list of resource types that filters any selected resources for export. When omitted, all resources specified by URI or folder URI are exported. When specified, only the resource types in this list are exported. |
| organization | A single organization ID that determines a branch of the repository for export. When this option is specified, this organization becomes the root for all roles, users, and URIS to be listed for export. |
| parameters | A list of parameters that act as flags: if specified, the corresponding action is taken, if omitted they have no effect. The export parameters are listed in the following table. |
| keyalias | Specify the alias of the key (for example "productionServerKey") to use when encrypting passwords in the export catalog. The alias must correspond to a custom key in the importing server's keystore. When not specified, the server uses its own import-export key, and unless this key is shared with another server, the catalog may only be imported back into the same server. For a list of available keys, see The keys Service. This key must also be available on the server that imports the catalog. For more information about import and export keys, see the JasperReports Server Security Guide. |
The following table describes the export parameters that can be specified in the parameters option:
| Export Parameters | Description |
|---|---|
| everything | Export everything except audit and monitoring: all repository resources, permissions, report jobs, users, roles, and server settings. |
| role-users | When this option is present, each role export triggers the export of all users belonging to that role. This option should only be used if roles are specified. |
| repository-permissions | When this option is present, repository permissions are exported along with each exported folder and resource. This option should only be used if URIs are specified. |
| skip-dependent-resources | When specified, only the resources specified by URIs or resource types are exported, no dependent resources such as data sources, queries, or files included by reference are exported. For example, you can use this parameter to export a single report. The export catalog created with this parameter will cause broken dependencies during import unless the same dependencies already exist in the same relative locations in the destination. |
| skip-suborganizations | When specified, the export will omit all the items such as roles, users, and resources that belong to suborganizations, even if they are directly specified using the corresponding options. When no organization ID is specified, this flag applies to the root such that no top-level organizations are included in the export, only the contents of the root. |
| include-attributes | Includes all attributes that are associated with a item being exported, such as a user, an organization, or the root. |
| skip-attribute-values | When specified with include-attributes, only attribute names are exported with null values. Use this to prevent applying attributes that are specific to one server or one organization. |
| include-server-settings | When specified, the configuration and security settings on the server are exported. When imported into another server, these settings will take effect immediately. |
| include-access-events | When this option is present, access events (date, time, and user name of last modification) are exported along with each exported folder and resource. This option should only be used if URIs are specified. |
| include-audit-events | Include audit data for all resources and users in the export. The audit feature must be enabled in the server configuration. |
| include-monitoring-events | Include monitoring events. The monitoring feature must be enabled in the server configuration. |
The body of the response contains the ID of the export operation needed to check its status and later download the file:
The response may also warn you of any broken dependencies in the export that may affect a future import operation:
Polling the Export Status
After receiving the export ID in the response to the export request, you can check the state of the export operation. The server takes up to several seconds to generate the export catalog, depending on the size of the requested resources and the load on the server.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/export/<export-id>/state | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Returns a JSON object that gives the current state of the export operation. | 404 Not Found – When the specified export ID is not found. | ||
The body of the response contains the current state of the export operation:
Fetching the Export Output
When the export state is ready, you can download the zip file containing the export catalog.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/export/<export-id>/<fileName> | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Returns the exported catalog as a zip file with the given <fileName>. | 404 Not Found – When the specified export ID is not found. | ||
Canceling an Export Operation
To cancel an export operation that you have started, send a DELETE request with the ID of the export operation.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/export/<export-id> | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – The specified export operation was canceled. | 404 Not Found – When the specified export ID is not found. | ||
Recommended Comments
There are no comments to display.