Configurations and the Configuration Browser configuration-browser

Adobe Experience Manager (AEM) configurations serve to manage settings in AEM and serve as workspaces.

What is a Configuration? what-is-a-configuration

A configuration can be considered from two different viewpoints.

In summary: from an administrator’s point of view, configurations are how you create workspaces to manage settings in AEM, whereas the developer should understand how AEM uses and manages these configurations within the repository.

Regardless from your perspective, configurations serve two main purposes in AEM:

Configurations as an Administrator configurations-administrator

The AEM administrator and authors can consider configurations as workspaces. These workspaces can be used to gather groups of settings and their associated content for organizational purposes by implementing access rights for those features.

Configurations can be created for many different features within AEM.

Example administrator-example

For example, an administrator may create two configurations for Editable Templates.

The admin can then create general page templates using the WKND-General configuration and then templates specific to the magazine under WKND-Magazine.

The admin can then associate the WKND-General with all content of the WKND site. However the WKND-Magazine configuration would be associated only with the magazine site.

By doing this:

Similar setups are possible not only for Editable Templates but also for Cloud Configurations, ContextHub Segments, and Content Fragment Models.

Using the Configuration Browser using-configuration-browser

The Configuration Browser allows an administrator to easily create, manage, and configure access rights to configurations in AEM.

Creating a Configuration creating-a-configuration

It is simple to create a configuration in AEM using the Configuration Browser.

Editing Configurations and Their Access Rights access-rights

If you think of configurations as workspaces, access rights can be set on those configurations to enforce who may and may not access those workspaces.

Configurations as a Developer configurations-developer

As a developer, it is important to know how AEM as a Cloud Service works with configurations and how it processes configuration resolution.

Separation of Configuration and Content separation-of-config-and-content

Although the administrator and users may think of configurations as workplaces to manage different settings and content, it is important to understand that configurations and content are stored and managed separately by AEM in the repository.

Content references its associated configuration by way of a cq:conf property. AEM performs a lookup based on the content and its contextual cq:conf property to find the appropriate configuration.

Example developer-example

For this example, let’s assume you have some application code that is interested in DAM settings.

Conf conf = resource.adaptTo(Conf.class);
ValueMap imageServerSettings = conf.getItem("dam/imageserver");
String bgkcolor = imageServerSettings.get("bgkcolor", "FFFFFF");

The starting point of all configuration lookup is a content resource somewhere under /content. This could be a page, a component inside a page, an asset, or a DAM folder. This is the actual content for which you are looking for the right configuration that applies in this context.

Now with the Conf object in hand, you can retrieve the specific configuration item that you are interested in. In this case, it is dam/imageserver, which is a collection of settings related to the imageserver. The getItem call returns a ValueMap. You then read a bgkcolor string property and provide a default value of “FFFFFF” in case the property (or entire config item) is not present.

Now let’s have a look at the corresponding JCR content:

/content/dam/wknd
    + jcr:content
      - cq:conf = "/conf/wknd"
    + image.png [dam:Asset]

/conf/wknd
    + settings
      + dam
        + imageserver [cq:Page]
          + jcr:content
            - bgkcolor = "FF0000"

In this example, you can assume a WKND-specific DAM folder here and a corresponding configuration. Starting at that folder /content/dam/wknd, you can see that there is a string property that is named cq:conf that references the configuration that applies to the subtree. The property is set on the jcr:content of an asset folder or page. These conf links are explicit, so it is easy to follow them by just looking at the content in CRXDE.

Jumping inside /conf, follow the reference, and see that there is a /conf/wknd node. This is a configuration. Its lookup is transparent to the application code. The example code never has a dedicated reference to it, it’s hidden behind the Conf object. Which configuration applies is controlled through the JCR content.

You see that the configuration contains a fixed-named settings node that contains the actual items, including the dam/imageserver you need in this case. Such an item can be thought of as a “settings document” and is represented by a cq:Page including a jcr:content holding the actual content.

Finally, you see the property bgkcolor that this sample code needs. The ValueMap you get back from getItem is based on the page’s jcr:content node.

Configuration Resolution configuration-resolution

The basic example above showed a single configuration. But there are many cases where you want to have different configurations such as a default global configuration, a different one for each brand and maybe a specific one for your subprojects.

To support this the configuration lookup, AEM has an inheritance and fallback mechanism in the following order of preference:

Using Configurations using-configurations

Configurations in AEM are based on Sling Context-Aware Configurations. The Sling bundles provide a service API that can be used to get context-aware configurations. Context-aware configurations are configurations that are related to a content resource or a resource tree as was described in the previous example.

For more details about Context-Aware Configurations, examples, and how to use them, see the Sling documentation..

ConfMgr Web Console confmgr-web-console

For debugging and testing purposes, there is a ConfMgr web console at https://<host>:<port>/system/console/conf, which can show configurations for a given path/item.

Simply provide:

Click Resolve so you can see which configurations are resolved and get code samples that help to resolve those configurations.

Context-Aware Configuration Web Console context-aware-web-console

For debugging and testing purposes, there is a Context-Aware Configuration web console at https://<host>:<port>/system/console/slingcaconfig, which allows querying context-aware configurations in the repository and viewing their properties.

Simply provide:

Click Resolve so you can retrieve the associated context paths and properties for the selected configuration.