Enhanced XML Import

Overview

Enhanced XML Import in Bloomreach Content extends the standard JCR System View XML format. These enhancements support advanced import scenarios, such as merging imported content with existing repository nodes and importing property values from external files.

When to Use

Use Enhanced XML Import when you need to:

Merge new content into existing nodes without overwriting all data.
Insert nodes at specific positions among siblings.
Import property values from external files.
Append or override property values during import.
Reference other nodes without hard-coding UUIDs.

Background

The Console allows you to import content using an enhanced version of the JCR System View XML format. System View XML is defined in the [JCR specification](http://www.day.com/specs/jcr/2.0/7_Export.html#7.2 System View) and provides a way to serialize and deserialize any JCR content.

Bloomreach Content extends this format by introducing additional semantics. These enhancements enable merging, selective property updates, and referencing external files during import.

Note: Enhanced System View XML files that include directives for modifying existing nodes are sometimes called "Delta XML" files.

Example Enhanced System View XML

The following example demonstrates several enhanced XML directives:

<?xml version="1.0" encoding="UTF-8"?>
<sv:node xmlns:sv="http://www.jcp.org/jcr/sv/1.0" xmlns:esv="http://www.onehippo.org/jcr/xmlimport"
    sv:name="foo" esv:merge="combine">
  <sv:node sv:name="bar" esv:merge="combine">
    <sv:property sv:name="property1" sv:type="String">
      <sv:value>value1</sv:value>
    </sv:property>
    <sv:property sv:name="property2" sv:type="String" esv:merge="append">
      <sv:value>value_x</sv:value>
      <sv:value>value_y</sv:value>
    </sv:property>
    <sv:node sv:name="baz" esv:merge="insert" esv:location="qux">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>myns:mytype</sv:value>
      </sv:property>
      <sv:property sv:name="myns:myproperty" sv:type="String">
        <sv:value esv:file="/path/to/file.txt" />
      </sv:property>
    </sv:node>
  </sv:node>
</sv:node>

Enhanced XML Directives

xmlimport Namespace

To use enhanced directives, declare the enhancement namespace on the root <sv:node> element:

Always include xmlns:sv="http://www.jcp.org/jcr/sv/1.0".
Add xmlns:esv="http://www.onehippo.org/jcr/xmlimport" to enable enhanced attributes.

This namespace allows the use of esv:merge and esv:location attributes on sv:node elements.

Merging Nodes

To merge imported content into an existing node, set esv:merge="combine" on the relevant sv:node. This instructs the importer to:

Use the existing node as the base.
Add properties and child nodes from the import.
Attempt to merge child nodes with esv:merge="combine" recursively.

You cannot change the primary type with combine. If the node does not exist, a standard import occurs. For merging, you may omit jcr:primaryType and jcr:mixinTypes properties.

Changing Primary Node Type or Mixins

To change the primary node type or mixins of an existing node, use esv:merge="overlay". This directive allows you to:

Merge content as with combine.
Change the node's primary and mixin types.

Inserting Nodes at a Specific Location

By default, imported nodes are added as the last child of their parent. To insert a node at a specific position among siblings, use:

esv:merge="insert" on the sv:node.
esv:location to specify the sibling node before which to insert.

For same-name siblings, append an index in brackets to the node name.

Skipping Import for Existing Nodes

To skip importing a node and all its descendants if the node already exists, set esv:merge="skip" on the node.

Appending Values to Multi-Value Properties

To add values to an existing multi-value property, set esv:merge="append" on the property.

Overriding Properties

When merging or overlaying nodes, imported properties without an esv:merge directive will overwrite existing properties, generating a warning. To explicitly override a property and avoid warnings, set esv:merge="override" on the property.

Importing Property Values from External Files

To import string or binary property values from an external file, add esv:file to the <sv:value> element. The attribute value must be a path relative to the root of the containing JAR file (leading slash is optional).

Additional Features

Setting a Reference Property by Path

To reference another node without hard-coding its UUID:

Define a String property with ___pathreference appended to its name.
Set the property value to the absolute JCR path of the target node.

Example:

<sv:property sv:name="hippo:related___pathreference" sv:type="String">
    <sv:value>/content/documents/myproject/events/2016/07/workshop</sv:value>
</sv:property>

On import, Bloomreach Content resolves the path and stores the property as a proper Reference. The referenced node must be imported before the reference for resolution to succeed.

Note: When exporting a node with a Reference property using the Console, the property is automatically converted to a String property with the ___pathreference suffix, as shown above.