Context-Aware Configuration (CAConfig) in AEM with WCM-IO – A Practical Guide

When building multi-language or multi-site Adobe Experience Manager (AEM) websites, you often need to apply site-specific or language-specific configurations.

For example, imagine you have an English site and an Arabic site. You may want different authentication settings, API keys, or UI labels based on which site the user visits. This is where Context-Aware Configuration (CAConfig) in AEM becomes incredibly useful.

It allows you to define configuration values at the site, language, or page level, and AEM automatically picks the correct values based on the page context.

Why Use Context-Aware Configuration in AEM?

CAConfig makes your code:

• Flexible – define different settings for different sites or pages
• Clean & Secure – no hardcoding values
• Maintainable – easier for teams to update settings in /conf

Getting Started with CAConfig in AEM

• Navigate to your core module in the AEM Maven project, and optionally create a config package (e.g., com.myproject.core.config).

• Then create a Java interface, for example: MsalConfig.java.

 package com.adobe.aem.guides.inowate.core.config;

 import org.apache.sling.caconfig.annotation.Configuration;
 import org.apache.sling.caconfig.annotation.Property;

 @Configuration(
        label = "Inowate -  Context Aware Configuration for MSAL",
        description = "Context Aware Configuration for Inowate AEM Project"
 )
 public @interface MsalCaConfig {

    @Property(
    label = "Configuration Name", 
    description = "Name of the configuration context")
    String configName() default "configName:";

    @Property(
    label = "Entra ID", 
    description = "Unique identifier for the application")
    String entraID() default "entraID:";

    @Property(
    label = "Authority",
    description = "Authorization server or token issuer URL")
    String authority() default "authority:";
 }

How to Use Context-Aware Configuration in Your AEM Component

Once your configuration interface is ready, the next step is to use it in your component where it’s needed.

For example, I have a component called TeamMember, and I want to access the configuration values defined via CAConfig and display them on the HTML output. For demonstration purposes, I’ll simply render the values in the 

 package com.adobe.aem.guides.inowate.core.models;

 import com.adobe.aem.guides.inowate.core.config.MsalCaConfig; //importing config here
 @Model(adaptables = { SlingHttpServletRequest.class,
    Resource.class }, defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL)
 public class TeamMembersModel {

    private static final Logger LOGGER =
     LoggerFactory.getLogger(TeamMembersModel.class);

    @SlingObject
    private Resource currentResource;

    private String configName; // local veriables will use for config
    private String entraID;  // local veriables will use for config
    private String authority; // local veriables will use for config

    
    @PostConstruct
    protected void init() {
    if (currentResource != null) {
        ConfigurationBuilder configBuilder 
            = currentResource.adaptTo(ConfigurationBuilder.class);
        if (configBuilder != null) {
            MsalCaConfig caConfig = configBuilder.as(MsalCaConfig.class);
            if (caConfig != null) {
                configName = caConfig.configName();
                entraID = caConfig.entraID();
                authority = caConfig.authority();
                LOGGER.info("Loaded CAC: configName={},
                 entraID={}, authority={}", configName, entraID, authority);
            } else {
                LOGGER.warn("CAConfig is null");
            }
        } else {
            LOGGER.warn("ConfigurationBuilder is null");
        }
    }
    }
    // functions that will return the configs values.
    public String getConfigName() {
        return configName;
    }

    public String getEntraID() {
        return entraID;
       }

    public String getAuthority() {
        return authority;
    }

    }

Here, I’m simply rendering the configuration values in the HTML file for demonstration purposes.

Also, add the following code in /core/pox.xml in the <bnd> tag, adjust the code according to. Your project classes

 
 <bnd><![CDATA[
   -plugin: org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin,\
               org.apache.sling.bnd.models.ModelsScannerPlugin
      Sling-ContextAware-Configuration-Classes: \
        com.adobe.aem.guides.inowate.core.config.MsalCaConfig
    Import-Package: javax.annotation;version=0.0.0,*

                                ]]></bnd>

Deploying the Configuration

To deploy the configuration, run the following Maven commands:

• mvn clean install -PautoInstallBundle -Padobe-public
• mvn clean install -PautoInstallPackage -Padobe-public

Creating the Configuration in CRXDE Lite

1. Navigate to /conf/projectname and create a folder named sling:configs. Make sure the folder’s primary type is set to sling:Folder.

2. Inside sling:configs, create a new node with type nt:unstructured. Name this node exactly the same as your configuration interface file from the core module (for example, MsalConfig).

3. Under this node, define the properties using the same field names as declared in your Java config interface. Assign appropriate values to these properties.

4. To support multiple languages or sites (e.g., English and Arabic), create additional folders named en and ar, and copy the sling:configs structure into each. Then update the values based on the specific language or site requirements.

You can create as many language or site-specific folders as you need, based on your project requirements.

Refer to the screenshot below for a clear structure example.

/conf/inowate/sling:configs

/conf/inowate/en/sling:configs

/conf/inowate/ar/sling:configs

Linking Context-Aware Configuration to Your Sites

To apply your Context-Aware Configuration (CAConfig) to specific sites or pages, you'll need to set the sling:configRef property.

Navigate to the jcr:content node of the page where you want the configuration applied, and add the sling:configRef property. The value should be the path to the configuration you want to load.

In my setup:

• I'm linking the general sling:configs to the language-masters site.
• The /en configuration is linked to the English site.
• The /ar configuration is linked to the Arabic site.

This allows AEM to automatically resolve and apply the correct configuration based on the context of the site or page being accessed.

Refer to the screenshots below for visual guidance.

For language-masters

For English site /content/inowate/language-masters/en

For Arabic site: /content/inowate/language-masters/en

So, when I load the English site page, AEM fetches the configuration from:

/conf/inowate/en/sling:configs

And when I load the Arabic site page, it pulls the configuration from:

/conf/inowate/ar/sling:configs

This ensures each language site uses its specific context-aware settings. Refer to the following screenshots for a clear example:

English Site Configuration Output:

Arabic Site Configuration Output:

Note: 

If you have another site, for example a German site, and you haven’t created specific Context-Aware Configurations for it, AEM will fall back to the default configuration located at: /conf/inowate/sling:configs

It won’t use the configurations from the en or ar folders, as those are specifically tied to the English and Arabic sites.

Context-Aware Configuration with WCM-IO Editor

Using the WCM-IO Editor, you can easily manage site-specific or page-specific Context-Aware Configurations (CA-Configs) in AEM. It simplifies the process of creating, updating, and maintaining CA-Configs through a user-friendly interface.

The initial steps remain the same as previously discussed. After that, you’ll need to install the WCM-IO package. This can be done by downloading the package and deploying it to AEM via CRXDE Lite.

Click here to download the WCM-IO package

Next, you’ll need to create a template, which will be used for creating your CA-Configuration page. You can create this template at the following path:

/apps/your-project/templates/template-name

Here’s the sample code for the template I’ll be using to create the CA-Configuration page:

 <?xml version="1.0" encoding="UTF-8"?>
 <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
          xmlns:cq="http://www.day.com/jcr/cq/1.0"
          xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="cq:Template"
          jcr:title="CAConfig Editor Page"
          jcr:description="Template to edit context-aware configurations"
          allowedPaths="[/content(/.*)]"
          ranking="{Long}100">

        <jcr:content
                jcr:primaryType="cq:PageContent"
                sling:resourceType="wcm-io/caconfig/editor/components/page/editor"
                jcr:title="CAConfig Editor Page"/>
 </jcr:root>

Screenshot from the code:

 After creating the template, make sure to include its path in the src/main/content/META-INF/vault/filter.xml file by adding the following entry:

<filter root="/apps/projectName/templates"/>

Now, run the following command to deploy the template to your AEM instance:

mvn clean install -PautoInstallPackage -Padobe-public

On CRXDLITE: 

Once the deployment is complete, let's say you have a German site and want to create a site-specific configuration for it.

To do this, go to CRXDE Lite, create a new folder named de under /conf/your-project/, and add the sling:configs node inside that folder then at the page level of your German site add sling:configRef  and assign the path to its until de folder. This will link the site to its specific context-aware configuration. Refer to the screenshots below for guidance.

 

Next, add the sling:configRef property to the jcr:content node of the German website page.

Creating a CA Configuration Page for the German Site

• Navigate to the German site in AEM.
• Select the German main page and click on the create button.
• Choose the Configuration Template.
• Enter a name for the configuration page and click Create.
• Open the newly created page.
• Click on the Configuration option.
• Add the site-specific values you want for the German page.
• Go to your German site page and refresh it.

You’ll now see that German-specific CA configurations are applied only to the German site.

Selecting the German page to create the CA config page

selecting template

Adding the name of a page

Clicking on configuration 

Adding values for German page

Final output

Benefits of Using Context-Aware Configuration (CAConfig) in AEM

Custom Configs for Each Site or Language

You can easily set up different configurations for each website or language version — like English, Arabic, or German — without mixing things up.

Applies Configs Based on Page Location

AEM automatically picks the right configuration based on where the content lives, so there’s no need to write extra code to handle it manually.

All Configurations in One Place

Everything stays organised under the /conf folder, making it easier to manage and reuse across different components and pages.

Less Code, More Clarity

Since the logic lives in configuration, your components don’t need as many if-else checks, keeping the code clean and easier to maintain.

Perfect for Multi-Site Projects

If you're building for multiple brands or clients under one AEM instance, CAConfig helps you keep each one separate with its own set of rules.

Built-in Fallback Support

If a specific configuration isn’t found, AEM will automatically fall back to a default one — like global settings — so your site stays functional.

Secure and Easy for Authors

Configuration is separate from content, and tools like the wcm.io editor make it easy for non-developers to update values when needed.

Flexible Down to the Page Level

You can even have different settings for individual pages if needed — for example, one page could show a different layout or title than another.

Scales Well as You Grow

Whether you’re adding new regions, languages, or brands, CAConfig makes it simple to scale your setup without a mess.

Difference Between OSGi Configuration and Context-Aware Configuration (CAConfig) in AEM
OSGi Configuration

System-Level Settings

OSGi configs are mostly used for backend services and bundles — like setting up a connection to an external API, defining timeouts, or toggling a feature flag globally.

Applies Globally

Once set, the values apply across the whole AEM instance unless you're using run modes to split them.

Managed via Felix Console or Files

You typically manage OSGi configs through the Felix console (/system/console/configMgr) or deploy them from files under /apps or /libs.

Developer-Oriented

Mostly handled by developers or DevOps teams, not authors. Not very user-friendly for content teams. 

 Context-Aware Configuration (CAConfig)

Content-Level Settings

CAConfig is used when you need site-specific or page-specific settings, like setting a site title, map coordinates, or theme per language/site.

Applies Based on Context

It automatically picks the correct config based on where the content lives (e.g., /content/site/en vs /content/site/ar).

Stored Under /conf

All configurations live neatly under the /conf folder and can be edited through CRXDE or even via UI tools like wcm.io editor.

Author-Friendly

Authors or content admins can manage CAConfigs easily without touching code. It’s made for flexibility on the content side.

Conculusion

Context-Aware Configuration in AEM makes managing site- and language-specific settings simple and efficient. It helps keep your code clean and lets authors update configs easily without developer help. This approach is perfect for scaling multi-site projects smoothly. If you want flexible and maintainable configs, CAConfig is the way to go!