Automatic Export Add-on

Overview

The Automatic Export add-on exports changes from the development content repository to your project's repository data modules. This process helps ensure that repository changes are consistently reflected in version-controlled files.

Purpose

Automatic export tracks modifications in your local development repository and writes these changes to the appropriate files in your project. This reduces manual effort and helps maintain synchronization between the repository and your source files.

Enabling Automatic Export

To enable automatic export, configure two Java system properties when starting the CMS. These properties define where export files are located and stored.

Note: If you use the archetype-generated project structure, the cargo.run Maven profile already sets these properties. No further action is required to enable automatic export in this case.

The project.basedir property is defined in the main project POM:

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

Set project.basedir to the absolute path of your project's root directory. Using the Maven property ${project.basedir} is recommended. The repo.autoexport.allowed property must also be set to true. This is the default in the hippo-cms-project POM, which your project POM inherits.

When you run the CMS project with the cargo.run profile, automatic export is enabled by default. You can also enable or disable automatic export from the Console using the Disable/Enable auto export button in the top menu.

Automatic export reads and updates files in your project's src/main/resources directory for any module with automatic export enabled. If no suitable file exists for a change, automatic export creates a new file following best-practice conventions for file placement.

Important: Do not use Maven filtering or build-time text substitution for files managed by automatic export. If you need to use such techniques, disable automatic export for the relevant module as described below.

Recommended Module Structure

For best results, organize repository data in multiple Maven modules. The default archetype for Bloomreach Content creates five modules:

repository-data/application
repository-data/development
repository-data/site
repository-data/site-development
repository-data/webfiles

The development and site-development modules are for data files used in development and testing environments. Production deployments should use only the application and site modules. The without-development-data Maven profile can be used with cargo.run to exclude development data locally. The dist-with-development-data module supports deploying development data to remote testing environments.

The webfiles module is typically updated directly on the filesystem, not via automatic export. For more information, see Using Web Files.

Module Dependency Restrictions

Automatic export requires that all downstream modules (modules loaded or ordered after the current one) that contain config, content, or namespace definitions are also configured for auto export. Modules containing only webfilebundle definitions are exempt.

If your project includes additional modules that are not explicitly dependent on others, module order is determined lexically by name. This can affect projects with multiple independent modules.

To resolve ordering issues:

Configure all relevant modules for auto export, if appropriate (do not enable for webfiles modules unless required).
Ensure the application module is ordered after any module not being exported. Use the hcm-module.yaml file to specify ordering, as shown below:

group: 
  name: myproject
  after: hippo-cms
project: myproject
module:
  name: repository-data-application
  after: repository-data-other-team

Disabling Automatic Export Temporarily

You may need to disable automatic export when making temporary changes or importing batch content for local development. Use the Console to disable export as needed.

Note: When you re-enable automatic export, any nodes changed while export was disabled will be exported. To prevent specific nodes from being exported, remove them from the repository before re-enabling export, or configure exclusions using .meta:category: runtime, content declarations, or the autoexport:excluded property (see below).

Configuration Options

Automatic export configuration is stored at /hippo:configuration/hippo:modules/autoexport/hippo:moduleconfig in the repository. Access this node in the Console to view or modify settings.

Important: Restart the CMS after changing automatic export configuration for changes to take effect.

Exclusion Patterns

To prevent certain paths from being exported, use the multi-valued autoexport:excluded property. Specify wildcard patterns:

* matches any single path element
** matches any path

For example, to exclude all content under /foo/bar, use /foo/bar/**. To exclude /foo/bar itself, add /foo/bar as a separate pattern.

Overriding `.meta:residual-child-node-category`

During local development, you may need to override the .meta:residual-child-node-category for specific nodes. Use the multi-valued autoexport:overrideresidualchildnodecategory property with entries in the format <path>: <category>, where <category> is config, content, or system. Wildcards are supported in paths.

For example, the default for /hst:hst/hst:configurations is content, but during local development, it is often preferable to classify new channels as config. The override /hst:hst/hst:configurations: config is included by default.

Injecting `.meta:residual-child-node-category`

To automatically transition from config to content at certain paths during import or tree copy operations, use the autoexport:injectresidualchildnodecategory property. Entries follow the format <path>: <category>. Paths can end with [<primarytype>] to match nodes of a specific primary type.

When a path matches, the node is exported as config with an added .meta:residual-child-node-category for the specified category. Child nodes are exported as content or ignored if the category is system.

A default example is **/hst:workspace/**[hst:containercomponent]: content, which serializes new componentcontaineritems in the HST workspace as content.

Filtering UUIDs

Nodes with the mix:referenceable mixin generate jcr:uuid properties on export. These UUIDs change when nodes are redefined, which can cause unnecessary source control conflicts. Use the autoexport:filteruuidpaths property to filter out jcr:uuid properties. Specify wildcard patterns such as /hst:*/** to filter UUIDs for all hst:hst type nodes.

Configuring AutoExport Modules

Projects often split content and configuration across multiple modules. The autoexport:modules property defines mappings in the format mymodule:/repositorypath, where mymodule is the module's path relative to project.basedir and /repositorypath is the repository path to export.

You can also specify just mymodule to update existing definitions in that module without creating new ones. This is useful for test data that is manually moved to a development module.

To export separate namespaces to different modules, add entries like foocontent:/hippo:namespaces/foo to autoexport:modules. This exports all document type definitions and namespace definitions for foo to the foocontent module.

Note: Auto export does not move existing definitions between modules. It updates existing items in their current location and adds new items only to the configured module. To move items, do so manually and restart the project.

The default configuration provided by the archetype is:

/hippo:configuration/hippo:modules/autoexport:
  /hippo:moduleconfig:
    autoexport:modules: ['repository-data/application:/', repository-data/development,
      'repository-data/site:myproject:/hst:myproject','repository-data/site:myproject']

A mapping for the root repository path / is required. Restart the CMS after changing module configuration.

Autoexport Overrides for Groups, Roles, Userroles, and Authroles

By default, adding or modifying groups, roles, and userroles at runtime is treated as system category. In development mode with auto export enabled, these are exported as config to your project's YAML bootstrap configuration. This is important when managing feature userroles for custom groups.

The following entries are included in autoexport:overrideresidualchildnodecategory:

autoexport:overrideresidualchildnodecategory: ["/hippo:configuration/hippo:groups: config",
                                               "/hippo:configuration/hippo:roles: config",
                                               "/hippo:configuration/hippo:userroles: config"]

This ensures groups, roles, and userroles are exported.

If you use an external security provider (such as LDAP) in local development, remove or override these settings for groups, or add exclusions to prevent exporting sensitive properties like hipposys:members.

Properties such as hipposys:members, hipposys:groups, hipposys:userroles, and hipposys:users are always exported as .meta:category: system with .meta:add-new-values: true. For details, see System Properties with Initial Value(s).

File Structure

Automatic export updates files in your project when changes are made to serialized nodes. If no suitable file exists, automatic export creates a new file following best-practice conventions for node and directory placement.

Limitations

Content Roots with Same-Name Siblings

Automatic export may fail or produce invalid YAML when content roots have same-name siblings at the top three levels below /content (such as document or gallery folders). Avoid using same-name siblings in these contexts. In general, avoid same-name siblings for forward compatibility.

Content Root Ordering

Automatic export does not always preserve the correct ordering of content root nodes, especially with overlapping content definitions (e.g., one definition for /content/documents/myproject/news and another for /content/documents/myproject/news/2017/10) or when definitions are contributed by upstream modules. Manual editing of YAML files may be required to achieve the desired node order.

Local Resource Files Not Deleted

Binary resources in the repository are referenced in YAML by jcr:data elements pointing to resource files:

jcr:data:
  type: binary
  resource: /content/gallery/myproject/myimage/myimage_original.jpg

If a binary resource is deleted from the repository, the YAML file is updated, but the referenced file on disk is not removed. Delete these files manually to prevent unused files from accumulating in your project sources.