How to Embed wcm.io Context-Aware Configuration Editor

This blog article serves as your guide to seamlessly integrate and deploy the wcm.io Context-Aware Configuration Editor – a powerful tool that streamlines configuration management within AEM projects.

Throughout this article, we will delve into the step-by-step process of configuring, installing, embedding, and deploying the wcm.io Context-Aware Configuration Editor. By following these instructions, you’ll be able to harness the capabilities of this editor to automatically install configuration changes across all environments when your code is built via Maven and deployed to AEM. When it comes to deploying the wcm.io Context-Aware Configuration Editor, automation is key.

Quick Links

Add dependencies to parent pom.xml
Add dependencies to your target maven module
Configure com.day.jcr.vault’s <embeded> to target maven module
Add template to create and manage wcm.io caConfigs
Context-Aware Configuration bnd plugin
Absolute Parent Context Path Strategy
Root Template Context PathStrategy
Page Persistence Strategy

1. Add dependencies to parent pom.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<dependencyManagement>
<dependencies>
...
<dependency>
<groupId>io.wcm</groupId>
<artifactId>io.wcm.caconfig.editor.package</artifactId>
<version>1.8.0</version>
<type>zip</type>
</dependency>
<dependency>
<groupId>io.wcm</groupId>
<artifactId>io.wcm.caconfig.extensions</artifactId>
<version>1.8.0</version>
</dependency>
</dependencies>

2. Add dependencies to your target maven module

In this example, we will target all/pom.xml

1
2
3
4
5
6
7
8
9
10
11
12

<dependencies>
...
<dependency>
<groupId>io.wcm</groupId>
<artifactId>io.wcm.caconfig.editor.package</artifactId>
<type>zip</type>
</dependency>
<dependency>
<groupId>io.wcm</groupId>
<artifactId>io.wcm.caconfig.extensions</artifactId>
</dependency>
</dependencies>

3. Configure com.day.jcr.vault’s <embeded> to target maven module

In this example, we will target all/pom.xml, and yes, step 2 and 3 are configuration added to the same file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<plugins>
<plugin>
...
<groupId>com.day.jcr.vault</groupId>
<artifactId>content-package-maven-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<group>sourcedcode-packages</group>
<filterSource>src/main/content/META-INF/vault/filter.xml</filterSource>
<embeddeds>
<embedded>
<groupId>io.wcm</groupId>
<artifactId>io.wcm.caconfig.editor.package</artifactId>
<type>zip</type>
<target>/apps/sourcedcode/install</target>
</embedded>
<embedded>
<groupId>io.wcm</groupId>
<artifactId>io.wcm.caconfig.extensions</artifactId>
<target>/apps/sourcedcode/install</target>
</embedded>
</embeddeds>
<targetURL>http://${crx.host}:${crx.port}/crx/packmgr/service.jsp</targetURL>
</configuration>
</plugin>
</plugins>

4. Add template to create and manage wcm.io caConfigs

./ui.apps/src/main/content/jcr_root/apps/sourcedcode/templates/caconfig-template/content.xml

1
2
3
4
5
6
7
8
9
10

<?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="Context-Aware Configuration Page"
allowedPaths="[^/content/sourcedcode(/.*)?$]"
ranking="{Long}110">
<jcr:content
jcr:primaryType="cq:PageContent"
sling:resourceType="wcm-io/caconfig/editor/components/page/editor"/>
</jcr:root>

5. Context-Aware Configuration bnd plugin

A bnd plugin is provided that scans the classpath of a bundle Maven project at build time and automatically generates a Sling-ContextAware-Configuration-Classes bundle header for all annotation classes annotated with @Configuration. It can be used by both maven-bundle-plugin and bnd-maven-plugin, as both use the bnd library internally.

Standard Configuration
Place the configuration from the root pom.xml as such:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>

<_plugin>org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin</_plugin>
</instructions>
</configuration>
<dependencies>
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.caconfig.bnd-plugin</artifactId>
<version>1.0.2</version>
</dependency>
</dependencies>
</plugin>

If you use the bnd-maven-plugin and raw bnd statements, you have to configure it with this bnd statement:
Place the configuration from the root pom.xml as such:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<plugin>
<groupId>biz.aQute.bnd</groupId>
<artifactId>bnd-maven-plugin</artifactId>
<configuration>
<bnd><![CDATA[
...
-plugin org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin
]]></bnd>
</configuration>
<dependencies>
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.caconfig.bnd-plugin</artifactId>
<version>1.0.2</version>
</dependency>
</dependencies>
</plugin>

Sling Context Aware Configuration context-aware-configuration-bnd-plugin not working as expected
If both installations from the top are not working as expected, please try the configuration as below. Place the configuration from the root pom.xml as such. Take a look at line 21, where you can see we have kept org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin, org.apache.sling.bnd.models.ModelsScannerPlugin in one line of code, with a comma as the delimiter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<plugin>
<groupId>biz.aQute.bnd</groupId>
<artifactId>bnd-maven-plugin</artifactId>
<version>${bnd.version}</version>
<executions>
<execution>
<id>bnd-process</id>
<goals>
<goal>bnd-process</goal>
</goals>
<configuration>
<bnd><![CDATA[
Bundle-Category: ${componentGroupName}

# export all versioned packages except for conditional ones (https://github.com/bndtools/bnd/issues/3721#issuecomment-579026778)
-exportcontents: ${removeall;${packages;VERSIONED};${packages;CONDITIONAL}}

...

Bundle-DocURL:
-plugin org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin, org.apache.sling.bnd.models.ModelsScannerPlugin
]]>
</bnd>
</configuration>
</execution>
</executions>
...
</plugin>

6. Absolute Parent Context Path Strategy

io.wcm.caconfig.extensions.contextpath.impl.AbsoluteParentContextPathStrategy-sourcedcode.config

1
2
3
4
5
6
7

contextPathBlacklistRegex=""
service.ranking=I"2000"
unlimited=B"false"
configPathPatterns=["/conf$1"]
levels=i["1","2","3","4"]
contextPathRegex="^/content(/sourcedcode|/experience-fragments/sourcedcode/.*)$"
templatePathsBlacklist=[""]

In this crucial step, we introduce the Absolute Parent Context Path Strategy, found in the io.wcm.caconfig.extensions.contextpath.impl.AbsoluteParentContextPathStrategy-.config. This feature allows you to create tailored configurations for specific folders within your content repository. For instance, you can now establish separate configurations for ‘/content/sourcedcode/en’ and ‘/content/sourcedcode/fr,’ effectively breaking the chain of inheritance. This newfound freedom permits you to cancel inheritance at various levels, from 1 to 4, enabling you to fine-tune configurations to align with your folder structure. This level of precision and customization is pivotal in optimizing your content management experience.

7. Root Template Context PathStrategy

io.wcm.caconfig.extensions.contextpath.impl.RootTemplateContextPathStrategy-sourcedcode.config

1
2
3
4
5
6
7

maxLevel=I"4"
service.ranking=I"2000"
templatePaths=["/conf/sourcedcode/settings/wcm/templates/content-page","/conf/sourcedcode/settings/wcm/templates/blank-page"]
configPathPatterns=["/conf$1"]
contextPathRegex="^/content/sourcedcode.*)$"
templateMatchAllLevels=B"true"
minLevel=I"1"

In this step, we focus on configuring the io.wcm.caconfig.extensions.contextpath.impl.RootTemplateContextPathStrategy-.config. This feature allows you to establish a foundational template for your content, ensuring a well-structured content hierarchy in your AEM project. By defining a root template, you simplify content management and maintain consistency throughout your project. Whether you’re building a website, an application, or a digital experience, configuring a root template is a fundamental step in aligning your content with your project’s objectives.

8. Absolute Parent Context Path Strategy, Folder Level Ca Configs

io.wcm.caconfig.extensions.persistence.impl.PagePersistenceStrategy.config

1
2
3

service.ranking=I"1500"
enabled=B"true"
resourceType="nt:unstructured"

If you intend to maintain the default Sling implementation, there are two options for handling the configurations: you can either package them from the author environment to the publish environment or replicate them from CRXDE Lite. If you opt for the wcm.io editor, it offers a feature that facilitates configuration replication by saving configurations as cq:Page nodes. To activate replication within the editor page, you should utilize the “PagePersistenceStrategy” provided by the “caconfig.extension” package, which must be deployed in AEM. Additionally, you need to enable the “io.wcm.caconfig.extensions.persistence.impl.PagePersistenceStrategy” OSGi configuration within the ui.apps module. Failing to complete this step will result in ca configurations being stored as folders, which necessitates setting the resourceType to nt:unstructured.

How to Embed wcm.io Context-Aware Configuration Editor