Configurations and the Configuration Browser

AEM configurations serve to manage settings in AEM and serve as workspaces.

What is a Configuration?

A configuration can be considered from two different viewpoints.

• An administrator uses configurations as workspaces within AEM to define and manage groups of settings.
• A developer uses the underlying configuration mechanism that implements configurations to persist and look up settings in AEM.

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 enable certain features for certain groups of users.
• Configurations define access rights for those features.

Configurations as an Administrator

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

Configurations can be created for many different features within AEM.

• Cloud Configurations
• Context Hub Segments
• Content Fragment Models
• Editable Templates

Example

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

• WKND-General
• WKND-Magazine

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:

• When a content author creates a new page for the magazine, the author can choose from general templates (WKND-General) or magazine templates (WKND-Magazine).
• When a content author creates a new page for another part of the site that is not the magazine, the author can only choose from the general templates (WKND-General).

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

Using the Configuration Browser

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

Creating a Configuration

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

1. Log into AEM as a Cloud Service and from the main menu select Tools -> General -> Configuration Browser.

2. Tap or click Create.

3. Provide a Title and a Name for your configuration.

   

   • The Title should be descriptive.
   • The Name will become the node name in the repository.
     • It will be automatically generated based on the title and adjusted according to AEM naming conventions.
     • It can be adjusted if necessary.

4. Check the type of configurations you wish to allow.

   • Cloud Configurations
   • Context Hub Segments
   • Content Fragment Models
   • Editable Templates

5. Tap or click Create.

Editing Configurations and Their Access Rights

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

1. Log into AEM as a Cloud Service and from the main menu select Tools -> General -> Configuration Browser.
2. Select the configuration you wish to modify and then tap or click Properties in the tool bar.
3. Select any additional features you wish to add to the configuration
   NOTE

   It is not possible to unselect a feature once the configuration has been created.

   1. Use the **Effective Permissions** button to view a matrix of roles and what permissions they are currently granted to configurations. 
4. To assign new permissions, enter the user or group name in the Select user or group field in the Add New Permissions section.
   • The Select user or group field offers auto-completion based on existing users and roles.
5. Select the appropriate user or role from the auto-complete results.
   • You can select more than one user or role.
6. Check the access options that the selected user(s) or role(s) should have and click Add.
   
7. Repeat the steps to select users or roles and assign additional access rights as necessary.
8. Tap or click Save & Close when finished.

Configurations as a 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

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 is home to all content.
• /conf is home to all configuration.

Content references its associated configuration via a cq:conf property. AEM performs a lookup based on the content and it’s contextual cq:conf property to find the appropriate configuration.

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, usually somewhere under /content. This could be a page, a component inside a page, an asset, or DAM folder. This is the actual content for which we are looking for the right configuration that applies in this context.

Now with the Conf object in hand, we can retrieve the specific configuration item we 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. We 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/wkns
    + settings
      + dam
        + imageserver [cq:Page]
          + jcr:content
            - bgkcolor = "FF0000"

In this example, we assume a WKND specific DAM folder here and a corresponding configuration. Starting at that folder /content/dam/wknd, we’ll see that there is a string property named cq:conf that references the configuration that should apply for the subtree. The property will usually be 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, we follow the reference and see there is a /conf/wknd node. This is a configuration. Please note that its lookup is completely 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 completely controlled through the JCR content.

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

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

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 sub projects.

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

1. /conf/<siteconfig>/<parentconfig>/<myconfig>
   • Specific config referenced from cq:conf somewhere in /content
   • The hierarchy is arbitrary and can be designed just like your site structure, it is not the business of application code to know this
   • Changeable at runtime by users with configuration privileges
2. /conf/<siteconfig>/<parentconfig>
   • Traverse parents for fallback configs
   • Changeable at runtime by users with configuration privileges
3. /conf/<siteconfig>
   • Traverse parents for fallback configs
   • Changeable at runtime by users with configuration privileges
4. /conf/global
   • System global settings
   • Usually global defaults for your installation
   • Set by an admin role
   • Changeable at runtime by users with configuration privileges
5. /apps
   • Application defaults
   • Fixed with application deployment
   • Read-only at runtime
6. /libs
   • AEM product defaults
   • Only changeable by Adobe, project access not allowed
   • Fixed with application deployment
   • Read-only at runtime

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 further details about Context-Aware Configurations, examples, and how to use them, see the Sling documentation.

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:

• Content Path
• Item
• User

Click Resolve to see which configurations are resolved and receive sample code which will resolve those configurations.

Context-Aware Configuration 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:

• Content Path
• Config Name

Click Resolve to retrieve the associated context paths and properties for the selected configuration.

Business.Adobe.com resources