This page deals with importing and exporting data to and from the JCR. Magnolia provides functions to export data from a JCR workspace into a file, and to import data by file into a JCR workspace. This process is known as Bootstrapping.
Importing and exporting JCR data is useful when migrating content from one system to another, to provide configuration data or when making a backup. You can choose between XML and YAML formats.
A bootstrap file is an intermediate file that contains JCR data stored in XML or YAML format.
It is created by an export action, and it can be used to import JCR data into its corresponding workspace.
Bootstrap files can contain any type of data which can be stored in JCR, including both text and binary data.
In Magnolia, bootstrap files typically contain content or configuration data.
Magnolia supports two formats for file-based JCR data.
- JCR System View XML format - Subsequently referred to as XML format.
- YAML format
Data can be exported and imported using either format.
All features and functions work for both formats.
File names match the path of the data in the repository, such as
website.my-page.yaml. When you export a node, its children are also exported.
Magnolia can export JCR data to XML format. This format is specified by the JCR specification (see JCR System View XML). Magnolia uses this format for importing and exporting JCR data.
The exported XML reflects the hierarchy of the data in the repository.
The YAML-based JCR data file is Magnolia specific and not part of the official JCR specification.
The structure of the data in a YAML export is comparable to the XML-based JCR data file because it also reflects the hierarchy of the data in the repository. However, YAML files have a simple format. This makes them smaller, easier for humans to read and simpler to diff, merge and edit. These characteristics make YAML versions of JCR data particularly useful, for example, in the case of configuration data that needs to be edited by several team members during the development process.
Do not confuse the YAML-based bootstrap files with YAML definition files. If you need YAML definition files, see Downloading YAML definitions.
If Magnolia fails to import YAML-based JCR data indicating "unacceptable character" - the file encoding of your system and the Magnolia file encoding are different.
~/.profile and add:
To check, in Terminal type in:
It should return:
Importing and exporting JCR data with apps from the Admin UI
Additionally, the JCR Tools app allow you to operate on data in all Magnolia workspaces, including those where the Export and Import actions are not available in the workspace-specific app, for example in the Security app.
Note that all the apps mentioned, including the JCR Tools app, rely on the default import and export actions defined in the module
Default import and export actions
The default import and export actions are used in content apps and the JCR Tools app.
The Import and Export actions use the
JCRExportCommand commands. The commands are defined in the
magnolia-ui-admincentral module and implemented in JcrImportCommand and JcrExportCommand classes.
The export action can also contain filters.
Exporting binary data (such as images or videos) from the JCR to YAML throws an exception. Magnolia does not allow you to export binary data to YAML files in order to prevent excessive memory consumption.
The default export action provides the ability to apply filters to improve readability and omit data you do not need outside of Magnolia. Filtered properties are not exported to the XML or YAML file. However, when you import the file into the JCR repository again, the JCR node created contains all properties according to its node type definition.
The default export action defines a filter for the
configuration workspace and excludes the following properties:
You can adapt the filter or apply other filters for other workspaces according to your requirements.
Exporting and importing from content apps
The screenshot below is based on the Pages app. However, importing and exporting JCR data works in the same way on every content app which provides these actions. Note that you can add these actions to your custom content apps too.
Export and Import actions are available in the action bar and in the context menu (right-click).
When you import a file, the imported nodes become children of the selected parent node.
- Select a node to export the node and its children.
- Click Export.
- Choose a format: XML or YAML.
- Select a parent node under which you want to import the nodes.
- Click Import.
- Choose a format: XML or YAML.
By default new UUIDs are generated for nodes that have the same ID as an existing node in the repository. When using the JCR Tools app, you can change this behavior while using the Import tool.
Exporting and importing from the JCR Tools app
The import and export tools in the JCR Tools app allow you to operate on data in all Magnolia workspaces, including those where the Export and Import actions are not available in the workspace-specific app, for example in the Security app.
- Select the Workspace where the content resides.
- In Base path, type the path to the node to export.
- Select Format: XML or YAML.
- Select the type of Compression: None, ZIP or GZIP.
- Click Execute.
- Select the Workspace into which the content should be imported.
- In Base path, type the path into which content should be imported.
- Browse to the file to import.
- Select how to handle conflicting UUIDs. These options only apply when the file to import contains a UUID - remember that the UUID can be omitted dring export - and when an identical UUID already exists in the repository.
- Only import if no existing node only import and generate a new UUID if the node does not already exist.
- Generate a new id for imported nodes will result in a new UUID being generated for nodes being imported.
- Remove existing nodes with the same id will result in nodes with the same UUID as those imported being deleted before the import.
- Replace existing nodes with the same id will result in nodes with the same UUID as those imported being replaced with the imported nodes.
- Click Execute.
Importing bootstrap files from modules
As a developer, you typically adapt configuration data and content on your development environment. You then need to make it accessible on the production environment without manually importing the bootstrap files. Magnolia provides mechanisms to automatically import bootstrap files, for example when a module is installed for the first time.
Importing and exporting JCR data with Groovy scripts
You can execute Groovy scripts on a running instance to both export and import JCR data. This type of export or import only supports XML file format. See the Groovy module and Groovy app for information about how to execute Groovy scripts on a running Magnolia instance.
Sample Groovy script to export the node
/my-page from the
Importing and exporting JCR data programmatically with Java
The need to export and import JCR data using custom Java classes is very rare. Generally, using Groovy scripts is sufficient.
If you need to export JCR data, use the class DataTransporter.
When importing bootstrap files, we recommend you use task classes, which can handle bootstrap files called from your module version handler. For an example about how to use the module version handler. Magnolia provides tasks to handle bootstrap files out of the box, see ModuleBootstrapTask, ModuleDependencyBootstrapTask and SamplesBootstrapTask; you also can write a custom task for instance by extending AbstractTask.
Alternatively, you can use the class BootstrapUtil.