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.

As of JasperReports Server 7.5, import operations must specify a key to decrypt any passwords in the import catalog. Use either the secret-key or the secretUri parameter. For more information about import and export keys, see the JasperReports Server Security Guide.

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 other JasperReports Server versions that used themes incompatible with your version.

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.

keyalias

key

Specify the alias of the key (for example "productionServerKey") associated with the import catalog. This is the key that was used to encrypt any passwords in the catalog when it was exported. 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, in which case the catalog must have been exported from this server, unless this key has been shared with another server.

For a list of available keys, see The keys Service. For more information about import and export keys, see the JasperReports Server Security Guide.

secret-key

hex key

Specify the encryption key in hexadecimal format (for example "0x1c 0x40 0xb9 0xf6 0xe2 0xd3 0xf9 0xd0 0x5a 0xab 0x84 0xe6 0xd4 0xe8 0x5f 0xed") associated with the import catalog. You can obtain the key in hexadecimal format when exporting the catalog from the source server.

secretUri

repo URI

Specify the encryption key in a secure file resource, identified by its URI in the repository. This must be the same key used when exporting the catalog from the source server.

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:

v7.9.0

Main menu

You are here

The import Service

Launching an Import Operation

Polling the Import Status

Import Errors

Restarting an Import Operation

Canceling an Import Operation

Importing from a Web Form