The export Service

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: 

{
  "roles": ["ROLE_USER","ROLE_MANAGER|organization_1"],
  "users": ["superuser","joeuser|organization_1"],
  "uris":  ["/public/Samples/Reports/AllAccounts",
            "/organizations/organization_1/reports/Survey/Survey_Data"],
  "parameters": ["role-users", "repository-permissions"]
}

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.
scheduledAlerts A list of report URIs for which all scheduled alerts are exported. If you specify a folder URIs, the scheduled alerts for all reports in the folder, recursively, are exported.

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.

skip-favorite-resources

When specified, the resources added to Favorites are not exported.

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:

{
  "id": "njkhfs8374",
  "phase": "inprogress",
  "message": "Progress..."
}

The response may also warn you of any broken dependencies in the export that may affect a future import operation:

{
  "id": "njkhfs8374",
  "phase": "inprogress",
  "message": "Progress..."
  "warnings": [
    {
      "code": "export.broken.dependency",
      "message":"Resource with broken dependencies",
      "parameters": [
        "path_to_broken_resource"]
    }, ...
  ]
}

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:

{
  "phase": "inprogress",
  "message": "Progress..."
}
 
{
  "phase": "ready",
  "message": "Ready!"
}
 
{
  "phase": "failure",
  "message": "Not enough space on 
              disk"
}

 

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.