Automatic Export Add-on

Introduction

Goal

Automatically export changes made in the development content repository to the bootstrap modules in your project.

Background

Experience has shown that one of the tricky tasks for a developer while working on a project is keeping track of the changes made to the local development repository and export those changes to the relevant files before commiting them to a version control system.

In order to help you with that task an add-on exists that can track the changes you make to the repository and which exports those changes automatically to your file system.

Getting Started 

Name your Content Module

To prevent name collisions between initialize items in your own content module and those defined in artifacts your project depends on, a  hippoecm-extension.xml file should declare an attribute on its root element that is used as a prefix for the initialize items generated by automatic export. If you created your project using the Hippo archetype, the hippoecm-extension.xml file in the content module already declares this ae:id attribute as the name of your project:

<sv:node xmlns:sv="http://www.jcp.org/jcr/sv/1.0"
         xmlns:ae="http://www.onehippo.org/jcr/autoexport/1.0"
         sv:name="hippo:initialize"
         ae:id="myhippoproject" />

Enable the Add-on

In order to enable automatic export you need to tell it where to find and store export files. This done by passing in the system property in the primary project pom.

<profile>
  <id>cargo.run</id>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <configuration>
          <snip/>
          <container>
            <systemProperties>
              <!-- enables auto export: -->
              <project.basedir>${project.basedir}</project.basedir>
            </systemProperties>
          </container>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>

The project.basedir system property must be set to the absolute path (starting with a /) of the root of your project. The easiest way to do this is by using the Maven property  project.basedir, as shown in the example above. In case of the archetype generated structure this property is already defined correctly in the primary pom. Now all you need to do is log into the console and press the "Enable auto export" button in the top menu.

Disabling Automatic Export from the Console

Sometimes you might want to add or remove nodes and properties from the repository for testing purposes or import some batch content only for local development, while you don't want these changes to be exported. In these cases you can disable export temporarily from updating your configuration from the console.

Configuration Options

The automatic export configuration is located at /hippo:configuration/hippo:modules/autoexport/hippo:moduleconfig in the repository. Log in to the CMS console and browse to that node. The below options are defined as properties on that node.

Exclusion Patterns

Instead of disabling and enabling automatic export from the console every time you need to, it may be more convenient to configure exclusion patterns for paths you never want to have exported. This is done using the multi-valued property autoexport:excluded. You need to specify wildcard patterns as the values of this property where * means any path element and ** means any path. Say for instance that you want to exclude all content below /foo/bar. You would then specify /foo/bar/** as your exclusion pattern. Often however, you not only want everything below a certain path but also the path itself. So to also exclude /foo/bar itself you would have to specify that explicitly as well by adding /foo/bar

Filtering out UUIDs

When nodes carry the mix:referenceable mixin, export would normally generate jcr:uuid property elements for those nodes. Because these uuids change whenever the node is redefined and because for some contexts uuids are not strictly needed this may lead to unnecessary scm conflicts. For this reason you may configure automatic export to filter out these jcr:uuid properties using the multi-valued property autoexport:filteruuidpaths. The values specified here are prefix patterns. So for instance /hst:hst would filter out jcr:uuid properties for all hst nodes.

Multiple Content Modules

Some projects require their content to be split up in multiple modules. Automatic export supports this via the multi-valued property autoexport:modules which accepts string values of the following format: mymodule:/repositorypath. Here mymodule is the file path relative to the project.basedir to the content module and /repositorypath is a path in the repository. Everything below /repositorypath, including /repositorypath itself will be exported to the module mymodule. The default configuration is content: /.

If you have multiple nested content submodules, then you can configure the nested submodule paths in the autoexport:modules property. For example, if you have two nested content submodules, bootstrap/configuration and bootstrap/content, then your configuration can be like the following example:

<sv:property sv:name="autoexport:modules" sv:type="String">
  <sv:value>bootstrap/content:/content</sv:value>
  <sv:value>bootstrap/configuration:/</sv:value>
</sv:property>

One typical use-case for multiple content modules is to have separate namespaces go into separate modules. In order to configure auto export for this add something like foocontent:/hippo:namespaces/foo to the autoexport:modules property. All document type definitions for that namespace, along with the cnd for that namespace as well as the namespace declaration itself will be exported to module foocontent.

Note that auto export will not move content and initialize items from one module to another when they already exist. When changes are made to such content and initialize items it will simply update the existing ones. It will only add new items to the configured module when these need to be created. If you want to move items you must do that manually and then restart the project.

Delta XMLs

Automatic export supports a subset of Delta XML instructions. Nodes can be combined, and properties can be overriden. Overlays and inserts are not supported. When appending to a multi-valued property, a property override is used instead of an append directive.

File Structure

Automatic export reads your project's files and updates these when something changes to the nodes serialized in these files. However, sometimes there is no appropriate file to write changes to and in this case automatic export creates a new file for you. In order to determine on what nodes to add a new file and where to put these files in the directory hierarchy of your content root directory it tries to follow a best-practices convention.

Limitations

Same-Name Siblings

Same-name siblings are not supported on certain levels in the repository. Specifically when the same-name sibling is defined as the document element of the content resource.

Node Reordering

Again only for those nodes that act as a content resource root, node reordering is not supported.

Sequence Numbers

Sequence numbers are used by the bootstrap system to determine the order in which to execute initialize items. Automatic Export attempts to generate sequence number high enough for the initialize items it depends on to be loaded. It cannot however determine the sequence numbers of initialize items outside its own content module. It could in rare cases therefor occur that the initialize item it creates has a sequence number that is too low. In these cases you will see the system log an error message for that initialize item when it is bootstrapped. Manually increasing the sequence number of that initialize item will then be necessary.