The import Service

Use the rest_v2/import service to upload a catalog as a zip file and import it into the repository with the given options. The service has two forms, depending on whether called from an application or from a web page. The operation is also asychronous, you must poll the state of the import to make sure it succeeds, or otherwise read an error code and retry the operation with different options.

This chapter includes the following sections:

Launching an Import Operation
Polling the Import Status
Import Errors
Restarting an Import Operation
Canceling an Import Operation
Importing from a Web Form

Launching an Import Operation

Typically, an application will use the rest_v2/import service to upload a catalog zip file as an attachment. Your application can specify import options as URL arguments in the format <argument>=true. Options that are omitted are assumed to be false. You must be authenticated as the system admin (superuser) to import into root, but organization admins (jasperadmin) may import into their organizations or suborganizations.

The import operation is asynchronous, and your application should poll the status of the operation to determine when it finishes or has an error. In case of an error, you can restart the operation with new options or cancel it. The next sections of this chapter explain how to do this.

It is also possible to invoke the import service from a web page, as explained in Importing from a Web Form.

Method

URL

POST

http://<host>:<port>/jasperserver[-pro]/rest_v2/import?<arguments>

Argument

Value

Description

update?

true

Resources in the catalog replace those in the repository if their URIs and types match.

skipUserUpdate?

true

When used with update=true, users in the catalog are not imported or updated. Use this option to import catalogs without overwriting currently defined users.

broken
Dependencies?

skip
include
fail

Defines the strategy when importing a resource with broken dependencies. The default value is fail.

skip – The resource with broken dependency won't be imported, but the import operation will continue.
include – Attempts to import the resource by resolving dependencies with local resources. If unsuccessful, this resource is skipped.
fail – The import operation will stop and show an error.

organization?

orgID

Destination organization for importing. The file being imported must have been exported from an organization, not the root of the server. If this argument is not specified, the organization of the user performing the operation is used.

merge
Organization?

true

When importing from one organization into a different organization, specify this argument. The resulting organization takes its ID from the import file. If organization IDs of import and destination do not match, and this argument is not specified, the operation stops with an error.

skipThemes?

true

When this argument is specified, any themes in the import other than the default theme is ignored. Use this argument when importing catalogs from servers before release 5.5 whose themes are incompatible.

includeAccess
Events?

true

Restores the date, time, and user name of last modification if they are included in the catalog to import.

includeAudit
Events?

true

Imports audit events if they are included in the catalog.

includeMonitoring
Events?

true

Imports monitoring events if they are included in the catalog.

includeServer
Setting?

true

Imports server settings if they are included in the catalog.

Content-Type

Content

application/zip

The catalog file to import. Jaspersoft does not recommend uploading files greater than 2 gigabytes.

Return Value on Success

Typical Return Values on Failure

200 OK – Returns a JSON object that indicates the import has been started. See sections on polling and error messages below.

401 Unauthorized – Import is available only to administrators (superuser or jasperadmin).

The body of the response contains the ID of the import operation needed to check its status:

{
    id:"aad78989-dasds32-dasdsd"
    phase: "inprogress",
    message: "Import in progress"
}

See the following sections to manage the asynchronous import operation.

Polling the Import Status

To check the status of the import, use its ID in the following method:

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/import/<import-id>/state

Return Value on Success

Typical Return Values on Failure

200 OK – The body of the response gives the current state of the import operation.

404 Not Found – When the specified import ID is not found.

As with the initial import request, the body of the response contains the state of the import operation, including its current phase and corresponding message:

{
    id:"aad78989-dasds32-dasdsd"
    phase: "inprogress",
    message: "Import in progress"
}

The following table describes the possible phases of the import operation:

Import Phase

Description

inprogress

Import has begun and is still running.

finished

The import has completed.

failed

The import had an error and was not completed.

pending

The import cannot run because of an error, but it can be restarted with new options. Pending will happen if the import operation stopped with the following error codes:

import.organizations.not.match
import.broken.dependencies

Import Errors

In case of warnings or errors, the GET method will return a JSON structure that includes an error message and code. Some errors also have parameters given as a list of values, for example a list of resource URIs with broken dependencies.

{
    id:"aad78989-dasds32-dasdsd"
    phase: "pending",
    message: "Import is pending",
    error: {
       code: "import.broken.dependencies",
       parameters: [errorParams] 
    }
}

The following tables list the most common warnings and errors, along with an array of parameters, if any. When there is more than one parameter, its position in the array determines its meaning. Some warnings have more than one form with different numbers of parameters:

Warning Code

Parameters

Description

import.resource.uri.too.long

0=resourceURI

The URI given by the parameter is too long.

import.resource.uri.too.long

0=resourceURI
1=length

The URI given by the first parameter is too long. The second parameter is the maximum length.

import.access.denied

0=resourceURI

Access was denied when trying to import the resource with the given URI.

import.resource.not.found

0=resourceURI

The resource with the given URI cannot be found.

import.resource.different.type.
already.exists

0=resourceURI

The target of the given resource URI has a different type than the one being imported. The resource will not be updated.

import.resource.uri.not.valid

0=resourceURI

The resource with the given URI is attached to an organization that is not valid in the target.

import.resource.data.missing

0=resourceURI

The resource with the given URI is missing from the catalog and will be skipped.

import.reference.resource.not.found

0=resourceURI

The resource with the given URI has dependent resources that are not in the import catalog.

import.reference.resource.not.found

0=resourceURI
1=dependentURI

The resource with the first URI has a dependent resource with the second URI that is not in the import catalog.

Error Code

Parameters

Description

import.organizations.not.match

0=catalogOrganization
1=targetOrganization

The organization ID contained in the import catalog does not match the target organization. Use the mergeOrganizations option.

import.broken.dependencies

0=resourceURI
1=resourceURI
...

The resources in the list have broken dependencies in the import catalog.

import.organization.into.root.not.allowed

0=catalogOrganization

You cannot import the organization into the root.

import.root.into.organization.not.allowed

0=targetOrganization

The import catalog contains root resources that cannot be imported into the target organization.

import.failed

0=message

The import failed for the reason in the message.

import.failed.zip.error

none

The server cannot read the zip file.

import.failed.content.error

none

The zip file is not a valid import catalog.

Restarting an Import Operation

When an import is in the pending state, you can try to restart it. To see the import options that led to the pending state, use the GET method with the import ID.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/import/<import-id>

Return Value on Success

Typical Return Values on Failure

200 OK – Returns a JSON object that contains the options of the import operation.

404 Not Found – When the specified import ID is not found.

The response contains a JSON structure that lists all options specified for this import operation:

{
   "brokenDependencies": "fail",  
   "organization" : "organization_1",
   "parameters" : ["role-users", "repository-permissions"]
}

Once you know which options blocked the import operation, use the PUT method of the import service to send new options and restart the operation.

Method

URL

PUT

http://<host>:<port>/jasperserver[-pro]/rest_v2/import/<import-id>

Content-Type

Content

application/json

A JSON object that contains the new import options, for example:

{
   "brokenDependencies": "include",  
   "organization" : "organization_1",
   "parameters" : ["role-users", "repository-permissions"]
}

Return Value on Success

Typical Return Values on Failure

200 OK – The body of the response is shown below.

404 Not Found – When the specified import ID is not found.

The body of the response shows the import options that were applied:

{
   "brokenDependencies": "include",  
   "organization" : "organization_1",
   "parameters" : ["role-users", "repository-permissions"]
}

Canceling an Import Operation

To cancel an import operation that you have started, send a DELETE request with the ID of the operation.

Method

URL

DELETE

http://<host>:<port>/jasperserver[-pro]/rest_v2/import/<import-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 import ID is not found.

Importing from a Web Form

Alternatively, you can call the import service directly from a web page with form and input tags. Use checkbox inputs to submit the import options and a file input to upload the catalog zip file.

Submitting an import catalog through an HTML form is also an asychronous operation. However, web pages are not practical for receiving the ID and polling the status of the import operation. Therefore, you are limited in knowing whether the import succeeded and unable to restart it if needed.

Method

URL

POST

http://<host>:<port>/jasperserver[-pro]/rest_v2/import

Content-Type

Content

multipart/form-data

The form data is sent by the browser when you submit a page with input tags. For example:

form-data; name="file-name",
form-data; name="include-access-events",
form-data; name="update",
...

application/zip

The catalog file to import. Jaspersoft does not recommend uploading files greater than 2 gigabytes.

Return Value on Success

Typical Return Values on Failure

200 OK – Returns a JSON object that indicates the import has been started.

401 Unauthorized – Import is available only to administrators (superuser or jasperadmin).

The form data options are similar to the arguments in the other import format. Submitting an option name as form data sets it to true for this operation, otherwise all options are false by default. The following table describes the options you can submit in the request:

Import Web Form Options

Description

update

When the catalog contains resources with the same path and type as existing resources in the repository, those in the repository will be overwritten. Roles and users in an organization will also be overwritten with any in the catalog.

skip-user-update

When update is specified, you can also specify this option to avoid overwriting any user profiles.

merge-organization

In commercial releases with organizations, specify this option if the catalog is exported from one organization and imported into a different one. If this option is not specified, and the catalog is sourced from a different organization than the destination, the import will fail.

skip-themes

In commercial releases, specify this option to ignore any themes in the catalog. Otherwise, any themes in the catalog will be imported into the repository.

include-access-events

When specified, the timestamps for resource creation and modification of each resource are imported into the repository.

include-audit-events

When this option is specified, any audit event logs in the catalog will be imported into the server's audit event logs.

include-monitoring-events

When this option is specified, any monitoring event logs in the catalog will be imported into the server's monitoring event logs.

include-server-settings

When this option is specified, any global server settings in the catalog will be imported into the server.

The following HTML example shows how the import service can be invoked from a web page:

<form method="post"
      action="http://example.com:8090/jasperserver-pro/rest_v2/import"
      enctype="multipart/form-data">
    Import a catalog file to JasperReports Server:
    <input type="file" name="file-name" required="true" accept="application/zip">
    <fieldset>
        <legend>Options:</legend>
        <input type="checkbox" name="update">Overwrite resources of the same name<br>
          <input type="checkbox" name="skip-user-update">But do not overwrite users<br>
        <input type="checkbox" name="merge-organization">Import into a different organization<br>
        <input type="checkbox" name="skip-themes">Do not import themes<br>
        <input type="checkbox" name="include-access-events">Import created/modified timestamps<br>
        <input type="checkbox" name="include-audit-events">Import audit event logs<br>
        <input type="checkbox" name="include-monitoring-events">Import monitoring event logs<br>
        <input type="checkbox" name="include-server-settings">Import global server settings<br>
    </fieldset>
    <input type="submit" value="Submit">
</form>
Version: 
Feedback