Page Comparison

...

Replace the user names accordingly. If you have created more system users or more “initialization” packages like this, convert them to repoinit as well. Additional benefit: this repoinit syntax us much more compact and better readable.

Step 9:

...

The Project Structure documentation of AEM Cloud Service explains the new requirements for content packages (immutable and mutable, that means application packages and config/sample content packages).

If you’ve not done it already, make sure you have switched all your content package projects to the Apache Jackrabbit FileVault Package Maven Plugin (see migration guide).

The latest wcm.io aem-global-parent also includes the latest version of the FileVault Package Maven Plugin which has built-in additional validation steps, you may have to adapt your packages, see this guide .

Check/adapt all your content package module POMs:

...

Make sure the appropriate packageType property is set for each content package. “application” and “container” are immutable content packages, “content” are mutable content packages. It’s not allowed to use the “mixed” type. Example:

Code Block

language	xml

<packageType>content</packageType>

...

If you have packages that mix immutable and mutable content (the validation rules of the FileVault Package Maven Plugin will tell you that), you have to split up your packages.

...

Remove longCacheKey definitions

It’s not longer required to set longCacheKey properties for client libraries - this feature is enabled by default in AEM Cloud Service generating a hash based on the content of the client library.

Please note that this is only the case in the cloud environment, not when using the local quickstart JAR of AEM Cloud SDK. If you want to activate the feature for the local AEM instance as well, set the “Long term client side cache key” in the “Adobe Granite HTML Library Manager” OSGi configuration to /.*;hash.

Step 10: Make content package modules compatible with AEM Cloud

The Project Structure documentation of AEM Cloud Service explains the new requirements for content packages (immutable and mutable, that means application packages and config/sample content packages).

If you’ve not done it already, make sure you have switched all your content package projects to the Apache Jackrabbit FileVault Package Maven Plugin (see migration guide).

The latest wcm.io aem-global-parent also includes the latest version of the FileVault Package Maven Plugin which has built-in additional validation steps, you may have to adapt your packages, see this guide .

Check/adapt all your content package module POMs:

Make sure the appropriate packageType property is set for each content package. “application” and “container” are immutable content packages, “content” are mutable content packages. It’s not allowed to use the “mixed” type. Example:
It is recommended (but not mandatory) to create a “repository structure” package module that defines all application folders that are already present OOTB in AEM Cloud Service and which should not fail the validation of the other packages if application content is deployed to them. In the Adobe documentation this module is referenced as repository-structure, in the latest Adobe AEM project archetypes it’s named ui.apps.structure.
For CONGA-bases projects the recommendation is to create it at
Code Block
content-packages/apps-repository-structure/pom.xml

Example package definition (full example):

Code Block

language	xml

<plugin> <groupId>org.apache.jackrabbit</groupId> <artifactId>filevault-package-maven-plugin</artifactId> <extensions>true</extensions>

Code Block

language	xml

<!-- Do not deploy directly via AEM cloud manager, only as part of CONGA-generated "all" package -->
<properties>
  <cloudManagerTarget>none</cloudManagerTarget>
</properties>

You do not have to declare dependencies between your packages. This is done by CONGA automatically based on the order of the files defined in the CONGA role.
<packageType>content</packageType>
If you have packages that mix immutable and mutable content (the validation rules of the FileVault Package Maven Plugin will tell you that), you have to split up your packages.
Make sure that all packages have a new package property cloudManagerTarget set to none. This instructs the Cloud Manager to ignore this package - it will be handed over to the Cloud Manager as part of an “all” package generated by CONGA in a later step. Example:
Code Block
language xml
 <properties> <cloudManagerTarget>none</cloudManagerTarget> </properties>
You do not have to declare dependencies between your packages. This is done by CONGA automatically based on the order of the files defined in the CONGA role.

It is recommended (but not mandatory) to create a “repository structure” package module that defines all application folders that are already present OOTB in AEM Cloud Service and which should not fail the validation of the other packages if application content is deployed to them. In the Adobe documentation this module is referenced as repository-structure, in the latest Adobe AEM project archetypes it’s named ui.apps.structure.

For CONGA-bases projects the recommendation is to create it at
Code Block
content-packages/apps-repository-structure/pom.xml

Example package definition (full example):

Code Block

language	xml

<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>

    <!-- Do not deploy directly via AEM cloud manager, only as part of CONGA-generated "all" package -->
    <properties>
      <cloudManagerTarget>none</cloudManagerTarget>
    </properties>

    <filters>

      <!-- /apps root -->
      <filter><root>/apps</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>

    </filters>
  </configuration>
</plugin>

Once this is defined it can be referenced from the other content package modules containing immutable application content of the project. Example:

Code Block

language	xml

<dependencies>
  <dependency>
    <groupId>YOUR_GROUP_ID</groupId>
    <artifactId>YOUR_GROUP_ID.apps-repository-structure</artifactId>
    <version>YOUR_VERSION</version>
    <type>zip</type>
    <scope>provided</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        ...
        <repositoryStructurePackages>
          <repositoryStructurePackage>
            <groupId>YOUR_GROUP_ID</groupId>
            <artifactId>YOUR_GROUP_ID.apps-repository-structure</artifactId>
          </repositoryStructurePackage>
        </repositoryStructurePackages>      
      </configuration>
    </plugin>
  </plugins>
</build>

Make sure this package gets never deployed to any AEM instance! It’s only a tool for supporting the package validation during build time.

Step

...

11: Make CONGA-generated content packages compatible with AEM Cloud

Check the CONGA roles defined at config-definition/src/main/roles if you have custom packages defined using JSON templates and the aem-contentpackage post processor:

...

This applies not to OSGi configuration packages generated with the aem-contentpackage-osgiconfig post processor - they are automatically generated as immutable container packages.

Step

...

12: Add new CONGA Environments for AEM Cloud

The way recommended by Adobe is to put the AEM application code directly in the GIT repository provided by the Cloud Manager. In this case no separate “configuration-management” GIT repository is used, so we need to define additional CONGA Environments for the dev and stage/prod environments in the Cloud directly in the application GIT repository at config-definition/src/main/dev-environments:

...

Info
It is also possible to put only the “configuration-management” GIT repository in the Cloud Manager GIT, define only the environments there and build the AEM application artifacts outside the Cloud Manager. This setup is not covered by this article.

Step

...

13: Build “all” and “dispatcher config” packages for Cloud Manager

Add two new plugin executions to the POM at config-definition/pom.xml:

...

This will generate the ZIP files that will be picked up by Adobe Cloud Manager to deploy the content packages and dispatcher configuration to AEM Cloud Service.

Step

...

14 - Workarounds for Issues

Note
This section lists workarounds for issues that are currently present in AEM Cloud 2020.4. They may be fixed in more recent releases and no longer required.

Define additional maven repositories

AEM Cloud Manager does not know the maven repository to load the AEM SDK API from. Also against Maven best practices, add the following repository definition to the Parent POM:

Code Block

language	xml

<repositories> <repository> <id>adobe-aem-releases</id> <name>Adobe AEM Repository</name> <url>https://downloads.experiencecloud.adobe.com/content/maven/public/</url> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories>

fixed in more recent releases and no longer required.

Do not configure Sling Log Manager

...

If you find such a configuration, remove it completely. It will fail the image build in Adobe Cloud Manager.

Disable longCacheKey for client libraries

AEM Client Libraries that use URL fingerprinting via the longCacheKey property currently do not work in AEM Cloud Service. You have to remove this property and use the client libraries without URL fingerprinting for the time being.

Last Remarks

Use a Sandbox in AEM Cloud to test your migrated project thoroughly. Do not deploy to a stage/prod environment before all is running as expected on a dev environment (it’s easy to delete a dev environment and start from scratch).

...

Versions Compared

Old Version 3

New Version 4

Key

Step 9:

Remove longCacheKey definitions

Step 10: Make content package modules compatible with AEM Cloud

Step

11: Make CONGA-generated content packages compatible with AEM Cloud

Step

12: Add new CONGA Environments for AEM Cloud

Step

13: Build “all” and “dispatcher config” packages for Cloud Manager

Step

14 - Workarounds for Issues

Define additional maven repositories

Do not configure Sling Log Manager

Disable longCacheKey for client libraries

Last Remarks