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. This operation is Asynchronous. 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 uses 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. To import into root, you must be authenticated as the system admin (superuser), 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. 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 |
true |
When importing from one organization into a different organization, specify this argument. The resulting organization takes its ID from the import file. If the 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 |
true |
Restores the date, time, and user name of the last modification if they are included in the catalog to import. |
||||||||||
|
includeAudit |
true |
Imports audit events if they are included in the catalog. |
||||||||||
|
includeMonitoring |
true |
Imports monitoring events if they are included in the catalog. |
||||||||||
|
includeServer |
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 this 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 secretUri |
|
Deprecated for security reasons. See the Content-Type below. |
||||||||||
|
Content-Type |
Content |
|||||||||||
|
multipart/form-data |
You must send the secret-key or secret-uri as form-data. See Importing from a Web Form:
|
|||||||||||
|
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 |
||||||
|---|---|---|---|---|---|---|---|
|
in progress |
Import has begun and is still running. |
||||||
|
finished |
The import has been 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 happens if the import operation stopped with the following error codes:
|
Import Errors
In the case of warnings or errors, the GET method returns 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
|
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 is not 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 is 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:
{
"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 inputs from the Import options checkbox 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 Asynchronous 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 as you cannot restart the import service 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. When you select a form data option, the option is set to true. Otherwise, the option is set to false by default.
When an option name is submitted in the form data with any value, then the form data options are considered true for the operation.
|
|
If you do not want to enable any of the import options, then do not specify those option names in the import request when submitting the form. |
The following table describes the options that you can submit in the import request:
|
Import Web Form Options |
Description |
|---|---|
|
update |
When the catalog contains resources with the same path and type as existing resources in the repository, then those in the repository is overwritten. Roles and users in an organization are also 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, and the import fails. |
|
skip-themes |
In commercial releases, specify this option to ignore any themes in the catalog. Otherwise, any themes in the catalog are 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 are imported into the server's audit event logs. |
| include-alerts | Includes data alert when importing the report. |
|
include-monitoring-events |
When this option is specified, any monitoring event logs in the catalog are imported into the server's monitoring event logs. |
|
include-server-settings |
When this option is specified, any global server settings in the catalog are 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>
Recommended Comments
There are no comments to display.