Context-aware configuration for site-specific AEM settings

AEM's Sling Context-Aware Configuration gives Java teams a way to vary OSGi settings by site, brand, tenant or resource path while keeping one governed deployment. Instead of copying configuration packages for every market, teams define a shared baseline and allow a more specific context to supply only the differences. The result can be easier to release, audit and support across AEM Sites. Learn more about 217796 Sekrety Finalistov Kak Oni Reshali Keisy Unilever.

The capability is most useful when business variation is real and stable. It is not a substitute for content modelling, authorisation or feature management, and a poorly designed hierarchy can become just as tangled as duplicated code. Clear ownership, predictable overrides and publish-stage testing matter more than the number of configuration levels.

How context-aware configuration resolves settings

Sling evaluates context during a request, using factors such as the resolved resource path, selectors, extension and request properties. It then selects the applicable configuration definitions and combines their OSGi property values. A shared default can therefore remain intact while a site, tenant or individual resource supplies a deliberate override.

Configuration definitions can live in a controlled configuration bucket such as /apps/.../osgiconfig/config and be associated with resources through supported bindings like sling:configRef. This arrangement keeps deployment code separate from contextual values while allowing content structures to point towards the configuration they need. Component-specific rules still apply, particularly for factory configurations and services with named configuration references.

Run modes provide the complementary environment boundary: they distinguish authoring, development and publish behaviour at deployment time, while Context-Aware Configuration resolves variation inside that environment. Keeping those mechanisms distinct prevents a local setting from accidentally reaching production. The archived CIRCUIT programme's ICF Olson’s profile offers useful conference background for teams balancing AEM architecture, integrations and delivery constraints.

Build a maintainable configuration model

Start by separating configuration from editorial content. Names, endpoints, service toggles and implementation bindings usually belong in OSGi configuration; reusable copy, product information and structured business content belong in the content layer or content fragments. Mixing the two creates review bottlenecks and makes cache invalidation harder to reason about.

Use stable property names, document every supported override and assign an owner to each configuration definition. Avoid using a site name as a catch-all property when a semantic name, such as service.endpoint or consent.provider, would work across brands. That small discipline lets teams reorganise URLs without rewriting Java code or configuration consumers.

Treat configuration definitions as versioned code. Store them in source control, review changes alongside related bundles and promote tested packages through the deployment pipeline used by the AEM installation. Where a setting changes after launch, apply the same discipline expected for content approval workflows: record the request, name the owner, test it outside production and retain an auditable approval.

Use a practical configuration hierarchy

A hierarchy should reflect business decision boundaries, not an arbitrary collection of URL folders. Global consumer businesses already separate core requirements from local conditions; the Unilever case studies illustrate why context shapes the right solution. For AEM, that usually means asking whether a value belongs to the platform, a brand, a market or one tightly bounded resource.

Use layers only while they create useful inheritance:

Shared baseline in /apps/.../osgiconfig/config for values that are safe everywhere.
Brand layer for brand-wide bindings, naming conventions or shared service choices.
Market layer for Australian or New Zealand differences such as consent handling or a regional endpoint.
Resource reference through sling:configRef where a page or tenant genuinely needs an override.

Each child layer should override named properties rather than copy an entire definition. Document precedence, make the winning source observable in diagnostics and remove redundant layers when two scopes always resolve to the same values. This keeps a site-specific setting easy to trace without turning the configuration tree into another content fork.

Protect security and publishing controls

Context selection is not access control. Choosing a configuration because a request reached a particular path neither grants access nor protects a secret. Keep repository permissions, OSGi service policies, TLS and identity controls outside the inheritance hierarchy, and test them independently at authoring and publish stages. For stronger authentication, custom two-factor login modules show one AEM-specific route, but evaluate them alongside the organisation's identity platform.

Credentials must not be committed to configuration definitions because JCR content may be exported, cloned or read by more people than application code. Resolve secrets through approved credential stores or secret-management integration, and grant service accounts only the permissions each integration needs. On AEM as a Cloud Service, include pipeline and environment separation in the same review.

Controls worth validating include:

Least privilege: map every service account to the minimum repository and OSGi permissions.
Environment separation: test author, preview and publish contexts with their intended run-mode filters.
Rollback evidence: retain the previous package and record which configuration source won for each site.

A publish-readiness check should fetch representative pages with real selectors and extensions, inspect the resolved values and confirm that no authoring-only setting has leaked into the public tier. Configuration changes need the same traceability as content releases, even when the business owner describes them as a small endpoint tweak.

Account for Australian delivery conditions

Australian delivery teams are often distributed across Sydney, Melbourne, Brisbane and Perth, so a release window is more than a date on a calendar. Different UTC offsets affect overlap meetings, while daylight-saving rules also vary: most eastern states shift their clocks, Queensland does not, and Perth uses Western Australian time. Store timezone-aware schedules centrally and avoid approving changes through device-local assumptions.

Use Australian English in labels and content, including organisation, behaviour and localisation, while keeping code keys unchanged. Australian teams often use informal terms such as arvo and no worries in internal chat, but customer-facing metadata should remain plain and professional. For brands trading in Australia, a .com.au campaign domain, GST-inclusive pricing and a local approval path may need distinct bindings. Front-end teams can compare delivery patterns with peers through NUGGET Fringe sessions, then adapt the useful parts to local requirements.

Treat privacy as configuration with consequences. Map the Australian Privacy Principles under the Privacy Act 1988, alongside relevant state or territory requirements, into consent behaviour, analytics defaults and data-service choices rather than relying on a generic overseas consent string. Seasonal timing also matters in a southern-hemisphere market: summer campaigns, the end of the financial year and Christmas trading periods need their own content, promotion and release readiness.

Put the pattern into production

Begin with one pilot site that has a clear business owner and at least one genuine regional or brand variation. Map each context to a configuration path, document precedence and record baseline measures such as error rate, cache hit ratio, authoring latency and support demand. Keep the logic in version control and the generated artefact reproducible, whether the target is AEM 6.5 or AEM as a Cloud Service.

Validate the complete resolution chain rather than one component. Exercise inherited values, overrides, selectors, extensions and relevant run modes in a non-production environment, then repeat the checks against the published site. Record the resolved configuration source, remove accidental duplication and publish a short decision record explaining why each override exists.

Create the context map, assign a pilot owner and book a publish-readiness review before another AEM site copies the pattern.