Deploying Oak Indexes to AEM as a Cloud Service

Hi everyone! 

I was struggling a bit with this topic, so figured I'd post a discussion to help any others who are having issues.  The setup to load new or updated oak indexes into the cloud is fairly simple, and there's already documentation on how to do this...however, with the latest version of the filevault-package-maven-plugin plugin (v 1.0.5 - 1.2.2), you will get validation errors if you try to include an oak index in your ui.apps module.  If you've tried doing this, you have probably seen an error like

The info on how to set up oak indexes in an AEMaaCS codebase is here: https://experienceleague.adobe.com/docs/experience-manager-cloud-service/operations/indexing.html?lang=en

Although the documentation is correct as far as how to structure the index in the codebase, it just doesn't take into account that the jackrabbit-packagetype validator will not let you deploy the code as it stands today on December 2, 2021.  Note that this will likely be fixed in the not so distant future with an update to the filevault plugin to use the latest validator module (where this is fixed), so this article might not be relevant for too much longer (hopefully!).  The answer I've seen on the forums has been to downgrade the filevault plugin to version 1.0.4, but this comes with its own set of problems as there are bugs in that version that will prevent you from doing things in your filter.xml files that you should be able to do.

So, if you want to stick with the current version of the filevault plugin, and still be able to deploy oak indexes to the cloud, this article is for you, so read on!

The latest versions of the validator do take oak indexes into account (3.5.x) and you can override the filevault plugin to use a newer version of the validator.  Because filevault-package-maven-plugin version 1.1.6 does not include the latest validator, you'll have to override that one dependency.  To do this, in the root pom.xml, you need to update the validator dependency within the filevault plugin:

<dependency>
    <groupId>org.apache.jackrabbit.vault</groupId>
    <artifactId>vault-validation</artifactId>
    <version>3.5.6</version>
</dependency>

 and then you also need to include the custom config that allows the oak:index node:

<validatorsSettings>
    <jackrabbit-packagetype>
        <options>
            <immutableRootNodeNames>apps,libs,oak:index</immutableRootNodeNames>
        </options>
    </jackrabbit-packagetype>
</validatorSettings>

By doing both of these things, you should be able to continue using version 1.1.6+ of the filevault plugin, and still deploy your oak indexes without downgrading.

Here's the full plugin configuration:

<plugin>
    <groupId>org.apache.jackrabbit</groupId>
    <artifactId>filevault-package-maven-plugin</artifactId>
    <extensions>true</extensions>
    <version>1.1.6</version>
    <configuration>
        <filterSource>src/main/content/META-INF/vault/filter.xml</filterSource>
        <validatorsSettings>
            <jackrabbit-packagetype>
                <options>
                    <immutableRootNodeNames>apps,libs,oak:index</immutableRootNodeNames>
                </options>
            </jackrabbit-packagetype>
            <jackrabbit-nodetypes>
                <options>
                    <!-- use the nodetypes and namespaces from the aem-nodetypes.jar provided in the plugin dependencies -->
                    <cnds>tccl:aem.cnd</cnds>
                </options>
            </jackrabbit-nodetypes>
        </validatorsSettings>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.apache.jackrabbit.vault</groupId>
            <artifactId>vault-validation</artifactId>
            <version>3.5.6</version>
        </dependency>
        <dependency>
            <groupId>biz.netcentric.aem</groupId>
            <artifactId>aem-nodetypes</artifactId>
            <version>6.5.7.0</version>
        </dependency>
    </dependencies>
</plugin>

Also note that you'll still need to add 

<allowIndexDefinitions>true</allowIndexDefinitions>

 to your ui.apps/pom.xml file.  You won't need this with the most current version of the package type validator, but you will for the oak index validator.

Hope this helps!

Best,

Evan