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 | skip | Defines the strategy when importing a resource with broken dependencies. The default value is fail.
| ||||||||||
| 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:
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:
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 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.
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 | 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. | 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 | 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 | The organization ID contained in the import catalog does not match the target organization. Use the mergeOrganizations option. |
| import.broken.dependencies | 0=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:
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: | ||
| 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:
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: | ||
| 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:
Recommended Comments
There are no comments to display.