How to trigger Oak Index via AEM JMX to start the process of applying the changed index definitions

[#1]

How to trigger Oak Index via AEM JMX to start the process of applying the changed index definitions 

by Debal Das

We are all aware of the power of AEM Oak indexing, but we also have struggled with it.

I will use examples to discuss struggles and different use cases today. Before directly jumping into the issues and solutions, let me give you the context.

In our project AEM 6.5 is currently in use with ACS AEM commons installed and it was required to update and delete the existing custom Oak indexes.

To ensure successful update and deletion, we have created Ensure Definitions for each Oak Index in our project.

Unfortunately, after the deployment, we noticed that the update and deletion did not execute. To understand the cause of failure I was looking into the error.log and noticed index update and deletion didn’t get trigged via Ensure Definitions.

Once again, I reviewed the properties and values in Ensure Definition, and simultaneously, I checked if anyone had encountered similar issues and discussed ways to fix them.

Luckily I got a great article written by Jörg and this article helps me to know how to trigger Oak Index via AEM JMX to start process of applying the changed index definitions.

Now I will talk about different use cases here.

Use case:1 If Oak Index is same as Ensure Definition -

Sharing a sample Ensure Definition associated with custom index below and the data captured from .content.xml -

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:oak="http://jackrabbit.apache.org/oak/ns/1.0" xmlns:dam="http://www.day.com/dam/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
    jcr:primaryType="oak:Unstructured"
    async="async"
    compatVersion="{Long}2"
    evaluatePathRestrictions="{Boolean}true"
    forceIndex="{Boolean}true"
    includedPaths="[/content/dam]"
    type="lucene">
    <indexRules jcr:primaryType="nt:unstructured">
        <dam:Asset
            jcr:primaryType="nt:unstructured"
            includePropertyTypes="all">
            <properties jcr:primaryType="nt:unstructured">
                <contentFragment
                    jcr:primaryType="nt:unstructured"
                    analyzed="{Boolean}true"
                    name="jcr:content/contentFragment"
                    propertyIndex="{Boolean}true"
                    useInExcerpt="{Boolean}true"
                    useInSpellcheck="{Boolean}true"/>
            </properties>
        </dam:Asset>
    </indexRules>
</jcr:root>

.content.xml details associated with custom oak index has been shown below -

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:oak="http://jackrabbit.apache.org/oak/ns/1.0" xmlns:dam="http://www.day.com/dam/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" xmlns:rep="internal"
    jcr:mixinTypes="[rep:AccessControllable]"
    jcr:primaryType="nt:unstructured">
    <cfIndex
        jcr:lastModified="{Date}2024-01-28T13:23:52.981+05:30"
        jcr:lastModifiedBy="Ensure Oak Index"
        jcr:primaryType="oak:QueryIndexDefinition"
        async="async"
        compatVersion="{Long}2"
        evaluatePathRestrictions="{Boolean}true"
        forceIndex="{Boolean}true"
        includedPaths="[/content/dam]"
        reindex="{Boolean}false"
        reindexCount="{Long}2"
        seed="{Long}-2039789717445852746"
        type="lucene">
        <indexRules jcr:primaryType="nt:unstructured">
            <dam:Asset
                jcr:primaryType="nt:unstructured"
                includePropertyTypes="all">
                <properties jcr:primaryType="nt:unstructured">
                    <contentFragment
                        jcr:primaryType="nt:unstructured"
                        analyzed="{Boolean}true"
                        name="jcr:content/contentFragment"
                        propertyIndex="{Boolean}true"
                        useInExcerpt="{Boolean}true"
                        useInSpellcheck="{Boolean}true"/>
                </properties>
            </dam:Asset>
        </indexRules>
    </cfIndex>
</jcr:root>

In this case there won’t be any change Oak Index at [ /oak:index/customindex ] and the same information has been captured at error.log -

28.01.2024 14:50:19.987 *INFO* [sling-default-4-EnsureOakIndex( /apps/demo/oak-index => /oak:index )] com.adobe.acs.commons.oak.impl.EnsureOakIndexJobHandler Skipping update... Oak Index at [ /oak:index/cfIndex ] is the same as [ /apps/demo/oak-index/cfIndex ]

Use case:2 Update the custom oak index with Ensure Definition changes -

Sharing updated Ensure Definition associated with custom index below and the data captured from .content.xml -

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:oak="http://jackrabbit.apache.org/oak/ns/1.0" xmlns:dam="http://www.day.com/dam/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
    jcr:primaryType="oak:Unstructured"
    async="async"
    compatVersion="{Long}2"
    evaluatePathRestrictions="{Boolean}true"
    forceIndex="{Boolean}true"
    includedPaths="[/content/dam]"
    type="lucene">
    <indexRules jcr:primaryType="nt:unstructured">
        <dam:Asset
            jcr:primaryType="nt:unstructured"
            includePropertyTypes="all">
            <properties jcr:primaryType="nt:unstructured">
                <contentFragment
                    jcr:primaryType="nt:unstructured"
                    analyzed="{Boolean}true"
                    name="jcr:content/contentFragment"
                    propertyIndex="{Boolean}true"
                    useInExcerpt="{Boolean}true"
                    useInSpellcheck="{Boolean}true"/>
                <title
                    jcr:primaryType="nt:unstructured"
                    analyzed="{Boolean}true"
                    name="jcr:content/model/jcr:title"
                    propertyIndex="{Boolean}true"
                    useInExcerpt="{Boolean}true"
                    useInSpellcheck="{Boolean}true"/>
            </properties>
        </dam:Asset>
    </indexRules>
</jcr:root>

In this case we will see the following message: updated Oak Index at [ /oak:index/customindex ] with configuration at error.log file just like the one below -

28.01.2024 18:33:23.973 *WARN* [sling-default-4-EnsureOakIndex( /apps/demo/oak-index => /oak:index )] com.adobe.acs.commons.oak.impl.EnsureOakIndexJobHandler Updated Oak Index at [ /oak:index/cfIndex ] with configuration [ /apps/demo/oak-index/cfIndex ], but no reindex requested!
28.01.2024 18:33:23.976 *INFO* [sling-default-4-EnsureOakIndex( /apps/demo/oak-index => /oak:index )] com.adobe.acs.commons.oak.impl.EnsureOakIndexJobHandler Saving all CREATE, UPDATES, and RE-INDEXES, re-indexing may start now.

Use case:3 Delete the Oak Index via Ensure Definition -

To delete the existing custom oak index I have updated the Ensure Definition with following entries -

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:oak="http://jackrabbit.apache.org/oak/ns/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="oak:Unstructured"
    async="async"
    compatVersion="{Long}2"
    delete="{Boolean}true"
    type="lucene"/>

The data captured from .content.xml

Now if I run the Ensure Oak Index via JMX , then we will see delete operation specific details at error.log file as show below and our custom oak index won’t be available under /oak:index -

28.01.2024 19:08:33.468 *INFO* [qtp631170156-3237] com.adobe.acs.commons.oak.impl.EnsureOakIndex Ensuring Oak Indexes [ /apps/demo/oak-index ~> /oak:index ]
28.01.2024 19:08:33.469 *INFO* [qtp631170156-3237] com.adobe.acs.commons.oak.impl.EnsureOakIndex Job scheduled for ensuring Oak Indexes [ /apps/demo/oak-index ~> /oak:index ]
28.01.2024 19:08:33.472 *INFO* [sling-default-1-EnsureOakIndex( /apps/demo/oak-index => /oak:index )] com.adobe.acs.commons.oak.impl.EnsureOakIndexJobHandler Saving all DELETES, IGNORES, and DISABLES to [ /oak:index ]

How to trigger Oak Index via AEM JMX to start the process of applying the changed index definitions -

Step 1 : Please select the JMX console using following URL :

<AEM-instance>/system/console/jmx

Step 2: Then search for “Ensure Oak Index” in JMX console as shown below

Step 3: Click on Ensure Oak Index will redirect us on following page -

Step 4: The click on following operation: ensure(boolean force, java.lang.String ensureDefinitionsPath) and I need to enter my application specific ensure definition path and set the boolean flag as true as shown below -

Step 5: Next click on Invoke button , we will be seeing 1 as response.

References below -

• https://cqdump.joerghoh.de/2018/07/19/why-you-need-to-start-ensureoakindex-manually/
• https://adobe-consulting-services.github.io/acs-aem-commons/features/ensure-oak-index/index.html