Migrate from wcm.io Configuration 0.x to Context-Aware Configuration

Owned by Stefan Seifert
Last updated: Apr 03, 2017

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 your 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.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-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 or MockConfig.setUp

And instead use the new Mock context plugins like this:

import static io.wcm.testing.mock.wcmio.caconfig.compat.ContextPlugins.WCMIO_CACONFIG_COMPAT;
import static io.wcm.testing.mock.wcmio.handler.ContextPlugins.WCMIO_HANDLER;
import static io.wcm.testing.mock.wcmio.sling.ContextPlugins.WCMIO_SLING;
import static org.apache.sling.testing.mock.caconfig.ContextPlugins.CACONFIG;

@Rule
public AemContext = new AemContextBuilder()
        .plugin(CACONFIG)
        .plugin(WCMIO_SLING, WCMIO_CACONFIG_COMPAT, WCMIO_HANDLER)
        .build();

If your are not using wcm.io Handler you can remove WCMIO_SLING and WCMIO_HANDLER.

Disable the configuration editor on publish:

[configurations runModes=publish]
  
  # Disable Configuration Editor on publish
  io.wcm.caconfig.editor.impl.EditorConfig
    enabled=B"false"

Scenario B: Drop-in replacement via Compatibility Layer and update to new APIs

Do the same steps as in Scenario A.

If you want to use the new Configuration Annotation Class Feature as described in Apache Sling Context-Aware Configuration you can do this and remove your wcm.io Configuration Parameters Definitions instead. You then use directly the Sling Context-Aware Configuration API to read the configuration data. Within Sightly templates you have to switch the syntax to access the configuration as well as described in the Sling Context-Aware documentation. The configuration of your parameters are then stored in /conf and no longer in ./tools/config pages. Only the configuration parameters provided by wcm.io Handler still use the compatibility layer. In the configuration editor you can edit both.

You may use the wcm.io Context-Aware Configuration Extensions for AEM to configure additional context path strategies or persistence strategies for the configuration data that is read and written directly through the Sling Context-Aware Configuration API.

Scenario C: Full Migration including upgrade to wcm.io Handler 1.x

See Migrate from wcm.io Handler 0.x to 1.x