How to Use Context-Aware Configurations for Back-End AEM Development

Context-Aware Configurations are a feature of Apache Sling, a framework used within AEM that maps HTTP request URLs to content resources.

These configurations are tied to specific content resources or resource trees, enabling developers to define settings that adapt based on the location or context within the content hierarchy. Core Components use them to support site-wide configurations.

With context-aware configurations, developers can build scalable, multi-site architectures that adapt to different regions, brands, or business units without needing to duplicate code or configuration logic. This leads to consistent user experiences, lower maintenance costs, and better alignment between technical implementation and business structure.

A Context-Aware Configuration(CAConfig) is made possible by a combination of:

1. A Sling Annotation class, which needs to meet specific requirements to be considered as a CAConfig class:

   1. Is a POJO annotated with @Configuration and @interface (official example from Apache Sling: CAConfig Annotation Class)

   2. With methods named as the required configuration attributes

2. A Sling Configuration node(XML) that needs to meet specific requirements to be considered as a CAConfig node:

   1. Is a JCR node of type sling:OsgiConfig

   2. Needs to be created inside or below a sling:configs parent JCR node of type sling:Folder

   3. Named with the fully-qualified class name of its corresponding CAConfig Annotation class

   4. Has attributes matching the name and type of the methods defined on the corresponding CAConfig Annotation class

3. A page property called sling:configRef of type String that points to the context path to be used by this page for configurations.

When you have a properly defined CAConfig node that maps a CAConfig Annotation class, and you try to get those configuration attributes, they are resolved according to the Configuration Resolution lookup.

Adobe provides the Configuration Manager to author (create or edit) parent CAConfigs directories for: Context Hub Segments, Content Fragment Models, Editable Templates and Cloud Configurations. Doing it this way results in a node structure with a default "settings" node specific for each of those variations. However, there are cases when you want to create CAConfigs for back-end services that don't fall into the use cases or categories listed before, so you don't need the entire default settings node structure.

Here we are going to show you how to manage CAConfigs creation for that scenario.

To create use a CAConfig you need to:

1. Determine if you require a CAConfig!

2. Create your CAConfig class.

3. Create your CAConfig node.

4. Add a sling:configRef property to your site root pages pointing to the corresponding context path.

5. Get your CAConfig values in the Back End using the Sling Configuration Builder.

Example case:

Requirement: On the site you are working on, there is an email account that users can use to contact the company. On the site, that number appears several times in several places. The company would like to use a specific email for the US page in English, a different email for the US page in Spanish, another for the Canadian site, another for the Mexican site, and a single email for all Latin American countries. This is the site structure:

You have been asked to provide a solution that has a single point of update for maintenance work and that allows you to easily add a new email for a specific country site. CAConfigs are a good option here.

Steps:

1. A CAConfig makes a lot of sense in this case.

2. Let’s create our CAConfig class com.mysite.core.caconfigs.ContactUsConfig:

   CAConfig class

   Configuration(label="Contact Email", description="This email will be provided to users")
   public @interface ContactUsConfig {
        
       @Property(label="Contact Email", description="Customers will try to contact this email!")
       String email();
        
   }
   

3. Let’s create CAConfig node:

   1. First create the following directory structure inside /conf to map your site configuration requirements (all nodes are of type sling:Folder):

      

   2. Now create the corresponding CAConfig nodes within sling:configs parent nodes.

      

4. Add to every site root page of your site a sling:configRef property pointing to the corresponding context path.

   

   Note: all Latin America sites will reference the same context path (/conf/mysite/sling:configs/latin-america) so all of them use the same email value.

5. Use your Context-Aware configuration values in your back-end code, such as inside an OSGi service or a Sling model.

   ConfigurationBuilder

   try {
    
    Resource resource = resourceResolver.getResource(currentPagePath);
    
    if (resource != null) {
    
     ConfigurationBuilder confBuilder = resource.adaptTo(ConfigurationBuilder.class);
    
     if (confBuilder != null) {
    
      ContactUsConfig caconfig = confBuilder.as(ContactUsConfig.class);
    
      String contactEmail = caconfig.email();
    
     }
    
    }
    
   } catch (Exception e) {
    
    //Your Exception Handling code
    
   }
   

6. You can easily expose these values to HTL in two ways:

   1. Getting them inside a Sling Model and exposing them in a getter method, so the component that requires this value just needs to include the Sling Model in HTL and call the getter method.

   2. Using the ConfigurationBindingsValueProvider like this:

      ConfigurationBindingsValueProvider

      ${caconfig['com.mysite.core.caconfigs.ContactUsConfig'].email}
      

7. In case you need to specify a new email for a specific country, region, or language, you just:

   1. Add a new folder inside /conf with its corresponding CAConfig node.

   2. Add to the Page configuration the corresponding sling:configRef property pointing to the new context path.

Wrapping Up

Using Context-Aware configurations, developers can easily reuse settings across different websites while customizing them for specific regions, countries, or languages.

If you’re a global brand using AEM and managing multiple websites, context-aware configurations can make personalizing the experience on each site easier. However, to get the most out of features like this and everything else AEM offers, it helps to have a knowledgeable partner. Oshyn is an Adobe partner that can help you build engaging digital experiences and maximize your AEM investment.

Learn how to Improve Context-Aware Configurations on our blog.