AEM Replication & Dispatcher Flush: Agents & Sling Content Distribution

Replication Agents: what they do & where they live

Replication agents in AEM are the mechanism to:

• Activate (publish) content from Author → Publish
• Flush the Dispatcher cache
• Reverse replicate user input (Publish → Author) when required

They are configured in the repository and via classic admin UIs:

• Config path: /etc/replication
• Create/manage: /miscadmin (Classic UI)
• Default publish listener servlet: http://<publish-host>:4503/bin/receive

A development environment can have multiple cq-author and cq-publish instances, so an Author can have many agents, each targeting one or more Publish instances.

Forward Replication (Author → Publish)

1. Author packages the content and places it onto a replication queue (by activating a page/asset).
2. The Publish instance’s listener (/bin/receive) accepts the package.
3. Content is written/updated on Publish.

Example: Create a Publish Replication Agent under /etc/replication

You can create this under /etc/replication/agents.author for the Author runmode (CRXDE Lite). The node types and properties matter.

/etc/replication
  └── agents.author
      └── publish_4503
          (sling:Folder)
            ├── jcr:content (cq:PageContent)
            │   ├── enabled = true
            │   ├── serializationType = "binary"
            │   ├── transportUri = "http://publish.local:4503/bin/receive"
            │   ├── transportUser = "replication-user"
            │   ├── transportPassword = "*****"
            │   ├── retryDelay = 60000
            │   ├── logLevel = "info"
            │   ├── useSsl = false
            │   └── queueBatchMode = "true"
            └── ../ (other properties per your environment)

Properties like transportUri, transportUser, and transportPassword define the HTTP endpoint and credentials on the Publish side. Retry and batching keep your queue robust during spikes.

Example: Trigger a replication via HTTP (simulate “Activate”)

# Activate a page from Author
curl -u admin:admin -X POST \
  "http://author.local:4502/bin/replicate.json" \
  -d "path=/content/site/en/home" \
  -d "cmd=Activate"

This hits the author to enqueue replication (same mechanism the UI uses).

Reverse Replication (Publish → Author)

Reverse replication is used to move content (often user input) from Publish back to Author. The reverse agent on Publish writes changes to an outbox at:

repo://var/replication/outbox

Author’s replication listeners continuously read this outbox and apply updates in Author.

Example: Reverse Replication Agent on Publish

/etc/replication
  └── agents.publish
      └── reverse_to_author
          (sling:Folder)
            ├── jcr:content (cq:PageContent)
            │   ├── enabled = true
            │   ├── serializationType = "binary"
            │   ├── transportUri = "repo://var/replication/outbox"
            │   ├── logLevel = "info"
            │   └── trigger = "ondispatch"  # example trigger

Reverse replication is less common in AEM Cloud setups. When needed, ensure both permissions and network connectivity allow Author to read from the Publish outbox, or consider alternative patterns (e.g., Adobe IO Events or dedicated APIs) depending on your architecture.

Dispatcher Flush Agent (Invalidate cache)

A Flush Agent is typically created on the Publish (or Author) tier that sends invalidation requests to the Dispatcher to purge/refresh cached entries.

Example: Create a Flush Agent on Publish

/etc/replication
  └── agents.publish
      └── dispatcher_flush
          (sling:Folder)
            ├── jcr:content (cq:PageContent)
            │   ├── enabled = true
            │   ├── serializationType = "flush"
            │   ├── transportUri = "http://dispatcher-host:80/dispatcher/invalidate.cache"
            │   ├── transportUser = "flush-user"
            │   ├── transportPassword = "*****"
            │   ├── logLevel = "info"
            │   └── agentDescription = "Flush Dispatcher cache on activation"

• Your Dispatcher must be configured to accept the flush HTTP request and map it to cache invalidation.
• AEM can also perform invalidation via Sling Content Distribution (below), which scales better in multi‑instance clusters.

Sling Content Distribution (SCD): path‑based, OSGi‑configured distribution

SCD is an Apache Sling approach that works at the path level, supports cloud & on‑prem, and provides forward, reverse, sync, and multi‑datacenter sync distribution scenarios. It also offers invalidations, and can be triggered via API. [stacknowledge.in]

SCD OSGi Config examples (Cloud or on‑prem)

SCD uses OSGi configurations to define agents and distributors.

Example: Distributor & Publish agent (OSGi config)

# com.adobe.granite.distribution.core.impl.DistributionComponentFactory
# or org.apache.sling.distribution.* (depending on bundle versions)
enabled=true
name=publish
type=forward           # forward distribution: Author pushes to Publish
targets=["http://publish.local:4503"]  # target endpoints
authorizationStrategy=default
queueProcessingEnabled=true

Actual component names may vary by version/bundle. Configure via /system/console/configMgr or OSGi configs in your project’s ui.config (AEM as a Cloud Service) or conf packages. See the official docs for agent types and properties.

Programmatic distribution/invalidation via Java API

You can invalidate paths using the Distributor API, which is especially helpful in clustered environments (Dispatcher flush at scale):

import org.apache.sling.distribution.Distributor;
import org.apache.sling.distribution.DistributionRequest;
import org.apache.sling.distribution.DistributionRequestType;
import org.apache.sling.distribution.SimpleDistributionRequest;
import org.apache.sling.api.resource.ResourceResolver;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;

@Component(service = CacheInvalidationService.class, immediate = true)
public class CacheInvalidationService {

  @Reference
  private Distributor distributor;

  public boolean invalidate(ResourceResolver resolver, boolean isDeep, String... paths) {
    DistributionRequest request = new SimpleDistributionRequest(
        DistributionRequestType.INVALIDATE, isDeep, paths);

    // "publish" distributor must be configured in OSGi with appropriate agent(s)
    var response = distributor.distribute("publish", resolver, request);

    return response != null && response.isSuccessful();
  }
}

• DistributionRequestType.INVALIDATE ensures cache invalidation rather than content push.
• The "publish" distributor name should match your OSGi distributor config.

Auto replication with On/Off time

SCD supports trigger configs that auto‑distribute when OnTime/OffTime is reached (similar to legacy replication triggers). This is commonly configured via OSGi for the distribution agent/distributor.

Tree Activation: OOTB workflow

For bulk activation (e.g., an entire subtree), use the OOTB Tree Activation workflow.

Example: Configure Tree Activation workflow

1. In Workflow Models, create a workflow (or use OOTB) that includes the process step: “Tree Activation”.
2. Add parameters such as:
   • onlyModified=true (activate only changed pages)
   • dryRun=false (set true to simulate)
3. Start the workflow on the target path (e.g., /content/site/en).

For Cloud Service operations and replication notes (including tree activation), see the Experience League replication guide.

Typical scenarios with SCD

• Forward Distribution (Author pushes to Publish): events like created, queued, distributed, dropped, imported are tracked.
• Reverse Distribution (Publish pulls from Source)
• Sync Distribution (Coordinator instance maintains consistency across multiple instances)
• Multi‑datacenter Sync (coordinate sync with a per‑DC coordinator)

SCD’s invalidations can replace/augment “Flush Agents” for robust, cluster‑wide cache management. The legacy Replication API can invalidate cache but has capacity limits; SCD scales better in distributed environments.

Operational tips & best practices

• Use SCD for cache invalidation in clustered/cloud setups; prefer Distributor INVALIDATE requests for scale.
• Monitor replication queues in Author (/system/console) for stuck/delayed items.
• Keep credentials and transport URIs in secure configs (OSGi/runmode), not hard‑coded.
• In AEM Cloud, consider modern alternatives (Adobe IO Events, Journaling) for external integrations, and follow cluster‑aware coding guidelines.