aem-cs-source-migration-index-converter provides the capability to transform on-premise
Custom OAK Index Definitions to AEM as a Cloud Service compatible OAK Index Definitions.
Index Converter allows Adobe Experience Manager (AEM) developers to migrate existing Custom Oak Index Definitions to AEM as a Cloud Service compatible Custom Oak Index Definitions.
Custom Oak Index Definitions are categorized as:
- Custom OOTB (Product) Oak Index Definitions: Modification into existing OOTB Oak Index Definitions
- Newly created Oak Index Definitions
There are two ways to create Custom Oak Index Definitions:
- either under
/apps(through any custom content package)
- directly under
This utility transforms only lucene type Custom Oak Index Definitions which are present under
/oak:index. It will not transform those lucene type indexes which are created for
How it works
1. Handle Ensure Definitions
Refer to Ensure Oak Index to learn how to define and create Oak Definitions. These were created (in place of actual Oak index definitions) so that they do not wipe out the actual index data when updating the node, necessitating a reindex. AEM as a Cloud Service does not support Ensure Definitions, and hence they will be converted to Oak Index Definitions (then further migrated into AEM as a Cloud Service compatible Custom Oak Index Definitions) as per below guidelines:
- If property ignore is set to
true, ignore or skip the Ensure Definition
- Update the
- Remove any properties that are to be ignored as mentioned in OSGi configurations
- Remove subtree
/facets/jcr:contentfrom Ensure Definition
2. Handle Custom OOTB (Product) Oak Index Definition
- It will parse the Custom OOTB (Product) Oak Index Definition and fetch the associated OOTB
Index Definition corresponding to the
- It will compare the Custom OOTB Oak Index Definition to the associated OOTB Index Definition and retrieve the difference between Custom OOTB Index Definition and associated OOTB Index Definition. That difference or delta is basically customization done by the user in OOTB Oak Index Definition.
- It will validate the retrieved customization as per AEM as Cloud Service compatible OAK Index Definitions guidelines.
- It will merge validated customization of Custom OOTB Oak Index Definition to corresponding OAK Index Definition present on AEM as a Cloud Service.
Naming Conventions for Custom OOTB (Product) Oak Index Definition
"Name of the corresponding OAK Index Definition on AEM as a Cloud Service"- "latest version of this index on AEM as a Cloud Service "-"custom"-1
3. Handle Newly created Custom Oak Index Definition
- It will parse and validate the Custom Oak Index Definition as per AEM as Cloud Service compatible OAK Index Definitions guidelines.
- It will rename the Custom Oak Index Definition.
Naming Conventions for Newly created Custom Oak Index Definition :
"Name of the Custom Oak Index Definition"-"custom"-1
4. Update the filter path
This tool will update the filter path in filter.xml as well based on the new name of Custom OAK
For example, from
<filter root="/oak:index/damAssetLucene1"/> to
While it is recommended to use this tool via AIO CLI plugin for source migration, it can also be executed standalone.
It can be installed like any other
$ npm install @adobe/aem-cs-source-migration-index-converter
Adding the Module Requirement
To add the module to your
- Install the module in your project.
- Add the
const IndexConverter = require('@adobe/aem-cs-source-migration-index-converter');
Executing the Index Conveter Tool
To execute the index-converter tool locally :
git clone email@example.com:adobe/aem-cloud-service-source-migration.gitto clone the repository locally
- Navigate to the
npm installto install all the required dependencies
- Inside the
- add the required configurations to
config.yaml. Refer to Configurations sections below to learn more.
node index-converter.jsto execute the tool
./target/index/will contain the resulting restructured projects
- add the required configurations to
Specifying the Configurations
The following configurations are required for the Index Converter utility:
ensureIndexDefinitionContentPackageJcrRootPath: Absolute path to the jcr_root directory of the package containing the Ensure Index Definitions (please ignore if there are no Ensure Index Definitions).
ensureIndexDefinitionConfigPackageJcrRootPath: Absolute path to the jcr_root directory of the package containing the Ensure Index OSGi Configuration (please ignore if there are no Ensure Index Definitions).
aemVersion: Version of AEM customer is on, used to determine the baseline index definitions.
customOakIndexDirectoryPath: Path to the customer OAK Index Definition directory.
filterXMLPath: Path to the existing package
indexConverter: # Absolute path to the jcr_root directory of the package containing the Ensure Index Definitions # (please ignore if there are no Ensure Index Definitions) # eg. /Users/xyz/sampleCode/content/src/main/content/jcr_root ensureIndexDefinitionContentPackageJcrRootPath: "/Users/xyz/sampleCode/content/src/main/content/jcr_root" # Absolute path to the jcr_root directory of the package containing the Ensure Oak Index OSGI Configuration # (please ignore if there are no Ensure Index Definitions) # eg. /Users/xyz/sampleCode/CONFIG/src/main/content/jcr_root ensureIndexDefinitionConfigPackageJcrRootPath: "/Users/xyz/sampleCode/CONFIG/src/main/content/jcr_root" # Version of AEM customer is on, used to determine the baseline index definitions aemVersion: 64 # Path to the customer OAK Index Definition directory # (please ignore if there are no Custom Oak Index Definitions under /oak:index) # eg /Users/xyz/sampleCode/ui.apps/src/main/content/jcr_root/_oak_index customOakIndexDirectoryPath:"/Users/xyz/sampleCode/ui.apps/src/main/content/jcr_root/_oak_index" # Path to the existing package `filter.xml` file # eg /Users/xyz/sampleCode/ui.apps/src/main/content/META-INF/vault/filter.xml filterXMLPath:"/Users/xyz/sampleCode/ui.apps/src/main/content/META-INF/vault/filter.xml"
The tool has some known limitations (we are working on fixing them) such as :
- This utility transforms Custom Oak Index Definitions
- This utility transforms only lucene type Custom Oak Index Definitions which are present under
- It will not transform those lucene type indexes which are created for
Things that would need to be handled manually :
- copy the converted index definitions to the
- copy the index definition filter paths from the generated
Contributions are welcomed! Refer to Contributing Guide for more information.
This project is licensed under the Apache V2 License. Refer to LICENSE for more information.