AEM Project Repository Structure Package

June 19, 2024

CREATED FOR:

  • Admin
  • Developer

Maven projects for Adobe Experience Manager as a Cloud Service require a repository structure subpackage definition whose sole purpose is to define the JCR repository roots into which the project’s code subpackages deploy. This method ensures the installation of packages in Experience Manager as a Cloud Service is automatically ordered by JCR resource dependencies. Missing dependencies may lead to scenarios where substructures would be installed ahead of their parent structures and therefore be unexpectedly removed, breaking the deployment.

If your code package deploys into a location not covered by the code package, then any ancestor resources (JCR resources closer to the JCR root) must be enumerated in the repository structure package. This process is necessary to establish these dependencies.

Repository Structure Package

The repository structure package defines the expected, common state of /apps which the package validator uses to determine areas “safe from potential conflicts” as they are standard roots.

The most typical paths to include in the repository structure package are:

  • /apps which is a system-provided node
  • /apps/cq/..., /apps/dam/..., /apps/wcm/..., and /apps/sling/... which provide common overlays for /libs.
  • /apps/settings which is the shared context-aware configuration root path

This subpackage does not have any content and is comprised solely of a pom.xml defining the filter roots.

Creating the Repository Structure Package

To create a repository structure package for your Maven project, create an empty Maven subproject, with the following pom.xml, updating the project metadata to conform with your parent Maven project.

Update the <filters> to include all the JCR repository path roots your code packages deploy into.

Make sure to add this new Maven subproject to the parent projects <modules> list.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- ====================================================================== -->
    <!-- P A R E N T  P R O J E C T  D E S C R I P T I O N                      -->
    <!-- ====================================================================== -->
    <parent>
        <groupId>com.my-company</groupId>
        <artifactId>my-app</artifactId>
        <version>x.x.x</version>
        <relativePath>../pom.xml</relativePath>
    </parent>

    <!-- ====================================================================== -->
    <!-- P R O J E C T  D E S C R I P T I O N                                   -->
    <!-- ====================================================================== -->
    <artifactId>ui.apps.structure</artifactId>
    <packaging>content-package</packaging>
    <name>UI Apps Structure - Repository Structure Package for /apps</name>

    <description>
        Empty package that defines the structure of the Adobe Experience Manager repository the code packages in this project deploy into.
        Any roots in the code packages of this project should have their parent enumerated in the filters list below.
    </description>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.jackrabbit</groupId>
                <artifactId>filevault-package-maven-plugin</artifactId>
                <extensions>true</extensions>
                <properties>
                    <!-- Set Cloud Manager Target to none, else this package is deployed and remove all defined filter roots -->
                    <cloudManagerTarget>none</cloudManagerTarget>
                </properties>
                <configuration>
                    <properties>
                        <!-- Set Cloud Manager Target to none, else this package is deployed and remove all defined filter roots -->
                        <cloudManagerTarget>none</cloudManagerTarget>
                    </properties>
                    <filters>

                        <!-- /apps root -->
                        <filter><root>/apps</root></filter>

                        <!--
                        Examples of complex roots


                        Overlays of /libs typically require defining the overlay structure, at each level here.

                        For example, adding a new section to the main AEM Tools navigation, necessitates the following rules:

                        <filter><root>/apps/cq</root></filter>
                        <filter><root>/apps/cq/core</root></filter>
                        <filter><root>/apps/cq/core/content</root></filter>
                        <filter><root>/apps/cq/core/content/nav/</root></filter>
                        <filter><root>/apps/cq/core/content/nav/tools</root></filter>


                        Any /apps level Context-aware configurations need to enumerated here.

                        For example, providing email templates under `/apps/settings/notification-templates/com.day.cq.replication` necessitates the following rules:

                        <filter><root>/apps/settings</root></filter>
                        <filter><root>/apps/settings/notification-templates</root></filter>
                        <filter><root>/apps/settings/notification-templates/com.day.cq.replication</root></filter>
                        -->

                    </filters>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>