Problem
You have an existing AEM application which is based on wcm.io Configuration 0.x, and you want to migration to Apache Sling Context-Aware Configuration. Maybe you are also using wcm.io Handler 0.x which is also based on wcm.io Configuration 0.x.
Supported AEM Versions
Apache Sling Context-Aware Configuration is a built-in feature of AEM 6.3, and can be deployed manually in AEM 6.1 and AEM 6.2. AEM 6.0 or older is not supported.
If you are using AEM 6.1 or 6.2 you have to deploy the following bundles additionally (latest Version):
org.apache.sling:org.apache.sling.caconfig.api
org.apache.sling:org.apache.sling.caconfig.spi
org.apache.sling:org.apache.sling.caconfig.impl
Migration Scenarios
You have different migration scenarios:
- Scenario A: Drop-in replacement via Compatibility Layer
- Scenario B: Drop-in replacement via Compatibility Layer and update to new APIs
- Scenario C: Full Migration including upgrade to wcm.io Handler 1.x
Scenario A: Drop-in replacement via Compatibility Layer
Remove these bundles from you deployment:
- io.wcm:io.wcm.config.api
- io.wcm:io.wcm.config.core
- io.wcm:io.wcm.config.editor
And instead deploy these bundles:
- io.wcm:io.wcm.caconfig.application
- io.wcm:io.wcm.caconfig.compat
- io.wcm:io.wcm.caconfig.editor
Existing OSGi configurations for wcm.io Configuration 0.x should work in the same way in the compatibility Layer, the PIDs are unchanged. For configuration persistence, only io.wcm.config.core.persistence.impl.ToolsConfigPagePersistenceProvider
is supported, which still has to be enabled explicitly.
With this change your application should work. Configuration defined via the old wcm.io Configuration SPI are stilled stored together with content in /tools/config
pages. All other configurations managed via the new Sling Context-Aware Configuration API are stored directly in /conf
.
If you are using AEM Mock-based unit tests in your application together with wcm.io Configuration and wcm.io Handler you have to do the following steps in your Maven poms - remove these dependencies:
io.wcm:io.wcm.testing.wcm-io-mock.config
And instead add:
io.wcm:io.wcm.testing.wcm-io-mock.caconfig
io.wcm:io.wcm.testing.wcm-io-mock.caconfig-compat
org.apache.sling:org.apache.sling.testing.caconfig-mock-plugin
Additionally you have to update to the latest AEM Mocks version (1.x for AEM 6.1 or 2.x for AEM 6.2 and up) and remove the following statements from your unit test setup code:
Remove calls to
MockHandler.setUp
orMockConfig.setUp
And instead use the new Mock context plugins like this:
@Rule public AemContext = new AemContextBuilder() .plugin(CACONFIG) .plugin(WCMIO_SLING, WCMIO_CACONFIG, WCMIO_CACONFIG_COMPAT, WCMIO_HANDLER) .build();
If your are not using wcm.io Handler you can remove WCMIO_SLING
and WCMIO_HANDLER
.
Scenario B: Drop-in replacement via Compatibility Layer and update to new APIs
TBD
Scenario C: Full Migration including upgrade to wcm.io Handler 1.x
TBD
Related articles