Importing and exporting

Importing and exporting content and data is useful when migrating content from one system to another, taking a backup or bringing in a custom taxonomy. The default file format for content exports is JCR System View XML. You can also export content hierarchies to a ZIP archive. The tools available range from a quick right-click export to scripting and writing custom import handlers depending on the frequency of use.

File formats

The file formats that can be used for imports and exports include:

• XML adheres to JCR System View XML Mapping. Magnolia exports into this format by default. Imported XML files must also adhere to it. When used to export data, the XML structure reflects the hierarchy of the data in the repository. The name of the export file reflects the path of the data in the repository such as website.demo-project.about.xml. When used to export a node, the node's subnodes are also included.
• ZIP and GZIP files are ideal for importing documents in the Document Management System (DMS). The ZIP file can contain an entire directory structure with files and folders. Corresponding structure will be created in the repository on import.
• CSV and Excel files can be used for imports and exports with the Content Translation Support module .

Tools

Context menu

You can initiate imports and exports in AdminCentral with the context menu (right-click). This option is not available in all repositories.

If a node is selected when performing an import, then the imported node or data becomes children of the specified parent. If no node or data is specified, then the top imported node or data is included at the root of the repository or path into which the import is initiated.

To export XML:

1. Right-click a node to export the node and its children.
2. Select Export tree to XML. Accept any system requests to download file containing XML.

To import XML:

1. Right-click a parent node under which you want to import the content.
2. Select Import from XML.
3. Browse to the file to import.
4. Click Import.
   

You can upload a ZIP file in the Documents workspace. See the Export tool on how to export content to a ZIP file.

To import a ZIP file:

1. Right-click a folder or document and select Upload ZIP file.
2. Browse to the file.
3. In Encoding, select Windows or Mac depending on what system the ZIP file was created on.
4. Click Save.

Import and export tool

Use the import tool to import XML files to all repositories including those not available with the context menu.

To export:

1. Go to Tools > Export.
2. Select the Repository where the content resides.
3. In Base path, type the path to the node to export.
4. Select Keep versions if prior versions of the exported node should be kept.
5. Select Format XML if XML should be formatted. Relevant only if Keep versions is selected; otherwise Format XML has no affect, the XML is automatically formatted into the JCR Specification xml Mapping format.
6. Select the type of Compression: XML (no compression), ZIP or GZIP.
7. Click Export.
   

To import:

1. Go to Tools > Import.
2. Select the Repository into which the content should be imported.
3. In Base path, type the path into which content should be imported.
4. Select Keep versions if prior versions of the imported node should be kept.
5. Browse to the file to import.
6. Select how to handle conflicting UUIDs. These options only apply when an identical UUID already exists in the repository.
   
   • 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.
7. Click Import.
   

Content Translation Support module

This tool uses the   Content Translation Support module to import and export page content in CSV and Excel formats. The module's documentation contains procedures for exporting and importing content into Magnolia as well as performing the translation.

Scripting

You can export content from Magnolia using a simple Groovy script. This example exports the news-overview page and children provided in demo-project. This script performs the functionality equivalent to exporting to XML for the news-overview node.

import info.magnolia.importexport.DataTransporter
hm = ctx.getHierarchyManager('website')
newsRoot = hm.getContent('/demo-project/news-and-events/news-overview')
xmlFileOutput = new FileOutputStream('C:/test/export/news.xml')
DataTransporter.executeExport(xmlFileOutput, false, false, 
  hm.getWorkspace().getSession(), newsRoot.getHandle(), 'website', 
  DataTransporter.XML)
 xmlFileOutput.close()

Similarly, you can import content with the following Groovy script. It imports the content exported for news-overview and imports it into demo-project. This script performs the functionality equivalent to right-clicking /demo-project/news-and-events and importing the XML file.

import info.magnolia.importexport.DataTransporter
import javax.jcr.ImportUUIDBehavior
hm = ctx.getHierarchyManager('website')
newsRoot = hm.getContent('/demo-project/news-and-events')
xmlFile = new File('C:/test/export/news.xml')
DataTransporter.importFile(xmlFile, 'website', newsRoot.getHandle(), false, 
  ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW, true, true) 

For more information on Groovy see Groovy module documentation.  DataTransporter API provides information on the parameters for the executeExport and importFile methods.

Programmatically

Import and export functionality is implemented in package info.magnolia.importexport. This implementation is primarily contained within the DataTransporter and PropertiesImportExport classes. You can invoke methods in these classes from a custom class. An example for implementing the executeExport method:

File xmlFile = new File(folder.getAbsoluteFile(), xmlName);
FileOutputStream fos = new FileOutputStream(xmlFile);
try {
  DataTransporter.executeExport(fos, false, false,
  MgnlContext.getHierarchyManager(repository).getWorkspace().getSession(),
  node.getHandle(), repository, DataTransporter.XML);
 }
finally { IOUtils.closeQuietly(fos);}

Data and   Content Translation Support modules include examples of commands that import and export content. The commands use an import handler that corresponds to the data type upon which the command is invoked. For example, CompanyImportHandler is used to import company data while RSSFeedImportHandler is used to import RSS aggregator data.

Both handlers extend the ImportHandler class in the Data module. ImportHandler provides the common functionality needed for all import handlers such as tracking configuration characteristics (repository, name, target). You can write your own import handler by extending the ImportHandler class. In your custom handler, read the incoming data and assign it to parameters as configured in the data type. Implement the doImport method to do the actual data processing such as parsing the incoming file.

See Importing data on how to configure an import handler in AdminCentral. Importers and exporters  in Content Translation Support module is another example. These examples also show how an import handler can be periodically executed without a corresponding command. Using the Data module to import data gives an example of an import handler that is executed at the same time every night. This example includes a import handler implementation that parses and processes a non-XML file. This import handler implementation extends SimpleImportHandler which in turn is an extension of ImportHandler. The onDoImport method needs to implemented when extending SimpleImportHandler.

Use cases

There are various operations in which importing and exporting can be helpful.

DMS assets transfer

You can import DMS assets into Magnolia using the context menu as well as Import and export tool.

You can also use the packager module for DMS assets transfer. The dms repository can be selected for populating a package. Assets can then be selected for inclusion in the package. The package containing the assets can be downloaded and uploaded to another Magnolia system for installation.

Site migration

You can accomplish site migration in a number of ways.

• For smaller sites (less than 300 pages), you can simply copy the page content and paste into the editor.
• For larger sites, scripting would be preferable to copying and pasting. The script examples export from one site and import to another. The script can also add Magnolia specific metadata such as whether a page should be visible in navigation.
• You can import content using XML files. The files must comply with the JCR System View XML Mapping format. If an XML file does not comply with this format then it needs to be translated first, which can be accomplished with a script. A script can identify content types in the file and transform them into format that can be imported into Magnolia.
• You can also import data from XML files. The Data module can import structured data within a XML file independent of page content. This allows for import of data such as addresses, employees and client references.
• You can also use the Packager module for site migration between Magnolia sites. The content of a site can be packaged into a package file which is then downloaded. The package file is uploaded to another site and installed on that site.

Backup

You can back up content by exporting it to XML or ZIP and storing the files in a disaster recovery system. The name of the file containing the XML reflects the path of the exported data making identification easier.

You can also use the Packager module for backups. The name of the downloaded package can be set to indicate the date of the backup or some other type of identification. The packages can be stored in a DR system.

The Backup module is an alternative to file system and database backup solutions. The module features immediate interactive backup of JackRabbit backed repositories and scheduled recurring backup support with cron like configuration options.

Importing a taxonomy

The recommended procedure for importing tags depends on the size and format of the taxonomy as well as whether the taxonomy needs to be added once or repeatedly. Depending on your need, you can import the tags into the existing Category data type or add a new data type.

If the taxonomy does not need to be added repeatedly you should enter the taxonomy manually in AdminCentral if the size and format is such that it can reasonably be manually entered.

Importing a taxonomy manually

To enter a taxonomy manually into the existing Category data type:

1. Add new branch to Data > Category page as described in   Creating data .
2. Add tags as subtypes. For instance, if adding tags for classifying movies you may want to add a Movies branch with a genre scheme as children.
   
   

If you prefer to create a new data type:

1. Create the new data type as described in Creating a type . The name should be the name of the taxonomy. Using the movies example, you may want the new data type to be Movies.
2. Refresh the page so you can see the new data type in the Data menu in AdminCentral.
3. Add tags as subtypes as described in Creating data . The added data could include movie genres.
   
   

If the taxonomy is too large to enter manually but needs to be entered only once then you should write a Groovy script to process a file containing the taxonomy.

Import large taxonomy once

Use a Groovy script to import a large taxonomy once:

1. Create a new data type for the taxonomy as described in Creating a type .
2. Write a Groovy script as described in Scripting. In this case the repository should be data instead of website and root the path of the parent data type such as /movies.
3. Execute the script in the   Groovy console .

Import large taxonomy repeatedly

Write an import handler to import a taxonomy repeatedly:

1. Create a new data type as described in Creating a type .
2. Write an import handler as described in Programmatically.
3. Register the import handler in /modules/data/config/importers with properties set to execute as needed.

Using the imported taxonomy

You can use the tags in an imported taxonomy to classify content once the import is completed. Keep in mind that the data type will not have functionality such as   Category Cloud that are available with the example Category data type. You can add such functionality by copy and customizing.

The new taxonomy can be used as options for some control types. For instance, you can use subtypes as options for radio, checkbox, and select controls by setting the path, repository, valueNodeData, and labelNodeData properties. For the movies example, repository would be set to data and path to /movies. Assuming that a name property is set for each movie category, you would set valueNodeData and labelNodeData to name.