30. Juni 2022
Our AEM Easy Content Upgrade (AECU) tool provides an easy solution for content migrations since many years. But more and more Adobe AEM customers switch to the AEM cloud offering. While automated content migrations via AECU are possible for self-hosted and AMS-hosted AEM installations, AEM as a Cloud Service (AaaCS) was lacking this feature for some time. This is now possible using the new AECU startup hook for AaaCS.
What are typical content migrations?
Content migration means that you need to do adjustments to your production content. This is required when you want to deploy a new software release that is partially incompatible with your existing content. Typical migration tasks are:
- Change resource types because components were split/merged or renamed
- Move nodes/attributes to a different place caused by a component refactoring
- Set default settings based on location in content tree (e.g. tenant specific)
- Fix content issues
Why is AaaCS special regarding content migrations?
AaaCS comes with a completely new deployment model. Instead of just deploying a few packages the setup is far more sophisticated. Application code is deployed in a first step when the AEM software images are built. This part of the repository (/apps and /libs) cannot be changed at runtime. AaaCS runs in a cluster environment with multiple instances using a shared repository. Therefore, there is no more one-to-one relation of AEM instance to repository. Content changes by one instance are affecting the others, too. Instances might be added and removed at any time based on load. During a deployment the instances with old and new code access the same content repository. Install hooks for packages run with a non-privileged user which makes it impossible to use the traditional install hook mechanism for AECU.
This all brings extra complexity and resulted in a new mechanism to run AECU scripts.
How to specify AECU scripts on AaaCS?
The new AECU startup hook is executed whenever an AEM instance is started. This happens during deployments and cluster resizings. No configuration is needed. The only change for you is that the hook uses a special base folder to search for migration scripts.
Please put all your files under “/apps/aecu-scripts”. Scripts in other places will be ignored for the automatic execution. Of course, you can manage the scripts in subfolders. Also, run modes in folder names are supported like “project1.author”. Please keep in mind that AaaCS has a limited set of run modes. Only “dev”, “stage” and “prod” are available.
The startup hook is only executed on Adobe-hosted environments. For local development with Cloud SDK you can still use the traditional install hook. Please make sure that the install hook is only added on local deployments. See our “examples-cloud” package for an example to control this in pom.xml via Maven profile.
Limitations of AaaCS
During a deployment the old AND new code must be compatible with the old AND new (migrated) content. This is a general requirement of AaaCS due to the cluster nature.
Since the scripts are executed when an instance is started, they might be executed multiple times. On the one hand, this can happen at deployment time where instances startup one after the other. E.g. one instance is executing the scripts when another one comes up. This new instance would then start with the script that the first instance is currently executing.
On the other hand, this can happen at random times when the cluster is resized because of load. During deployment this can affect any script. A cluster resizing will only call the “always” scripts.
Please make sure your scripts are compatible to run multiple times.
The traditional install hook checks if a script was modified and runs it again in that case. This is not supported for the startup hook. Modified scripts need to be renamed to run again.
Scripts will not be executed during image build phase. Therefore, changes to /apps and /libs are not supported.
Where can I get it?
Please see our GitHub page to download the latest release. You can also find AECU on Maven Central for embedding it in your container package.
You will find all the documentation on GitHub. That also includes more advanced features like rights and role testing.