Index Converter Utility 1.2.5: Merge Logic for OOTB Index Customization (AMS AEM 6.5.21 to AEMaaCS Migration)

[Bhuwan_B]

I'm migrating Oak:index from AMS AEM 6.5.21 to AEM as a Cloud Service using the latest Index Converter utility (v1.2.5) and have observed that the utility merges some custom indexes with existing OOTB index definitions. For example, my custom index "abc" is being merged into the customization of "cqPageLucene-1" instead of creating a standalone custom index.

Q1. What criteria the utility uses to decide merging vs. standalone creation ?

Q2. Since these indexes serve different stakeholders with distinct requirements, would it be better to create them as fully custom indexes (e.g., customIndexName-custom-1) instead of following the utility's merge recommendation with existing OOTB index definitions (is that supported ?)

Please share best practices for overriding Index Converter utility decisions, Experiences with similar migration scenarios.

[giuseppebag]

The Index Converter utility determines merge vs. standalone creation based on whether the custom index is a modification of an existing OOTB index or a newly created custom index.​

Q1: Merge Criteria

Merges occur when the custom index name matches or is derived from an existing OOTB index (like cqPageLucene or damAssetLucene). The utility performs a three-way merge comparing the custom OOTB index, original OOTB baseline, and new AEM Cloud Service version, extracting the customizations and merging them using the naming convention: <OOTBIndexName>-<productVersion>-custom-<customVersion>.​

Standalone indexes are created when the index definition is entirely new and doesn't correspond to any OOTB index. These are renamed as: <indexName>-custom-1.​

Q2: Custom Indexes vs. Merge

Creating fully custom indexes is supported but should be a last resort. Adobe recommends customizing OOTB indexes when queries operate on the same node types, as this is easier to maintain during upgrades.​

Create fully custom indexes only when OOTB customization doesn't work or when indexing completely different node types. The critical rule: avoid creating custom indexes on the same node type as OOTB indexes, as this has caused performance and functional issues (source here) :