How to Deploy Custom Oak Indexes in AEM as a Cloud Service

Large content repositories can make searching for specific assets a tedious task. This can significantly impact the efficiency of your content management workflows.

Enhancing search performance in AEM as a Cloud Service can be effectively achieved by utilizing custom Oak indexes. These indexes allow you to optimize the search capabilities to better match your specific content needs, offering a streamlined content management experience. By tailoring Oak indexes to your specific content needs, you can dramatically improve search performance and streamline your content management experience.

This blog post will guide you through the process of deploying custom Oak indexes in AEM as a Cloud Service. We'll cover everything you need to know, from preparing the new index definition to deploying the updated codebase. By the end, you'll be equipped to unlock the full potential of AEM as a Cloud Service's search capabilities.

What are Oak Indexes?

Oak indexes are a type of index used by AEM to enhance search performance within the content repository. Built on Apache Oak, the underlying content repository technology for AEM, these indexes are crucial for optimizing search operations. AEM as a Cloud Service supports the Lucene Oak index type, allowing you to create custom Oak indexes tailored to your specific search requirements. By leveraging these custom indexes, you can fine-tune search capabilities to better align with your content needs, ensuring a more efficient search experience.

There are three different ways to define indexes in AEM as a Cloud Service. You can choose the one that best suits your needs and preferences.

Adding a new custom index definition
Updating the existing index definition (In cloud service this can be considered as creating new version of existing index)

Naming patterns for different types of Oak index

There are three distinct naming patterns for different types of Oak indexes. These include out-of-the-box Oak indexes, `customized out-of-the-box` Oak indexes, and `fully custom indexes`. Each of these types has its own unique naming convention.

For AEM Cloud SDK, the default index definition is /oak:index/cqPageLucene. Any new version included in an AEM update will have a name like /oak:index/cqPageLucene-2.

While the default Oak index cannot be directly modified, you can easily customize it by creating a new index based on the default one. This customized index can be named /oak:index/cqPageLucene-custom-1. To customize an out-of-the-box Oak index, you need to first package it from the AEM Cloud Service environment using the CRX Package Manager. After renaming the index definition to /oak:index/cqPageLucene-custom-1, you can add your customization on top of it.

If you are creating a brand new custom index, the naming convention for this index would follow the format of acme.product-1-custom-1(<indexName>[-<productVersion>]-custom-<customVersion>). To prevent any naming conflicts, it is mandatory for fully customized indexes to have a prefix such as "acme".

How to deploy the oak index

The Oak index is a scalable and hierarchical content repository designed for use in modern cloud-based applications: Let's see how to deploy it.

Prepare the index definition

To deploy the Oak index in AEM as a Cloud Service, the index must first be prepared according to the naming conventions outlined above.

<indexName>[-<productVersion>]-custom-<customVersion>
<out-of-the-box-indexName>-custom-<customVersion>

To achieve the desired result, locate the relevant files within the "ui.apps" module, specifically within the "ui.apps/src/main/jcr_root/oak:index" directory. You will need to modify the "filter.xml" file in this directory. Here, it's crucial to ensure that existing index definitions remain unaffected. For instance, you can use a filter such as to accomplish this.

To ensure existing index definitions remain unaffected, you'll need to modify the filter.xml file located in the ui.apps/src/main/jcr_root/oak:index directory. You can achieve this by adding specific filters, such as , to exclude unwanted indexes from the deployment process.

Project configuration

For Jackrabbit Filevault Maven Plugin version 1.1.6 or later:

Add the following section to the configuration element of filevault-package-maven-plugin in your project's root pom.xml:


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

Include the vault-validation dependency in your project:


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

For ui.apps.structure/pom.xml and ui.apps/pom.xml:

In the configuration of filevault-package-maven-plugin, enable both allowIndexDefinitions and noIntermediateSaves:



<groupId>org.apache.jackrabbit</groupId>
    <artifactId>filevault-package-maven-plugin</artifactId>
    <configuration>
        <allowIndexDefinitions>true</allowIndexDefinitions>
        <properties>
            <cloudManagerTarget>none</cloudManagerTarget>
            <noIntermediateSaves>true</noIntermediateSaves>
        </properties>
        </configuration>
</plugin>

Add an oak:index filter to ui.apps.structure/pom.xml:


 <filter>
<root>/oak:index</root>
<filter>

With these configurations, your custom Oak index definitions will be deployed during the Maven build process.

Changing the index:

To update an index definition, create a new index reflecting the desired changes. For example, to modify the existing index ‘/oak/init.product-1-custom-1’, create a new index named ‘/oak/init.product-1-custom-2’ with the updated settings.

The previous application version will still utilize the original index, whereas the updated version will employ the newly created index.

Removing the unwanted index

Only custom indexes can be removed. Here's how to delete a custom index:

Define an empty index with a new name but referencing the existing custom index you want to remove. For example, to delete /oak:index/init.product-1-custom-1, create an empty index named /oak:index/init.product-1-custom-2.
The system will automatically remove the old version (/oak:index/init.product-1-custom-1) after processing the empty index definition.
Eventually, the empty index (/oak:index/init.product-1-custom-2) will also be removed.

Here's an example of an empty index definition:


<init.product-1-custom-2
        jcr:primaryType="oak:QueryIndexDefinition"
        async="async"
        compatVersion="2"
        includedPaths="/dummy"
        queryPaths="/dummy"
        type="lucene">
        <indexRules jcr:primaryType="nt:unstructured">
            <rep:root jcr:primaryType="nt:unstructured">
                <properties jcr:primaryType="nt:unstructured">
                    <dummy
                        jcr:primaryType="nt:unstructured"
                        name="dummy"
                        propertyIndex="{Boolean}true"/>
                </properties>
            </rep:root>
        </indexRules>
</init.product-1-custom-2>

How can Initialyze assist with deploying custom Oak Indexes in AEM as a Cloud Service?

Deploying custom Oak Indexes in AEM as a Cloud Service is a crucial task for optimizing search and query performance within your Adobe Experience Manager environment. Throughout this article, we've delved into the importance of Oak Indexes, how they function, and the step-by-step process for deploying them. However, it's important to recognize that while the process may appear straightforward, it is inherently technical and requires a deep understanding of AEM's architecture and Cloud Service intricacies.

Given the complexity involved, partnering with certified AEM experts can significantly streamline the deployment process. At Initialyze, we bring extensive experience and expertise to ensure your custom Oak Index deployment is not only successful but also optimized for your specific needs. From strategy formulation to post-deployment support, our team is equipped to handle every aspect of the deployment lifecycle. Connect with our Adobe AEM experts and let us help you navigate the complexities of AEM Cloud Service, ensuring a seamless and efficient deployment of your custom Oak Indexes.