Skip to main content

Extending the AEM Connector

The AEM connector provides a powerful extension system that lets you customize how content is extracted, transformed, and indexed from Adobe Experience Manager. Extensions are Java classes that implement interfaces from the aem-commons library, published on Maven Central.


Maven Dependency​

To create custom AEM extensions, add aem-commons to your project:

<!-- Source: https://mvnrepository.com/artifact/com.viglet.dumont/aem-commons -->
<dependency>
<groupId>com.viglet.dumont</groupId>
<artifactId>aem-commons</artifactId>
<version>2026.2.3</version>
<scope>compile</scope>
</dependency>

Extension Interfaces​

The AEM connector provides these extension interfaces and base classes:

Class / InterfacePurposeConfig field
DumAemExtAttributeInterfaceCustom logic for extracting or transforming individual field valuesattributes[].className or sourceAttrs[].className
DumAemExtContentInterfaceExtract additional content from AEM pages (e.g., .model.json)models[].className
DumAemExtModelJsonBase<T>Recommended abstract base class for .model.json extractors, handles fetch, parse, and error handling automatically. Prefer this over implementing DumAemExtContentInterface directly.models[].className
DumAemExtDeltaDateInterfaceCustom delta date resolution for incremental indexingsources[].deltaClass
DumAemExtUrlAttributeInterfaceSpecialized URL handling with ID extraction (extends DumAemExtAttributeInterface)attributes[].className

DumAemExtAttributeInterface​

The most commonly used extension. Implement this to transform or extract individual attribute values with custom logic.

import com.viglet.dumont.connector.aem.commons.ext.DumAemExtAttributeInterface;
import com.viglet.dumont.connector.aem.commons.DumAemObject;
import com.viglet.dumont.connector.aem.commons.context.DumAemConfiguration;
import com.viglet.dumont.connector.aem.commons.mappers.*;
import com.viglet.turing.client.sn.TurMultiValue;

public class MyCustomAttribute implements DumAemExtAttributeInterface {

@Override
public TurMultiValue consume(
DumAemTargetAttr dumAemTargetAttr,
DumAemSourceAttr dumAemSourceAttr,
DumAemObject aemObject,
DumAemConfiguration dumAemConfiguration
) {
// Example: extract a custom property and transform it
String rawValue = aemObject.getAttributes()
.get("myProperty").toString();
return TurMultiValue.singleItem(rawValue.toUpperCase());
}
}

Parameters:

ParameterDescription
DumAemTargetAttrTarget search field being populated (name, type)
DumAemSourceAttrSource AEM property definition (name, className)
DumAemObjectAEM content node: path, title, template, jcrNode, jcrContentNode, lastModified, attributes
DumAemConfigurationConnection config: url, username, rootPath, authorSNSite, publishSNSite, providerName

Built-in implementations:

ClassWhat it does
DumAemExtContentIdReturns the AEM page path as the document ID
DumAemExtContentUrlBuilds the full URL from the page path and URL prefix config
DumAemExtContentTagsFetches tags from the /jcr:content.tags.json endpoint
DumAemExtCreationDateReturns the jcr:created date
DumAemExtModificationDateReturns the cq:lastModified or jcr:lastModified date
DumAemExtPublicationDateReturns the last replication date
DumAemExtHtml2TextConverts HTML content to plain text
DumAemExtPageComponentsExtracts text from responsive grid components
DumAemExtTypeNameReturns the content type name
DumAemExtSourceAppsReturns the provider name from configuration
DumAemExtSiteNameReturns the site name

DumAemExtContentInterface​

Implement this to fetch additional content from AEM, for example, calling the .model.json Sling Model exporter to get structured data.

import com.viglet.dumont.connector.aem.commons.ext.DumAemExtContentInterface;
import com.viglet.dumont.connector.aem.commons.bean.DumAemAttrMap;

public class MyModelJsonExtractor implements DumAemExtContentInterface {

@Override
public DumAemAttrMap consume(
DumAemObject aemObject,
DumAemConfiguration dumAemConfiguration
) {
DumAemAttrMap result = new DumAemAttrMap();

// Fetch the .model.json endpoint
String url = dumAemConfiguration.getUrl()
+ aemObject.getPath() + ".model.json";
// ... HTTP call to get JSON ...

result.append("fragmentPath", "/content/dam/fragment");
return result;
}
}

Referenced in the models[].className field of the configuration JSON.

Prefer the abstract base class

For model.json extractors, use DumAemExtModelJsonBase instead of implementing this interface directly. See Model JSON Base Class below.


DumAemExtDeltaDateInterface​

Customize how the connector determines the "last modified" date for incremental indexing.

import com.viglet.dumont.connector.aem.commons.ext.DumAemExtDeltaDateInterface;

public class MyDeltaDate implements DumAemExtDeltaDateInterface {

@Override
public Date consume(
DumAemObject aemObject,
DumAemConfiguration dumAemConfiguration
) {
return Optional.ofNullable(aemObject.getLastModified())
.map(Calendar::getTime)
.orElse(null);
}
}

Referenced in the sources[].deltaClass field of the configuration JSON.



Model JSON Base Class & Fluent API​

When your extension extracts data from .model.json, you can use DumAemExtModelJsonBase and the fluent DumAemComponentMapper API to eliminate boilerplate and write concise, declarative extractors.

DumAemExtModelJsonBase​

An abstract class that handles the entire fetch → parse → error-handling lifecycle. Subclasses declare the model class and then choose how extraction is expressed:

MethodPurpose
getModelClass()Returns the root bean class for Jackson deserialization
extractAttributes(model, query, aemObject, attrValues)Extracts data from the parsed model and populates the attribute map: the direct style, shown below
componentExtractors()Registers small single-concern extractors the base composes per page, instead of overriding extractAttributes (see Composing Extractors)
contentTypes()Declares one schema and one extractor composition per content type, routed by template (see Content Types and Recipes)

Minimal example:

import com.viglet.dumont.connector.aem.commons.ext.DumAemExtModelJsonBase;
import com.viglet.dumont.connector.aem.commons.ext.DumAemModelJsonQuery;

public class MyModelJsonExtractor extends DumAemExtModelJsonBase<MyModel> {

@Override
protected Class<MyModel> getModelClass() {
return MyModel.class;
}

@Override
protected void extractAttributes(MyModel model, DumAemModelJsonQuery query,
DumAemObject aemObject, DumAemAttrMap attrValues) {
attrValues.set("title", model.getTitle())
.set("description", model.getDescription());
}
}

This replaces all the boilerplate of building the URL, calling DumAemCommonsUtils.getResponseBody(), creating the ObjectMapper, handling IOException, and wrapping results in Optional.

Composing Extractors​

One extractAttributes per source grows into a single method that knows every component on every template. Register DumAemComponentExtractors instead and the base runs them in order, each one covering a single component and testable on its own:

public class MyModelJsonExtractor extends DumAemExtModelJsonBase<MyModel> {

@Override
protected Class<MyModel> getModelClass() {
return MyModel.class;
}

@Override
protected List<DumAemComponentExtractor<MyModel>> componentExtractors() {
return List.of(new MyPageExtractor(), new MyBannerExtractor(), new MyNewsExtractor());
}
}

A DumAemComponentExtractor is a functional interface with the same signature as extractAttributes:

public class MyNewsExtractor implements DumAemComponentExtractor<MyModel> {

@Override
public void contribute(MyModel model, DumAemModelJsonQuery query,
DumAemObject aemObject, DumAemAttrMap attrValues) {
query.component("my-app/components/news", MyNews.class)
.first()
.attr("newsDate", MyNews::getDate)
.into(attrValues);
}
}

Overriding extractAttributes directly still works and is unchanged; the two styles are alternatives, not layers.

Extractors must be stateless during extraction

Your extension is resolved once and cached, then reused across threads: with dumont.reactive.indexing=true several pages are extracted in parallel through the same instance. Keep per-page data in local variables and in the DumAemAttrMap you are handed; an extractor holding per-page mutable instance state will produce corrupted attributes under load. This applies to both styles.

Content Types and Recipes​

One source often indexes several kinds of page (an article, an event, a course) that share little. contentTypes() replaces "one source, one schema" with one schema and one extractor composition per type, and templateName() says which AEM template a page came from so the base can route it:

@Override
protected List<DumAemContentType<MyModel>> contentTypes() {
return List.of(
DumAemContentType.<MyModel>builder("article")
.fields(DumAemContentTypeField.text("headline"), DumAemContentTypeField.facet("topic"))
.extractors(new MyArticleExtractor())
.build(),
DumAemContentType.<MyModel>builder("event")
.fields(DumAemContentTypeField.text("venue"), DumAemContentTypeField.string("startsAt"))
.extractors(new MyEventExtractor())
.build());
}

@Override
protected String templateName(MyModel model, DumAemObject aemObject) {
return model.getTemplateName();
}

Only the resolved type's extractors run for a given page, and the connector reports field coverage per content type rather than only per source. Pages whose template resolves to no declared type fall back to the flat componentExtractors(). templateNameAliases() collapses several template names onto one canonical type.

When the same content type is indexed by several institutions or sites, declare it once as a recipe: a versioned, parameterized content type applied by reference instead of copied:

// Shared, registered once: name@version, e.g. course-offer@2
DumAemRecipeLibrary library = new DumAemRecipeLibrary().register(courseOfferRecipe());

public class MySiteExtractor extends DumAemExtModelJsonBase<MyModel> {

private final DumAemRecipeContentTypes<MyModel> recipes =
DumAemRecipeContentTypes.<MyModel>builder(library)
.bind(DumAemRecipeRef.latest("course-offer"),
DumAemRecipeParameters.builder("my-site").template("curso")
.param("componentBasePath", "my-app/components").build())
.build();

@Override
protected List<DumAemContentType<MyModel>> contentTypes() {
return recipes.contentTypes();
}

@Override
protected Map<String, String> templateNameAliases() {
return recipes.templateNameAliases();
}
}

Each site supplies its own DumAemRecipeParameters (its template names, its component resource-type prefix), and both methods resolve the recipe from the library fresh on every call. Registering a higher version therefore re-applies the new fields and extractors to every site that bound the recipe by latest, on the next extraction and without touching any extension; a site that pinned course-offer@1 stays on it. A binding whose recipe is not registered is skipped, so one missing recipe never breaks the others.

DumAemModelJsonQuery​

A utility class that simplifies finding AEM components inside the model.json by their :type using JsonPath. It replaces the repetitive pattern of JsonPath.parse() + Filter.filter() + MAPPER.convertValue().

// Before (repeated for every component type):
DocumentContext jsonContext = JsonPath.parse(json);
Object jsonDetails = jsonContext.read("$..[?]", Filter.filter(
Criteria.where(":type").eq("my-app/components/news")));
List<MyNews> news = MAPPER.convertValue(jsonDetails, new TypeReference<>() {});
news.stream().filter(Objects::nonNull).findFirst().ifPresent(item -> { ... });

// After (one line):
query.findFirstByComponentType("my-app/components/news", MyNews.class)
.ifPresent(item -> { ... });

Available methods:

MethodDescription
findByComponentType(type, class)Returns all components matching the :type as a typed list
findFirstByComponentType(type, class)Returns the first matching component as Optional<T>
component(type, class)Returns a DumAemComponentMapper<T> for fluent attribute mapping

DumAemComponentMapper: Fluent API​

The most concise way to extract component data. Chain .attr() calls to declaratively map fields, use .also() for custom logic, and .via() to navigate into nested objects.

Basic: find first component, map fields​

query.component("my-app/components/news", MyNews.class)
.first()
.attr("date", MyNews::getDate)
.attr("author", MyNews::getAuthor)
.into(attrValues);
query.component("my-app/components/teacher", Teacher.class)
.first()
.via(Teacher::getProfile)
.attr("name", Profile::getFullName)
.attr("bio", Profile::getBiography)
.into(attrValues);

Mix declarative and custom logic with .also()​

Use .also() when you need conditional logic, computed values, or fallbacks alongside declarative mappings:

query.component("my-app/components/banner", Banner.class)
.first()
.also((banner, attrs) -> {
// Fallback logic: use background image, or color if not available
String image = banner.getBackgroundImage() != null
? banner.getBackgroundImage()
: banner.getBackgroundColor();
attrs.set("image", image);
})
.attr("title", Banner::getTitle)
.attr("richText", Banner::getRichText)
.into(attrValues);

Process all components of a type​

query.component("my-app/components/carousel", Instructor.class)
.all()
.also((instructor, attrs) -> {
attrs.append("text", instructor.getName())
.append("text", instructor.getBio());
})
.into(attrValues);

Fluent API: complete reference​

MethodDescription
.first()Only process the first matching component
.all()Process all matching components (default)
.attr(name, getter)Map a field to a target attribute (override = true)
.attr(name, getter, override)Map a field with explicit override flag
.also(biConsumer)Execute custom logic for each processed component
.via(navigator)Navigate into a nested object, returns a new mapper of the nested type
.into(attrValues)Execute all accumulated mappings and actions
.findFirst()Returns Optional<T> for custom processing outside the chain
.stream()Returns a Stream<T> for custom processing outside the chain

Base Class Helpers​

DumAemExtModelJsonBase provides utility methods that address common patterns:

lastModifiedDate(aemObject)​

Extracts the last modified date, falling back to the creation date:

attrValues.append("date", lastModifiedDate(aemObject));

resolveTemplateName(templateName) + templateNameAliases()​

Normalizes AEM template names using a declarative alias map. Override templateNameAliases() to define your mappings:

@Override
protected Map<String, String> templateNameAliases() {
return Map.of(
"contact-page", "institutional",
"sub-home", "institutional",
"news-article", "news",
"knowledge-article", "news",
"webinar", "event"
);
}

Then use resolveTemplateName() in your extractor:

attrValues.set("templateName", resolveTemplateName(model.getTemplateName()));
// "contact-page" → "institutional", "news-article" → "news", etc.

Complete Example​

Here is a complete extractor using all the abstractions:

public class MyPortalModelJson extends DumAemExtModelJsonBase<MyPortalModel> {

@Override
protected Class<MyPortalModel> getModelClass() {
return MyPortalModel.class;
}

@Override
protected Map<String, String> templateNameAliases() {
return Map.of(
"contact-page", "institutional",
"news-article", "news"
);
}

@Override
protected void extractAttributes(MyPortalModel model, DumAemModelJsonQuery query,
DumAemObject aemObject, DumAemAttrMap attrValues) {
// Root metadata
attrValues.append("date", lastModifiedDate(aemObject))
.set("fragmentPath", model.getFragmentPath())
.set("templateName", resolveTemplateName(model.getTemplateName()));

// News component
query.component("my-portal/components/news", MyNews.class)
.first()
.attr("date", MyNews::getDate)
.into(attrValues);

// Banner with image fallback
query.component("my-portal/components/banner", MyBanner.class)
.first()
.also((banner, attrs) -> {
String image = banner.getImage() != null
? banner.getImage() : banner.getFallbackImage();
attrs.set("image", image);
})
.attr("richText", MyBanner::getRichText)
.attr("modificationDate", MyBanner::getAuthorDate)
.into(attrValues);

// Event with nested address logic
query.component("my-portal/components/event", MyEvent.class)
.first()
.attr("date", MyEvent::getDate)
.attr("endDate", MyEvent::getEndDate)
.also((event, attrs) ->
attrs.append("text",
"%s %s".formatted(event.getCity(), event.getAddress())))
.into(attrValues);

// Teacher: navigate into elements
query.component("my-portal/components/teacher", MyTeacher.class)
.first()
.via(MyTeacher::getElements)
.attr("title", Elements::getName)
.attr("abstract", Elements::getQualification)
.attr("image", Elements::getPhoto)
.into(attrValues);
}
}

DumAemAttrMap: API Reference​

DumAemAttrMap is the core data structure for collecting extracted attributes. It extends HashMap<String, TurMultiValue> and provides typed methods for adding values safely (null values are silently ignored).

The fluent methods provide concise, chainable calls with clear semantics. They accept any supported type (String, Date, Boolean, Integer, Long, Double, Float, TurMultiValue) and dispatch automatically.

set(name, value): replace​

Sets a value, replacing any existing value for this attribute:

attrValues
.set("title", model.getTitle())
.set("date", model.getDate())
.set("active", true);
append(name, value): merge​

Appends a value, merging with any existing value. If the attribute does not yet exist, it is created:

attrValues
.append("text", teacher.getBio())
.append("text", teacher.getName());
setIfAbsent(name, value): conditional​

Sets a value only if the attribute does not already exist in the map. Replaces the common if (!attrValues.containsKey(...)) pattern:

attrValues.setIfAbsent("abstract", description);
setAll(name, list) / appendAll(name, list): string collections​
attrValues
.setAll("tags", List.of("news", "tech", "java"))
.appendAll("categories", additionalCategories);
setAllDates(name, list) / appendAllDates(name, list): date collections​
attrValues.setAllDates("eventDates", List.of(startDate, endDate));
of(name, value): static factory​

Creates a new map with a single attribute:

return DumAemAttrMap.of("title", model.getTitle());

Fluent API: Quick Reference​

MethodBehaviorReturns
set(name, value)Replace existing valuethis
append(name, value)Merge with existing valuethis
setIfAbsent(name, value)Set only if key is absentthis
setAll(name, List<String>)Replace with string collectionthis
appendAll(name, List<String>)Merge string collectionthis
setAllDates(name, List<Date>)Replace with date collectionthis
appendAllDates(name, List<Date>)Merge date collectionthis
of(name, value) (static)Create map with one attribute (override)new map
ofAppend(name, value) (static)Create map with one attribute (merge)new map
ofAppendAll(name, List<String>) (static)Create map with string collection (merge)new map

All methods accept any supported type: String, Date, Boolean, Integer, Long, Double, Float, TurMultiValue.

Merging Maps​

attrValues.merge(otherAttrValues);

Combines two attribute maps. For each key in the source map:

  • If override is true on the source value → replaces the existing value
  • If override is false → appends to the existing multi-value

AEM Configuration JSON​

The AEM connector is configured via a JSON file that defines sources, attributes, locale mappings, and content models. This file is placed in an export/ directory and imported at startup.

Full Example (WKND Site)​

{
"sources": [
{
"name": "WKND",
"defaultLocale": "en_US",
"localeClass": "com.viglet.dumont.connector.aem.commons.ext.DumAemExtLocale",
"deltaClass": "com.example.MyDeltaDate",
"endpoint": "http://localhost:4502",
"username": "admin",
"password": "admin",
"oncePattern": "^/content/wknd/us/en/faqs",
"rootPath": "/content/wknd",
"contentType": "cq:Page",
"author": true,
"publish": true,
"authorSNSite": "wknd-author",
"publishSNSite": "wknd-publish",
"authorURLPrefix": "http://localhost:4502",
"publishURLPrefix": "https://wknd.site",
"localePaths": [
{ "locale": "en_US", "path": "/content/wknd/us/en" },
{ "locale": "es", "path": "/content/wknd/es/es" }
],
"attributes": [
{
"name": "id", "type": "STRING", "mandatory": true,
"className": "com.viglet.dumont.connector.aem.commons.ext.DumAemExtContentId"
},
{
"name": "title", "type": "TEXT", "mandatory": true,
"facetName": { "default": "Titles", "pt_BR": "Títulos" }
},
{
"name": "tags", "type": "STRING", "multiValued": true,
"facet": true, "facetName": { "default": "Tags" },
"className": "com.viglet.dumont.connector.aem.commons.ext.DumAemExtContentTags"
},
{
"name": "url", "type": "STRING", "mandatory": true,
"className": "com.viglet.dumont.connector.aem.commons.ext.DumAemExtContentUrl"
}
],
"models": [
{
"type": "cq:Page",
"className": "com.example.MyModelJsonExtractor",
"targetAttrs": [
{ "name": "title", "sourceAttrs": [{ "name": "jcr:title" }] },
{ "name": "tags", "sourceAttrs": [{ "name": "cq:tags" }] },
{
"name": "text",
"sourceAttrs": [{
"className": "com.viglet.dumont.connector.aem.commons.ext.DumAemExtPageComponents"
}]
}
]
}
]
}
]
}

Source Fields​

FieldTypeDescription
namestringSource identifier (displayed in the admin console)
endpointstringAEM instance URL (e.g., http://localhost:4502)
username / passwordstringAEM authentication credentials
rootPathstringContent tree root to crawl (e.g., /content/wknd)
contentTypestringJCR node type to index (e.g., cq:Page)
defaultLocalestringFallback locale code (e.g., en_US)
localeClassstringClass for locale resolution
deltaClassstringClass implementing DumAemExtDeltaDateInterface
oncePatternstringRegex: matching paths are indexed only once (never re-indexed)
author / publishbooleanEnable indexing from author/publish environments
authorSNSite / publishSNSitestringViglet Turing SN Site names for each environment
authorURLPrefix / publishURLPrefixstringPublic URL prefixes for documents

Locale Paths​

"localePaths": [
{ "locale": "en_US", "path": "/content/wknd/us/en" },
{ "locale": "es", "path": "/content/wknd/es/es" }
]

Content found under each path is tagged with the corresponding locale.

Attribute Fields​

FieldTypeDescription
namestringField name in the search index
typestringSTRING, TEXT, or DATE
mandatorybooleanWhether this field is required
multiValuedbooleanWhether this field holds multiple values
descriptionstringHuman-readable description
facetbooleanExpose as a facet filter in search results
facetNameobjectLocalized labels: { "default": "Tags", "pt_BR": "Etiquetas" }
classNamestringClass implementing DumAemExtAttributeInterface, extracts the value instead of reading from JCR

Model Fields​

FieldTypeDescription
typestringJCR node type this model applies to
classNamestringClass implementing DumAemExtContentInterface
targetAttrs[].namestringTarget field (must match attributes[])
targetAttrs[].sourceAttrs[].namestringJCR property to read (e.g., jcr:title)
targetAttrs[].sourceAttrs[].classNamestringClass implementing DumAemExtAttributeInterface for custom extraction

Creating a Custom AEM Extension​

Step 1: Create a Maven project​

<project>
<groupId>com.example</groupId>
<artifactId>my-aem-extensions</artifactId>
<version>1.0.0</version>

<dependencies>
<dependency>
<groupId>com.viglet.dumont</groupId>
<artifactId>aem-commons</artifactId>
<version>2026.2.3</version>
</dependency>
</dependencies>
</project>

Step 2: Implement your extension​

Attribute extension (for individual fields):

package com.example.ext;

import com.viglet.dumont.connector.aem.commons.ext.DumAemExtAttributeInterface;
import com.viglet.turing.client.sn.TurMultiValue;

public class MyBreadcrumb implements DumAemExtAttributeInterface {
@Override
public TurMultiValue consume(DumAemTargetAttr target,
DumAemSourceAttr source, DumAemObject aemObject,
DumAemConfiguration config) {
String path = aemObject.getPath()
.replace(config.getRootPath(), "");
return TurMultiValue.singleItem(
String.join(" > ", path.split("/")));
}
}

Model JSON extension (for structured .model.json data):

package com.example.ext;

import com.viglet.dumont.connector.aem.commons.ext.DumAemExtModelJsonBase;
import com.viglet.dumont.connector.aem.commons.ext.DumAemModelJsonQuery;

public class MyModelJson extends DumAemExtModelJsonBase<MyModel> {

@Override
protected Class<MyModel> getModelClass() {
return MyModel.class;
}

@Override
protected void extractAttributes(MyModel model, DumAemModelJsonQuery query,
DumAemObject aemObject, DumAemAttrMap attrValues) {
attrValues.set("title", model.getTitle());

query.component("my-app/components/news", MyNews.class)
.first()
.attr("date", MyNews::getDate)
.into(attrValues);
}
}

Step 3: Build and deploy​

mvn clean package
cp target/my-aem-extensions-1.0.0.jar /appl/viglet/dumont/aem/libs/

The libs/ directory must contain both aem-plugin.jar and your extension JAR.

Step 4: Reference in the JSON​

{
"name": "breadcrumb",
"type": "STRING",
"className": "com.example.ext.MyBreadcrumb"
}

How classes are loaded​

Extension classes are loaded via DumCustomClassCache using Class.forName(). Requirements:

  • Public no-argument constructor
  • On the classpath (via libs/ and -Dloader.path)
  • Thread-safe (one instance is shared across all calls)

PageDescription
AEM ConnectorAEM connector features, configuration, and locale mapping
Installation GuideHow to deploy plugins with -Dloader.path
Developer GuideProject structure, build, and contribution guide