DocumentationExperience Cloud KCS

Deploying custom Oak index definitions across AEM as a Cloud Service environments

Last update: September 9, 2026

This article explains how to deploy custom Oak index definitions successfully across Cloud Manager, local SDK, and Rapid Development Environments (RDE) in Adobe Experience Manager as a Cloud Service by using environment-specific wrapper configurations.

Description description

Environment

Adobe Experience Manager as a Cloud Service (AEMaaCS) (all versions)

Symptoms

  • Custom Oak index definitions deploy successfully to Cloud environments using Cloud Manager pipelines.
  • The same index definitions don’t result in the custom index being created or available when deployed to local AEM SDK or RDE environments.
  • Placing index definitions as oak:index nodes in code (under ui.apps) causes Cloud Manager builds to fail.
  • Only one canonical diff.json index definition is maintained in source control.

Cause

Cloud Manager and local/RDE environments require different wrapper node types for Oak index definitions. Using the same wrapper for all environments leads to deployment failures in some environments.

Resolution resolution

Follow the steps below to resolve the issue:

  1. Maintain a single canonical diff.json index definition in your source control at:

    ui.apps/src/main/content/jcr_root/_oak_index/diff.index/diff.json

  2. Create two environment-specific wrapper .content.xml files:

    • For Cloud Manager (Pipeline Mode):

    • src/main/sim-wrapper/pipeline/.content.xml

    Example content:

    <jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" jcr:primaryType="nt:unstructured" type="lucene" includedPaths="/same" queryPaths="/same" async="async"> <diff.json jcr:primaryType="nt:file"/> </jcr:root>

    • For Local SDK and RDE:
    • src/main/sim-wrapper/local/.content.xml

    Example content:

    <jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" jcr:primaryType="oak:QueryIndexDefinition" type="disabled"> <diff.json jcr:primaryType="nt:file"/> </jcr:root>

  3. Configure Maven profiles in your ui.apps/pom.xml to switch the wrapper at build time:

    • Set the Pipeline Mode profile (For example: sim-pipeline) as active by default for Cloud Manager builds.

    • Use a separate profile (For example: sim-local) for local SDK and RDE builds.

  4. Build and deploy using the correct Maven profile for each environment:

    • For Cloud Manager: Run the standard build (For example: mvn clean package) or with the pipeline profile, if needed.

    • For Local SDK: Run mvn clean install -Psim-local,autoInstallSinglePackage

    • For RDE: Run mvn clean package -Psim-local and deploy with aio aem:rde:install <built-zip>

  5. Before deploying, validate that the generated ZIP package contains the correct .content.xml for the target environment.

  6. For further details and examples, refer to the Oak Indexing Simplified Guide.

recommendation-more-help
experience-cloud-kcs-help-kbarticles