• | Command-Line Utilities |
• | Exporting From the Command Line |
• | Importing From the Command Line |
Command-Line Utilities
The import and export utilities are shell scripts located in the <js-install>/buildomatic folder:
Windows: | <js-install>buildomaticjs-import.bat |
Linux: | <js-install>/buildomatic/js-import.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 in Linux, be sure to add the .sh file extension.
When using the import and export utilities, keep in mind the following:
• | 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. |
• | If you are importing to a different server, you must configure an encryption key on both servers, as described in Setting the Import-Export Encryption Key. Then you must enter the keystore password when prompted by the import command. |
• | Make sure the output location specified for an export is writable to the user running the command. |
• | All URIs are repository paths originating at the root. The repository paths shown in this chapter assume you are using a commercial edition of the server. In the community edition, paths don’t include organizations, for example: |
Commercial editions: | /organizations/organization_1/reports/interactive/CustomersReport |
Community project: | /reports/interactive/CustomersReport |
Exporting From the Command Line
Jaspersoft recommends you stop your server instance before running the export utility. For instructions see the JasperReports Server Installation Guide. |
Specifies repository resources such as reports, images, folders, and scheduled jobs to export to the file system. You can also export the internal definitions for scheduled jobs, users, roles, as well existing audit data. The export output is known as a repository catalog; it is either an archive file or a set of files in a folder structure:
Options in js-export Command
Option
Explanation
--everything
Export everything except audit and monitoring data: all repository resources, permissions, report jobs, users, and roles. If any server settings have been modified in the UI, those are included as well.
This option is equivalent to:
--uris --repository-permissions --report-jobs --calendars --users --roles
--help
Displays brief information about the available options.
--include-access-events
Access events (date, time, and user name of last modification) are exported.
--output-dir
Path of a directory in which to create the output catalog folder.
--output-zip
Path and filename of the output catalog zip file to create.
--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 recursively in all subfolders.
--calendars
When specified, the export will include any and all calendars of all types (holiday, recurring, ...) defined in the scheduler. When calendars are presnent in an export catalog, they are always processed and added upon import.
--repository-permissions
When this option is present, repository permissions are exported along with each exported folder and resource.
This option should only be used in conjunction with --uris.
--roles
Comma separated list of roles to export; if no roles are specified with this option, all roles are exported.
--role-users
When this option is present, each role export triggers the export of all users belonging to the role. This option should only be used in conjunction with --roles.
--uris
Comma separated list of folder or resource URIs in the repository.
--users
Comma separated list of users to export; if no users are specified with this options, all users are exported. Exporting a user includes all user attributes and, in order to maintain consistency, also exports all roles assigned to the user. When specifying users, you must give their organization ID if applicable, for example:
--users superuser, "jasperadmin|organization_1", ...
--include-audit-events
Include audit data for all resources and users in the export.
--include-monitoring-events
Include monitoring data for all resources and users in the export.
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 /fonts 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 the 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
The --uris option allows you to specify one or more resource URIs. A URI can specify a resource such as a report. In this case, all associated resources (such as images, subreports, data sources, resource bundles, and class files) are exported. A URI can also specify a folder. If a folder is specified, the export operation exports all resources and folders contained in the folder. In addition, it recurses through all its subfolders.
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 Command-Line Utilities for guidelines when running the command-line utilities.
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. |
Reads a repository catalog from the your file system and creates the named resource in the JasperReports Server repository. The repository catalog must have been created by the export interface or the js-export command, either as a ZIP archive file or a folder structure.
As of JasperReports Server 5.5, all exports contain encrypted passwords and if you are importing to a different server, you must configure an encryption key on both servers. See Setting the Import-Export Encryption Key for details.
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.
--include-access-events
Restores access events (date, time, and username of last modification) on imported resources.
--include-audit-events
Professional edition only. Imports any audit data that exists in the catalog.
--include-monitoring-events
Professional edition only. Imports any monitoring data that exists in the catalog.
--include-server-settings
Determines whether the system configuration is updated from the catalog. There are two pre-requisites in order 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. |
When server settings are imported, they take effect as soon as the server is started.
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
The default behavior when a resource is found in the target repository that has the same URI as the resource that you are attempting to import is to skip the creation operation and leave the existing resource unchanged (no overwrite 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 of a different type than the existing resource, the server returns an error and skips the update operation.
When you import a user, if its roles exist in the repository, the user is given these 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 must have been created with access events. If you do not import access events, or if they don’t exist in the imported files, the date and time of the import are used.
Recommended Comments
There are no comments to display.