The topic is about Oak index migration to make it compatible for AEMaaCS.
For sure, Index Convertor tool is available to convert the indexes to make it compatible for AEMaaCS.
However, most of the times, we tend to include/modify only custom index without any change in OOTB indexes and in that case there might not be the need of converting indexes as it might already works the same in cloud as well. Obviously, follow the naming convention as described in official documentation for AEM as cloud Service.
https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/operations/indexing...
But, this is not about index convertor. It's about putting it at right place in project so it gets deployed on cloud via CM pipeline.
There're couple of things I came across while I was working on migration that might be helpful if you run into same situation as I had:
1. Having the Oak index as separate package -> In my project, oak was index was included as a separate package to maintain the modularity and when we try to follow the same with cloud, it just fails. I missed the point written in official doc stating that
“You need to prepare a new index definition package that contains the actual index definition, following this naming pattern:
<indexName>[-<productVersion>]-custom-<customVersion>
which then needs to go under ui.apps/src/main/content/jcr_root. Sub root folders are not supported as of now.”
So, it literally has to be part of ui.apps package in order successfully deploy on Cloud.
2. ui.apps package type and core dependency i.e. aem-sdk or uber-jar -> In few projects I’ve seen that it went to cloud without upgrading dependencies to uber-jar and having oak index package as part of ui.apps. Well, it fully worked that time with the change that the packageType must be mixed in order to deploy oak index with ui.apps.
<packageType>mixed</packageType>
Note: It did work back then with package type “mixed” while project was running with “uber-jar”. Not sure if there has been changes in recent now that might not allow.
3. Running with aem-sdk-api and (filevault version < 1.3.0) -> Official documentation states:
”There is a known issue with Jackrabbit Filevault Maven Package Plugin version 1.1.0 which does not allow you to add oak:index to modules of <packageType>application</packageType>. You should update to a more recent version of that plugin“
Well, this issue isn’t solved even with above versions as well and fixed only with version 1.3.0 which means if you’re using any version of file vault plugin lesser than 1.3.0, it won’t allow you to build package with package type application. So, as a workaround there’re 2 ways. Either you upgrade the file vault version to 1.3.0 or add updated validator plugin to allow to work with package type application.
Code snippet:
With upgraded version of fileVault:
<plugin>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>filevault-package-maven-plugin</artifactId>
<extensions>true</extensions>
<version>1.3.0</version>
<configuration>
<name>${contentPackage.name}</name>
<group>${contentPackage.group}</group>
<packageType>application</packageType>
<allowIndexDefinitions>true</allowIndexDefinitions>
<validatorsSettings>
<jackrabbit-filter>
<options>
<validRoots>
/apps/<project>,
/oak:index
</validRoots>
</options>
</jackrabbit-filter>
<jackrabbit-packagetype>
<options>
<immutableRootNodeNames>apps,libs,oak:index</immutableRootNodeNames>
</options>
</jackrabbit-packagetype>
</validatorsSettings>
<properties>
<noIntermediateSaves>true</noIntermediateSaves>
</properties>
</configuration>
</plugin>
With old version of file vault:
<plugin>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>filevault-package-maven-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<name>${contentPackage.name}</name>
<group>${contentPackage.group}</group>
<packageType>application</packageType>
<allowIndexDefinitions>true</allowIndexDefinitions>
<validatorsSettings>
<jackrabbit-filter>
<options>
<validRoots>
/apps/<project>,
/oak:index
</validRoots>
</options>
</jackrabbit-filter>
<jackrabbit-packagetype>
<options>
<immutableRootNodeNames>apps,libs,oak:index</immutableRootNodeNames>
</options>
</jackrabbit-packagetype>
</validatorsSettings>
<dependencies>
<dependency>
<groupId>org.apache.jackrabbit.vault</groupId>
<artifactId>vault-validation</artifactId>
<version>3.6.0</version>
</dependency>
</dependencies>
<properties>
<noIntermediateSaves>true</noIntermediateSaves>
</properties>
</configuration>
</plugin>
If you’ll compare the above 2 snippets, you’d find the later one is using “vault-validation” dependency added in file vault plugin and that’s the dependency responsible to validate ui.apps package with oak index. Previous version of file vault plugin uses old version of “vault-validation” that doesn’t have this feature included.
2 more key points to pay attention from above given snippet is that:
- immutableRootNodeNames -> It must be there with value added (as there in code snippet) to have successful build. Official documentation didn’t mention it and that’s where I struggled to figure out why it’s not building package even with latest file vault plugin or after upgrading version of vault validation. Since oak index are going to build within ui.apps and ui.apps and libs are immutable, package expect oak:index to be immutable as well and that’s why it has be added in <jackrabbit-packagetype>
- noIntermediateSaves -> As described in official documentation,
Any content package containing index definitions should have the following property set in in the properties file of the content package, located at /META-INF/vault/properties.xml: noIntermediateSaves=true
Earlier, I was adding the properties.xml in vault directory with noIntermediateSaves as I didn’t know that just this property can be added directly from plugin itself without creating a file. File Vault plugin auto generates properties.xml and only the noIntermediateSaves should be added on the top of it without adding the file manually (to avoid override).
If you’re also planning to migrate to AEMaaCS or already in phase and get any issues specific to Oak index, then I hope this article might be able to help you and save time.
