The Ins and Outs of Code Package Deployments in AEM

This page documents what to include in and what to leave out of Adobe Experience Manager code packages based on past experience. The contents of a code package can be configured in the file src/main/content/META-INF/vault/filter.xml. This file tells the AEM Package Manager which repository paths are included in the package and what to do with them at deployment time.

There are three supported import modes for the Package Manager:

  1. replace: Normal behavior. Existing content is replaced completely by the imported content, i.e., is overridden or deleted accordingly.
  2. merge: Existing content is not modified, i.e., only new content is added and none is deleted or modified.
  3. update: Existing content is only updated but never deleted.

Possible things to include

In case you wish to disable the “Target” context menu item on all components because clicking on it “breaks” the content component involved, then you are required to overlay this file and add line “config.disableTargeting = true;” to function addTargetingActions: function(items, ctrlDef, isTargeted, config).

In case you want to implement a custom 404 page, as described in Customizing errorhandler pages, it is normally located at “/apps/sling/servlet/errorhandler/404.jsp”.

Part that contains the custom code you are running. This should always be in your code package.

By including this node in your code package, you can deploy Dispatcher Flush pages (previously created on a development environment) to all other Adobe Experience Manager (DTAP) environments.

This node contains the active contextstores available to your site.

Here you list the folders that are used by your site’s front-end design.

Possible subfolders to include could be:

  • clientlibs: client libraries used by your site
  • frontend: this folder should always be included in your code package. It should contain an info.html file has a link to the front-end design used on your site. The front-end design itself is hosted on a dedicated front-end server that contains the static html.
  • icons
  • images

Here you can store any mail templates used by custom workflows.

Node containing custom workflow to allow for storing the content entered by the customer and also send it as an email to a specified email address.

Customization of DAM Update Asset workflow (to generate a custom rendition).

Things to exclude

Only add this to your code package in the initial (go-live) release!
In the repository you will find a jcr:content node right under /etc/designs/, which contains content information like the URL to the logo image, settings of which components are allowed in which paragraphs on which templates, which (custom) clientcontext to use, etc… Should you include this repository path in your code package, this means that everything under this level will be overwritten with the content from your package (info not in the package is deleted on the server!).

Of course this is the desired behavior in case you are deploying design changes to the AEM server, but you will lose all the above mentioned information in the process. And as this is all content that can be configured by content authors; you should not store it in source code management and deploy with your package as this content can change over time, even between code releases.

So this is why you should place all front-end design related files in subfolders, allowing you to include these in the code package and avoid deploying to the root level of your design on the Adobe Experience Manager server. (You can’t fix this by adding import mode “merge” to the filter pointing to the root path of your design, as this would mean that only new files are added and existing design files are never deleted NOR MODIFIED.)

However, you do need to make sure the root of the design gets deployed at least once—otherwise the jcr:content node at the root of the /etc/designs/ folder might not be created, and it is under there that all design settings are stored.

This repository node contains all the tags that are created on the AEM server. As these can be created by content authors and used on pages, assets, etc.,you don’t want to have this information in your code package. This tends to change over time between releases, and if you deploy this, all tags not mentioned in the package are deleted!

The clientcontext can also be configured by the content author using clientcontext content components. When including this in the code package, you again risk resetting this content on the AEM server.

ivo_eersels2Author bio
Ivo Eersels is an industrial engineer and has been a software engineer on the Intershop Suite 6 E-commerce platform at Osudio, one of Europe’s largest e-business specialists, since 2007. He has been working with AEM since 2013. Ivo plays a large role in setting up projects, DTAP servers, deployment strategies, guidelines, and development.