Skip to content
Ordolith
All writing

Adobe Experience Manager

The Blueprint for AEM Repository Organization: ‘ui.apps.structure’ Explained

What the ui.apps.structure package does, and how to use it to deploy your own code into an AEM repository without overwriting someone else’s.

Asif Ahmed ChowdhuryFirst published on Medium

Details of ui.apps.structure in an AEM project

ui.apps.structure in an Adobe Experience Manager (AEM) project is an important module that defines the structure of the AEM repository where code packages are deployed. Here are some details about it:

Definition
ui.apps.structure is an empty package within the AEM project that serves as a blueprint for the expected structure of the AEM repository.
Purpose
This package doesn’t contain actual code or assets. Instead, it defines how the AEM repository should be organized to accommodate the code packages deployed in the project.
Safety
The package is used by the package validator to ensure that the structure of the AEM repository conforms to the project’s expectations. It helps ensure that code is deployed safely without conflicting with other components in the repository.
Composition
While it’s often empty, it can contain configurations, definitions, and structural details to guide the deployment of code.
Dependence
Other packages and code in the project rely on ui.apps.structure to determine the areas within the AEM repository that are “safe from conflicts.” This ensures that deployments are deterministic and non-conflicting.
Customization
The structure can be customized to suit the specific needs of the AEM project, but it should always be aligned with the project’s expectations and the safety requirements of the AEM platform.

This structural package is crucial for maintaining order and predictability within the AEM repository, allowing different parts of the project to coexist harmoniously and preventing unintended conflicts during deployment.

Problem statement

Suppose we have to develop widgets (widget-x, widget-y) in project-x. For example:

The ui.apps module tree: project-x holds clientlibs, components and a widgets folder with widget-x and widget-y, beside project-y.

But another vendor may already have developed some widgets in this project. So if we just write filter rules like this:

<?xml version="1.0" encoding="UTF-8"?>
<workspaceFilter version="1.0">
    <filter root="/apps/project-x/clientlibs"/>
    <filter root="/apps/project-x/components"/>
    <filter root="/apps/project-x/widgets"/>
</workspaceFilter>

it is not going to work. This will just replace the existing widgets package and install the new one. We can add mode="merge" to the filter rules, but this isn’t ideal, because the new package’s primary type may not be exactly the same as the previous one.

We don’t want to touch the existing widgets’ properties.

Solution

The ideal approach is to introduce a new module called ui.apps.structure.

The ui.apps.structure module: a src/main/content folder and a pom.xml.

The POM file

The pom.xml file will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://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.adobe.aem.tutorial</groupId>
        <artifactId>aem-tutorial</artifactId>
        <version>1.0.0-SNAPSHOT</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>aem-tutorial.ui.apps.structure</artifactId>
    <packaging>content-package</packaging>
    <name>AEM Tutorial - Repository Structure Package</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>
                <configuration>
                    <properties>
                        <cloudManagerTarget>none</cloudManagerTarget>
                    </properties>
                    <filters>
                        <!-- /apps root -->
                        <filter><root>/apps</root></filter>
                        <filter><root>/apps/project-x</root></filter>
                        <filter><root>/apps/project-x/widgets</root></filter>
                        <!-- Common overlay roots -->
                        <filter><root>/apps/sling</root></filter>
                        <filter><root>/apps/cq</root></filter>
                        <filter><root>/apps/dam</root></filter>
                        <filter><root>/apps/wcm</root></filter>
                        <filter><root>/apps/msm</root></filter>

                        <!-- Immutable context-aware configurations -->
                        <filter><root>/apps/settings</root></filter>

                        <!-- DAM folder root, will be created via repoinit -->
                        <filter><root>/content/dam/project-x</root></filter>

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

Here we have declared that the root of the widgets will be:

<filter><root>/apps/project-x/widgets</root></filter>

It won’t touch anything up to the widgets folder in the repository.

Then we need to update the filter in ui.apps as well. The ui.apps filter will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<workspaceFilter version="1.0">
    <filter root="/apps/project-x/clientlibs"/>
    <filter root="/apps/project-x/components"/>
    <filter root="/apps/project-x/widgets/widget-x"/>
    <filter root="/apps/project-x/widgets/widget-y"/>
</workspaceFilter>

The filter rules for the widgets become:

<filter root="/apps/project-x/widgets/widget-x"/>
<filter root="/apps/project-x/widgets/widget-y"/>

This way our project won’t touch the existing package. It will only install widget-x and widget-y, and everything that already exists stays as it is.

Adding the module

If this module isn’t generated automatically, we need to add it manually. After adding the package to the project, we need to add it to the POM files as well, so that it works as a module.

Main POM

Add it to the <modules> section as a module, for example <module>ui.apps.structure</module>:

<modules>
  <module>all</module>
  <module>core</module>
  <module>ui.frontend</module>
  <module>ui.apps</module>
  <module>ui.apps.structure</module>
  <module>ui.config</module>
  <module>ui.content</module>
  <module>it.tests</module>
  <module>dispatcher</module>
  <module>ui.tests</module>
</modules>

The ui.apps POM

In the ui.apps POM, add it in two sections. First, in the plugin section, as a repositoryStructurePackage:

<!-- ====================================================================== -->
<!-- V A U L T   P A C K A G E   P L U G I N S                              -->
<!-- ====================================================================== -->
<plugin>
    <groupId>org.apache.jackrabbit</groupId>
    <artifactId>filevault-package-maven-plugin</artifactId>
    <configuration>
        <properties>
            <cloudManagerTarget>none</cloudManagerTarget>
        </properties>
        <group>com.adobe.aem.tutorial</group>
        <name>aem-tutorial.ui.apps</name>
        <packageType>application</packageType>
        <repositoryStructurePackages>
            <repositoryStructurePackage>
                <groupId>com.adobe.aem.tutorial</groupId>
                <artifactId>aem-tutorial.ui.apps.structure</artifactId>
            </repositoryStructurePackage>
        </repositoryStructurePackages>
        <dependencies>
            <dependency>
                <groupId>com.adobe.cq</groupId>
                <artifactId>core.wcm.components.content</artifactId>
            </dependency>
            <dependency>
                <groupId>com.adobe.cq</groupId>
                <artifactId>core.wcm.components.config</artifactId>
            </dependency>
        </dependencies>
    </configuration>
</plugin>

Then in the dependency section, as a dependency:

<dependency>
    <groupId>com.adobe.aem.tutorial</groupId>
    <artifactId>aem-tutorial.ui.apps.structure</artifactId>
    <version>${project.version}</version>
    <type>zip</type>
</dependency>

The ui.config POM

If the project has a ui.config module, add it there too, again in two sections. First, in the plugin section, as a repositoryStructurePackage:

<build>
    <sourceDirectory>src/main/content/jcr_root</sourceDirectory>

    <plugins>
        <plugin>
            <groupId>org.apache.jackrabbit</groupId>
            <artifactId>filevault-package-maven-plugin</artifactId>
            <configuration>
                <properties>
                    <cloudManagerTarget>none</cloudManagerTarget>
                </properties>
                <packageType>container</packageType>
                <showImportPackageReport>false</showImportPackageReport>
                <repositoryStructurePackages>
                    <repositoryStructurePackage>
                        <groupId>com.adobe.aem.tutorial</groupId>
                        <artifactId>aem-tutorial.ui.apps.structure</artifactId>
                    </repositoryStructurePackage>
                </repositoryStructurePackages>
            </configuration>
        </plugin>
        <plugin>
            <groupId>com.day.jcr.vault</groupId>
            <artifactId>content-package-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Then in the dependency section, as a dependency:

<dependencies>
    <dependency>
        <groupId>com.adobe.aem.tutorial</groupId>
        <artifactId>aem-tutorial.ui.apps.structure</artifactId>
        <version>${project.version}</version>
        <type>zip</type>
    </dependency>
</dependencies>

With the module added to the project, we can take advantage of it.

This example is only a demonstration. The same module helps with much bigger challenges: for example, custom tools that need to overlay nodes from /libs to /apps.

Start with one conversation

Tell us what you need built, connected or looked after, and we'll reply with how we'd approach it.

  • Fixed scope, agreed up front

    You approve what's built and what it costs before work starts.

  • You own what we build

    Source code and documentation are handed over at launch.

  • Working across time zones

    We work with clients worldwide and keep regular overlap with your business hours.

  • Support after launch

    Optional ongoing support, agreed separately.