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

Sling Context-Aware Configurations, leveraged inside AEM, allows AEM sites to have different configurations for different regions while sharing some parameters that require inheritance for nested contexts and global fallback values.

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

1. A Sling Annotation class, which needs to meet certain 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 certain 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. But there are cases when you want to create CAConfigs for Back End services that do not fall into the use cases or categories listed before, so you don’t need the whole 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: in the site you are working on, there’s an email account to be used when a user wants to get in contact with 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 one 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 allows you to easily add a new email for a specific country site. Here CAConfigs are a good option.

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, inside an OSGi service, an Sling Model, etc:

   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 an specific country or 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.

Conclusion

Using Context-Aware configurations, we can leverage the required versatility to reuse configuration values for different sites but at the same time to specify more granular configuration values for regions, countries or even languages, without having to code additional logic.