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
- Navigate to /conf/projectname and create a folder named sling:configs. Make sure the folder’s primary type is set to sling:Folder.
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).
Under this node, define the properties using the same field names as declared in your Java config interface. Assign appropriate values to these properties.
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 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!
.jpeg "How to Create Multi-Language and Multi-Location Project In AEM")
.jpeg "AEM Editable Templates | Create Page using Editable template")
