Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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.
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.
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.xml
or 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.
When you click the Export button in a content app or from the JCR Tools app, the XML opens directly in the browser, replacing the AdminCentral instead of showing the usual Download dialog from the browser. This issue exists since Magnolia 5.6.6. See
-
MAGNOLIA-7310Getting issue details...
STATUS
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.
Many Magnolia content apps that store their data in JCR workspaces provide actions to import and export JCR data. Some examples: Pages app, Assets app, Contacts app, Categories app.
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 magnolia-ui-admincentral
.
The default import and export actions are used in content apps and the JCR Tools app.
The Import and Export actions use the JCRImportCommand
and JCRExportCommand
commands. The commands are defined in the magnolia-ui-admincentral
module and implemented in and
classes.
Node name | Value |
---|---|
modules | |
ui-admincentral | |
commands | |
default | |
export | |
import |
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:
jcr:created
, jcr:createdBy
, jcr:uuid
mgnl:activationStatus
, mgnl:created
, mgnl:createdBy
, mgnl:lastActivated
, mgnl:lastActivatedBy
, mgnl:lastModified
, mgnl:lastModifiedBy
You can adapt the filter or apply other filters for other workspaces according to your requirements.
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.
To export:
To import:
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.
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.
To export:
To import:
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.
The bootstrapping mechanism, directory location and management for Maven modules and light modules is different. See:
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 website
workspace:
import info.magnolia.importexport.DataTransporter session = ctx.getJCRSession("website") xmlFileOutput = new FileOutputStream("/Users/jdoe/tmp/test/website.my-page.xml") DataTransporter.executeExport(xmlFileOutput, false, false, session, "/my-page", "website", DataTransporter.XML) xmlFileOutput.close()
website
workspace:import info.magnolia.importexport.DataTransporter import javax.jcr.ImportUUIDBehavior xmlFile = new File("/Users/jdoe/tmp/test/website.my-page.xml") DataTransporter.importFile(xmlFile, "website", "/", false, ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW, true, true)
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 .
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, see create version handler. Magnolia provides tasks to handle bootstrap files out of the box, see ,
and
; you also can write a custom task for instance by extending
.
Alternatively, you can use the class .