Import and Export Through the Command Line¶

Warning

If you installed JasperReports Server from the binary installer, the command-line utilities are configured by the installer. If you installed the WAR file distribution, you must follow the instructions in Configuring Import-Export Utilities before you can run the utilities.

The import and export utilities are shell scripts in the <js-install>/buildomatic folder:

Windows:	`<js-install>/buildomatic/js-import.bat` `<js-install>/buildomatic/js-export.bat`
Linux:	`<js-install>/buildomatic/js-import.sh` `<js-install>/buildomatic/js-export.sh`

The examples in this chapter use the shortened Windows commands without the optional .bat extension on the command line. If you are running JasperReports Server on Linux, be sure to add the .sh file extension.

When using the import and export utilities, keep the following in mind:

JasperReports Server should be stopped when using the import and export utilities. This is very important for the import utility to avoid issues with caches, configuration, and security.
All command-line options start with two dashes (--).
You must specify either a directory or a zip file to export to or import from.
The import and export commands include additional options to import and export keys between servers that need to share export catalogs. The options for sharing keys are documented in the JasperReports Server Security Guide. Once keys have been shared between servers, the commands in this chapter can be used without specifying keys.
If you are exporting or importing organizations, you must be aware of resource dependencies outside of the organization that may block the operation. For more information, see Dependencies During Import and Export.
Ensure the output location specified for an export is writable to the user running the command.
All URIs are repository paths originating at the root (/). In commercial editions of the server, even those with a single default organization, the path must include the organization unless you specify --organization option, for example:

/organizations/organization_1/reports/interactive/CustomersReport

Warning

The import and export scripts provide access to the repository and internal database of the server. Even though all passwords are encrypted during export, a catalog may still contain sensitive URLs and data. You should set permissions on the host file system and operating system to secure the scripts and any catalogs you export.

Exporting from the Command Line¶

Usage: js-export [OPTIONS]

Note

We recommend you stop your server instance before running the export utility. For instructions see the JasperReports Server Installation Guide.

Use this command to export repository resources such as reports, images, dashboards, domains,, or entire folders to a catalog file. You can also export scheduled jobs, organizations, users, roles, and metadata such as repository access times and auditing events. The export output is known as a catalog. It is either a zip archive file or a set of files in a folder structure.

The js-export command includes additional options for exporting cryptographic keys. For more information about this special use case, see the JasperReports Server Security Guide.

Options in js-export Command

Option	Explanation
`--everything`	Exports everything except audit and monitoring data: all repository resources, permissions, report jobs, organizations, users, and roles. If any server settings have been modified in the UI, those are also included. May be combined with `--organization` to export everything in just one organization. This option is equivalent to: `--uris --repository-permissions --report-jobs --calendars --users --roles`
`--help`	Displays brief information about the available options.
`--include-access-events`	Exports repository events (date, time, and username of last modification).
`--output-dir`	Path of a location to export the catalog in a folder structure.
`--output-zip`	Path and filename to export the catalog as a zip file.
`--report-jobs`	Comma-separated list of repository report unit and folder URIs for which report unit jobs should be exported. For a folder URI, this option exports the scheduled jobs of all reports in the folder and all subfolders.
`--calendars`	When specified, the export includes all calendars of all types (holiday, recurring, ...) defined in the scheduler. When calendars are present in an export catalog, they are always processed and added on import.
`--uris`	Comma-separated list of folder or resource URIs to export from the repository. If the URI specifies a folder, the export operation exports all resources and folders contained in the folder. In addition, it recurses through all its subfolders.
`--resource-types`	Comma-separated list of resource types to export. The available resource types are: adhocDataView, awsDataSource, beanDataSource, customDataSource, dashboard, dataType, file, folder, inputControl, jdbcDataSource, jndiJdbcDataSource, listOfValues, mondrianConnection, mondrianXmlaDefinition, olapUnit, query, reportUnit, virtualDataSource, xmlaConnection.
`--repository-permissions`	This option exports repository permissions with each exported resource or folder. This option should only be used with `--uris`.
`--skip-dependent-resources`	Exports resources without their dependencies, for example a report without its external data source, input control definitions, or image files.
`--organization`	Specify the ID of an organization to export. When specified, only resources, users, and roles from this organization (and its suborganizations) are exported. When specified, all URIs are relative to this organization.
`--skip-suborganizations`	When used with `--organization`, specifies that suborganizations (and their resources, users, and roles) should not be exported.
`--roles`	Comma-separated list of roles to export. If no roles are specified with this option, all roles are exported.
`--role-users`	Use only with `--roles`. This option exports all users belonging to each exported role.
`--users`	Comma-separated list of users to export. If no users are specified with this option, all users are exported. Exporting a user includes all user attributes and all roles assigned to each user. When specifying users, you must give their organization ID if applicable, for example: `--users superuser, "jasperadmin\|organization_1"`
`--users-roles`	Use only with `--users`. This option exports all roles belonging to each exported user.
`--include-attributes`	Specify this flag to export attributes on any user, organization, or root level that is exported.
`--skip-attribute-values`	When used with `--include-attributes`, specifies that only attribute names are exported, values are null.
`--include-audit-events`	Includes audit data for all resources and users in the export.
`--include-monitoring-events`	Includes monitoring data for all resources and users in the export.
`--include-server-settings`	Includes persistent server settings, such as Log Settings, Ad Hoc Settings, Ad Hoc Cache, and OLAP Settings.
`--report-alerts`	Comma-separated list of repository report unit and folder URIs for which report unit alerts should be exported. For a folder URI, this option exports the alerts of all reports in the folder and all subfolders.

Warning

User passwords are encrypted during the export by default, but exported catalogs may contain sensitive data. Take appropriate measures to secure the catalog file from unauthorized access.

Examples:

Export everything in the repository:

js-export --everything --output-dir myExport

Export the /reports/interactive/CustomersReport report unit to a catalog folder:

js-export --uris /organizations/organization_1/reports/interactive/CustomersReport --output-dir myExport

Export the /images and /reports folders:

js-export --uris /organizations/organization_1/images /organizations/organization_1/reports --output-dir myExport

Export all resources (except users, roles, and job schedules) and their permissions to a zip catalog:
```
js-export --uris / --repository-permissions --output-zip myExport.zip
```

Export all resources and report jobs:

js-export --uris / --report-jobs / --output-dir myExport

Export the report jobs of the /reports/interactive/CustomersReport report unit:

js-export --report-jobs /organizations/organization_1/reports/interactive/CustomersReport --output-dir myExport

Export all roles and users:

js-export --roles --users --output-dir myExport

Export ROLE_USER and ROLE_ADMINISTRATOR roles along with all users belonging to either role:
```
js-export --roles ROLE_USER, ROLE_ADMINISTRATOR --role-users --output-dir myExport
```
Export all resources in an organization, but not its suborganizations:
```
js-export --organization organization_1 --skip-suborganizations --uris /
```
Note

The folder named Temp at the root and in every organization is a special folder. None of the folders or resources in a Temp folder are exported.

Importing from the Command Line¶

See Import and Export Through the Command Line for guidelines when running the command-line utilities.

Warning

When using the js-import command-line utility, the server must be stopped to avoid issues with caches, configuration, and security. For instructions see the JasperReports Server Installation Guide.

Usage: js-import [OPTIONS]

Use this command to read the catalog from your file system and create the resources in the JasperReports Server repository. The import command can also create entities such as organizations, users, roles, and attributes. The catalog must be one created by the export interface or the js-export command, either as a ZIP archive file or a folder structure.

Exported catalogs may contain encrypted passwords. If you are importing to a different server, you must configure an encryption key on both servers. See The Import-Export Encryption Keys for details.

The js-import command includes additional options for importing cryptographic keys. For more information about this special use case, see the JasperReports Server Security Guide.

Options in js-import Command

Option	Explanation
`--help`	Displays brief information about the available options.
`--input-dir`	Path for importing a catalog from a directory.
`--input-zip`	Path and filename for importing a catalog from a zip file.
`--update`	Resources in the catalog replace those in the repository if their URIs and types match.
`--skip-user-update`	When used with `--update`, users in the catalog are not imported or updated. Use this option to import catalogs without overwriting currently defined users.
`--organization`	If the import catalog is from an organization, it specifies the target organization where it should be imported. The organization ID should match the ID of the organization in the import catalog, if not, use the `--merge-organizaiton` option.
`--merge-organization`	Use this option when `--organization` is specified but it does not match the ID of the organization in the import catalog. When merging organizations, the contents of the import override the target organization for any user, role, or resource with the same name. A merged organization takes the organization ID of the imported organization.
`--broken-dependencies`	Specifies the action to take when importing a resource with a broken dependency. One of the following values: `skip` – Does not import the resource with the broken dependency, but continues to import other resources. `include` – Attempts to import the resource with the broken dependency. The import succeeds if there is already a resource in the destination that satisfies the dependency. If the dependency is not satisfied in the destination, the resource is skipped and the import continues. `cancel` – Stops the import operation.
`--include-access-events`	Restores access events (date, time, and username of last modification) on imported resources.
`--include-audit-events`	Imports any audit data in the catalog.
`--include-monitoring-events`	Imports any monitoring data in the catalog.
`--include-server-settings`	Determines whether the system configuration is updated from the catalog. There are two prerequisites for the catalog to contain configuration settings: The originating server settings must be modified through the UI (Log Settings, Ad Hoc Settings, Ad Hoc Cache, and OLAP Settings). For more information, see Configuration Settings in the User Interface. The catalog must be exported with the "everything'" option from the user interface or the command-line utility. Imported server settings take effect when the server is started.
`--skip-themes`	This flag is required when importing a catalog that includes a theme from some Release 5 server versions. If you need to import a custom theme, use the Theme UI to download it from the source server and upload it to the target server. In some cases, you may need to take more extensive steps. For more information, see Downloading and Uploading Theme ZIP Files.
`--include-alerts`	Includes data alert when importing the report.

Examples:

Import the myExport.zip catalog archive file:
```
js-import --input-zip myExport.zip
```
Import the myDir catalog folder, replacing existing resources if their URIs and types match those found in the catalog:
```
js-import --input-dir myDir --update
```
Import the myExport.zip catalog archive file but ignore any users found in the catalog:
```
js-import --input-zip myExport.zip --update --skip-user-update
```

Import the myDir catalog folder with access events:

js-import --input-dir myDir --include-access-events

When a resource in the target repository has the same URI as on that you are importing, the default behavior is left as it is and the existing resource remains unchanged (no overwriting occurs).

To delete the existing resource and replace it with a new one (of the same type and with the same URI), use the --update option. Note that, if the resource in the export catalog is a different type than the existing resource, the server returns an error and skips the update operation.

When you import a user whose roles exist in the repository, the user is given those roles. User properties are imported with the user.

When you import access events, the date and time of the last modification before export is restored on import for every resource. The catalog folder has to be created with access events. If you do not import access events, or if they do not exist in the imported files, then the date and time of the import are used.

Configuring Import-Export Utilities¶

If you installed JasperReports Server from the binary installer, the import-export utilities are configured by the installer. If you installed the WAR file distribution, you must configure several files before you can use the import-export utilities.

Alternatively, see Alternate Import-Export Scripts because the alternate scripts do not require any configuration, regardless of the installation method.

To configure the import-export utilities

Depending on the database you use, copy the installation configuration file:

from: <js-install>/buildomatic/sample_conf/<database>_master.properties

to: <js-install>/buildomatic/default_master.properties
Edit the default_master.properties file to set values specific to your installation. For more information about the settings in this file, see the JasperReports Server Installation Guide.

Note

Oracle users can set the sysUsername and sysPassword to the same name as dbUsername and dbPassword in the default_master.properties. The system username and password are not required because js-import and js-export do not make changes to the database schema.
Run the following command:
```
 js-ant clean-config gen-config
```
This command generates the following files with the values that you added to the default_master.properties file:
- <js-install>/buildomatic/build_conf/default/js.jdbc.properties
- <js-install>/buildomatic/build_conf/default/js.quartz.properties (only for DB2 and PostgreSQL)
Make sure that the JDBC driver for your database is located in the following folder:
```
<js-install>buildomatic/conf_source/iePro/lib
```
If necessary, you can find links for downloading JDBC drivers from the Jaspersoft Community website.