> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Syncing Experience Fragments as Email Templates
## Introduction
[Adobe Experience Manager (AEM)](https://business.adobe.com/products/experience-manager/adobe-experience-manager.html) is an enterprise content management platform that enables organizations to create, manage, and deliver personalized digital experiences across multiple channels.
Sync Experience Fragments and its variations directly as **Email Templates** in MoEngage. Allows marketing teams to author locale-specific email variations in AEM and have them automatically appear as a grouped, multi-locale email template in MoEngage.
## Use Cases
* **Locale-Based Email Campaigns**: Author one Experience Fragment with multiple locale variations (e.g., English, German, Italian). Each variation syncs as a child template grouped under a single parent in MoEngage, enabling MoEngage to automatically serve the right locale to each user.
* **Centralised Email Authoring**: Keep all email HTML in AEM as the single source of truth. Any publish action automatically pushes the latest content to MoEngage email templates without manual export or copy-paste.
* **Multi-Variation Testing**: Manage A/B or regional variants of an email inside a single AEM Experience Fragment, syncing each as a numbered variation in MoEngage's template group.
## How It Works
The sync follows a **Parent + Child template model** that maps directly to MoEngage's Email Template grouping structure:
| AEM Structure | Maps To | Notes |
| ------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
| XF Root Page | Template Group | Groups all locale variations together in MoEngage |
| First XF Variation (child page) | Parent Template (locale: `EN`) | Always synced first. Its `external_template_id` becomes the `group_id` for all child templates |
| Subsequent XF Variations | Child Templates | Locale detected automatically from the variation's title or node name (e.g., `-de_de` → `DE_DE`) |
### Locale Detection Logic
The workflow automatically detects the locale of each XF variation by matching a `[-_][language][-_][country]` suffix at the end of the variation's **page title** or **node name** (e.g., `promo-email-de_de` → `DE_DE`). The following locales are supported out of the box:
| Locale Code | Language / Region |
| ----------- | -------------------------- |
| `EN` | English (default fallback) |
| `DE_DE` | German (Germany) |
| `IT_IT` | Italian (Italy) |
| `ES_ES` | Spanish (Spain) |
| `NL_NL` | Dutch (Netherlands) |
| `ID_ID` | Indonesian (Indonesia) |
**Locale Fallback**
If no valid locale is detected from the variation title or node name, or if the detected locale is not in the supported list above, the workflow defaults the locale to `EN` and logs a warning. You can extend the `VALID_LOCALES` set in the implementation to support additional locales as needed.
## Step 1: Add the Email Sync Workflow Step
Create a new file at the following path in your AEM project:
```plaintext theme={null}
core/src/main/java/com/[your-company]/integration/workflow/MoEngageEmailSyncStep.java
```
**Sample Implementation**
The code below is a **sample reference implementation** intended as a starting point. It covers the core sync flow but may require adjustments to match your AEM project structure, locale list, sender details, or template naming conventions. Review the inline comments carefully and test thoroughly in a non-production environment before deploying. For implementation support or custom requirements, contact **MoEngage Support** or your Customer Success Manager.
```java MoEngageEmailSyncStep.java wrap theme={null}
package com.moengage.integration.workflow;
import com.adobe.granite.workflow.WorkflowException;
import com.adobe.granite.workflow.WorkflowSession;
import com.adobe.granite.workflow.exec.WorkItem;
import com.adobe.granite.workflow.exec.WorkflowProcess;
import com.adobe.granite.workflow.metadata.MetaDataMap;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.engine.SlingRequestProcessor;
import com.day.cq.contentsync.handler.util.RequestResponseFactory;
import com.day.cq.wcm.api.Page;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.ByteArrayOutputStream;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
import java.util.Iterator;
import java.util.List;
import java.util.ArrayList;
import java.util.stream.Collectors;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.json.JSONObject;
@Component(
service = WorkflowProcess.class,
property = { "process.label=MoEngage Email Sync (Parent + Child - Stable)" }
)
public class MoEngageEmailSyncStep implements WorkflowProcess {
private static final Logger log = LoggerFactory.getLogger(MoEngageEmailSyncStep.class);
private static final String EMAIL_API_URL = "https://api-%s.moengage.com/v1.0/custom-templates/email";
// Extend this set to support additional locales required by your markets
private static final java.util.Set VALID_LOCALES = new java.util.HashSet<>(java.util.Arrays.asList(
"IT_IT", "DE_DE", "ES_ES", "NL_NL", "ID_ID", "EN"
));
@Reference
private RequestResponseFactory requestResponseFactory;
@Reference
private SlingRequestProcessor requestProcessor;
@Override
public void execute(WorkItem workItem, WorkflowSession workflowSession, MetaDataMap args)
throws WorkflowException {
ResourceResolver resolver = null;
try {
String processArgs = args.get("PROCESS_ARGS", "");
Map config = parseArgs(processArgs);
String apiKey = config.get("moengage.api.key");
String apiSecret = config.get("moengage.api.secret");
String dataCenter = config.getOrDefault("moengage.datacenter", "02");
String publishUrl = config.getOrDefault("aem.publish.url", "").trim();
if (publishUrl.endsWith("/")) publishUrl = publishUrl.substring(0, publishUrl.length() - 1);
boolean debugMode = Boolean.parseBoolean(config.get("moengage.debug"));
String debugUrl = config.getOrDefault("moengage.debug.url", "");
String payloadPath = getCleanPath(workItem.getWorkflowData().getPayload().toString());
resolver = workflowSession.adaptTo(ResourceResolver.class);
if (resolver == null) {
log.error("Could not obtain ResourceResolver");
return;
}
Page xfRoot = getXfRootPage(payloadPath, resolver);
if (xfRoot == null) return;
List templates = discoverAllVariations(xfRoot, resolver, publishUrl);
if (templates.isEmpty()) return;
// Sync the first variation as the parent (locale: EN)
EmailTemplate parentTemplate = templates.get(0);
String parentExternalId = syncParentTemplate(
parentTemplate, resolver, dataCenter, apiKey, apiSecret,
workItem.getWorkflow().getInitiator(), debugMode, debugUrl
);
if (parentExternalId == null || parentExternalId.isEmpty()) {
log.error("Failed to create parent template, aborting child sync");
return;
}
// Sync remaining variations as children, linked via group_id
for (int i = 1; i < templates.size(); i++) {
EmailTemplate childTemplate = templates.get(i);
try {
syncChildTemplate(childTemplate, parentExternalId, i + 1, dataCenter,
apiKey, apiSecret, workItem.getWorkflow().getInitiator(),
debugMode, debugUrl);
} catch (Exception e) {
log.error("Failed to sync child template: {}. Skipping.", childTemplate.subject, e);
}
}
} catch (Exception e) {
log.error("Email Sync Failed. Caught exception to prevent AEM retry loop.", e);
}
}
// Resolves the XF root page from the workflow payload path
private Page getXfRootPage(String payloadPath, ResourceResolver resolver) {
String cleanPath = payloadPath.replaceAll("\\.html$", "").replaceAll("/jcr:content.*$", "");
Resource resource = resolver.getResource(cleanPath);
if (resource == null) return null;
Page page = resource.adaptTo(Page.class);
if (page == null) return null;
Page parent = page.getParent();
// If this is a variation page (no children), walk up to the XF root
if (parent != null && parent.getPath().contains("/experience-fragments/")
&& !page.listChildren().hasNext()) {
return parent;
}
return page;
}
// Iterates XF children and builds an EmailTemplate list.
// First child = parent (EN); remaining children = locale variants.
private List discoverAllVariations(Page xfRoot, ResourceResolver resolver, String publishUrl) {
List templates = new ArrayList<>();
try {
Iterator children = xfRoot.listChildren();
boolean isParent = true;
while (children.hasNext()) {
Page child = children.next();
String title = child.getTitle() != null ? child.getTitle() : child.getName();
String html = renderHtml(child.getPath(), resolver);
if (html.isEmpty()) {
log.warn("HTML is empty for {}, skipping.", title);
continue;
}
html = processHtmlForEmail(html, publishUrl);
if (isParent) {
// Parent template always uses EN as the default locale
templates.add(new EmailTemplate("master", title, html, title, "EN"));
isParent = false;
} else {
// Detect locale from title or node name suffix, e.g. "-de_de" or "_it_it"
String localeCode = null;
Matcher m = Pattern.compile("[-_]([a-zA-Z]{2}[-_][a-zA-Z]{2})$").matcher(title);
if (m.find()) {
localeCode = m.group(1).toUpperCase().replace("-", "_");
} else {
Matcher mNode = Pattern.compile("[-_]([a-zA-Z]{2}[-_][a-zA-Z]{2})$")
.matcher(child.getName());
if (mNode.find()) {
localeCode = mNode.group(1).toUpperCase().replace("-", "_");
}
}
// Fall back to EN if locale is unrecognised
if (localeCode == null || !VALID_LOCALES.contains(localeCode)) {
log.warn("Locale '{}' not valid for '{}', defaulting to EN", localeCode, title);
localeCode = "EN";
}
templates.add(new EmailTemplate(localeCode, title, html, title, localeCode));
}
}
} catch (Exception e) {
log.error("Error discovering variations", e);
}
return templates;
}
private String processHtmlForEmail(String html, String publishUrl) {
String cleanHtml = cleanContentAsIs(html);
if (publishUrl != null && !publishUrl.isEmpty()) {
cleanHtml = externalizeLinks(cleanHtml, publishUrl);
}
return cleanHtml;
}
// Creates the parent email template; returns external_template_id
private String syncParentTemplate(EmailTemplate template, ResourceResolver resolver,
String dataCenter, String apiKey, String apiSecret, String initiator,
boolean dbg, String dbgUrl) throws Exception {
String templateId = "email_" + template.templateName + "_" + System.currentTimeMillis();
String endpointUrl = String.format(EMAIL_API_URL, dataCenter);
JSONObject payload = new JSONObject();
JSONObject basicDetails = new JSONObject();
basicDetails.put("subject", template.subject);
basicDetails.put("email_content", template.htmlContent);
basicDetails.put("sender_name", "Brand Communications"); // TODO: customise as needed
JSONObject metaInfo = new JSONObject();
metaInfo.put("template_id", templateId);
metaInfo.put("template_name", template.templateName);
metaInfo.put("template_version", "1.0");
metaInfo.put("created_by", initiator);
metaInfo.put("variation", 1);
metaInfo.put("locale", template.locale); // Always "EN" for parent
payload.put("basic_details", basicDetails);
payload.put("meta_info", metaInfo);
String response = sendToMoEngageAndGetResponse(endpointUrl, apiKey, apiSecret,
payload.toString(), dbg, dbgUrl);
try {
JSONObject responseJson = new JSONObject(response);
String externalId = responseJson.optString("external_template_id", null);
if (externalId != null && !externalId.isEmpty()) {
return externalId;
}
return null;
} catch (Exception e) {
return null;
}
}
// Creates a child template linked to the parent via group_id
private void syncChildTemplate(EmailTemplate template, String parentGroupId, int variationNumber,
String dataCenter, String apiKey, String apiSecret, String initiator,
boolean dbg, String dbgUrl) throws Exception {
String templateId = "email_" + template.templateName + "_" + template.locale
+ "_" + System.currentTimeMillis();
String endpointUrl = String.format(EMAIL_API_URL, dataCenter);
JSONObject payload = new JSONObject();
JSONObject basicDetails = new JSONObject();
basicDetails.put("subject", template.subject);
basicDetails.put("email_content", template.htmlContent);
basicDetails.put("sender_name", "Brand Communications"); // TODO: customise as needed
JSONObject metaInfo = new JSONObject();
metaInfo.put("template_id", templateId);
metaInfo.put("template_name", template.templateName);
metaInfo.put("template_version", "1.0");
metaInfo.put("created_by", initiator);
metaInfo.put("variation", variationNumber);
metaInfo.put("locale", template.locale);
metaInfo.put("group_id", parentGroupId); // Links child to parent group
payload.put("basic_details", basicDetails);
payload.put("meta_info", metaInfo);
sendToMoEngageAndGetResponse(endpointUrl, apiKey, apiSecret,
payload.toString(), dbg, dbgUrl);
}
// HTML cleaning: extracts ",
Pattern.DOTALL | Pattern.CASE_INSENSITIVE).matcher(headContent);
while (styleMatcher.find()) result.append(styleMatcher.group()).append("\n");
}
String bodyContent = html;
Matcher bodyMatcher = Pattern.compile("]*>(.*?)",
Pattern.DOTALL | Pattern.CASE_INSENSITIVE).matcher(html);
if (bodyMatcher.find()) {
bodyContent = bodyMatcher.group(1);
} else {
bodyContent = html
.replaceAll("(?is)]*>", "")
.replaceAll("(?is)