Import and Export Catalogs

The output of the export command and the input to the import command is called a catalog. It is a set of folders and files that represent the contents of the server’s internal database, including organizations, users, roles, scheduled jobs, and repository resources such as reports and associated files. When you don't need the entire database, you can specify options to export only the contents you need, for example one role and its users.

The resources in the repository often have dependencies on other resources, for example a report that relies on images, input datatypes, and a data source. Exporting one resource includes all of its dependencies, even if they are stored in folders that were not specified in the export command. Importing a catalog that contains such dependencies will re-create the same folder structure in the target repository. Once imported, you can move and redefine the dependencies of these resources.

The catalog can be exported either as a hierarchy of folders and files, or as a single zip file (compressed archive) containing the same information. Regardless of the catalog format, the contents of the catalog are not intended for external access. Objects in the database, such as users, roles, and folders, are described in XML files, and repository resources are stored in various private formats consisting of data files and subfolders. The XML syntax of the catalog files is not publicly defined, and the data files aren’t meant to be accessed.

To access and interact with the server's internal objects, use the REST v2 API. This web service has well defined data types and resource descriptors in XML or JSON formats and a complete set of methods for reading and writing objects on the server. For more information, see the JasperReports Server Web Services Guide.

As of JasperReports Server 5.5, user passwords and data source passwords are encrypted in both the server’s internal database, and in exported catalogs by default. You should still take appropriate measures to secure the catalog file from unauthorized access. Catalog files contain sensitive metadata such as user names, database servers, and internal or external organizations. Catalog files may also contain data in the form of report output such as the PDF of an executive report.

Setting the Import-Export Encryption Key

As of JasperReports Server 5.5, all sensitive passwords in exported catalogs are encrypted for security. In order for two servers to share the encrypted contents of an exported catalog, they must share a private key. The default key is an AES 128-bit string stored in a configuration file.

This encryption is separate from the server's own internal encryption. All passwords are stored encrypted in the internal database. The import-export encryption applies only to export catalogs.

Setting the Import-Export Encryption Key

Configuration File





<property name="keyBytes">
<value>0x2b 0x6c 0x34 0x22 0x44 0x42 0x6f 0xb5 0x7f 0x34 0xd3 0x5a 0x1f 0x92 0xcd 0xdc</value>


Set the value of the keyBytes property to the same hexadecimal value on all servers that will exchange export catalogs.

However, be aware that when you change a private key on a server, all previous exports are invalidated. Therefore, you must configure your new server soon after installing it, and you should configure it with the key from an existing server, if you have one. This way all your servers and all your export catalogs will use the same key and be mutually compatible.

Importing Unencrypted Catalogs

Versions prior to 5.5 did not encrypt the user passwords upon export. These passwords appear in plain text. For backwards compatibility, unencrypted catalogs are still supported and can be imported into a 5.5 server, even with an encryption key is configured.

Passwords that are encrypted by an export operation in JasperReports Server 5.5 have encryption markers, so older passwords without the markers can be detected and imported without being decrypted.