Content Distribution

adobe/skills/plugins/aem/cloud-service/skills/content-distribution

by adobe940b8795c0dfApache-2.0197 starsListed Oct 9, 2026Updated Oct 8, 2026Repository updated today

AEM as a Cloud Service content distribution and replication. Covers programmatic publishing using the Replication API and distribution event monitoring using Sling Distribution events.

Instructions only

AEM Cloud Service Content Distribution

Beta Skill: This skill is in beta and under active development. Results should be reviewed carefully before use in production. Report issues at https://github.com/adobe/skills/issues

Programmatic content publishing and distribution monitoring using official AEM Cloud Service APIs.

When to Use This Skill

Use this skill collection for:

  • Programmatic publishing: Publish content via Replicator API
  • Distribution monitoring: Track distribution lifecycle events
  • Automated workflows: Integration with workflow process steps
  • Event handling: React to distribution events (failures, completions)
  • Custom publishing logic: Bulk operations, Preview tier publishing

Sub-Skills

This is a parent skill that routes to specialized sub-skills based on your task:

TaskSub-SkillFile
Programmatically publish/unpublish contentReplication APIreplication/SKILL.md
Monitor distribution events and lifecycleSling Distribution Eventssling-distribution/SKILL.md

Quick Decision Guide

Choose Replication API when you need to:

  • Publish content from custom OSGi services
  • Integrate publishing into workflow steps
  • Perform bulk publishing operations
  • Publish to Preview tier for review
  • Check replication status programmatically

Choose Sling Distribution Events when you need to:

  • Monitor distribution lifecycle (created, queued, distributed, imported)
  • React to distribution failures
  • Trigger post-distribution actions (cache warming, notifications)
  • Audit distribution operations
  • Track distribution metrics

Official APIs

Both skills use official, supported AEM Cloud Service APIs:

  1. Replication API: com.day.cq.replication

  2. Sling Distribution API: org.apache.sling.distribution

Architecture Overview

┌──────────────────────────────────────────────────┐│ Replication API (Your Code)                     ││ com.day.cq.replication.Replicator                ││                                                  ││ replicator.replicate(session, ACTIVATE, path)   │└────────────────────┬─────────────────────────────┘                     ↓┌──────────────────────────────────────────────────┐│ Sling Distribution (Underlying Transport)       ││ org.apache.sling.distribution                    ││                                                  ││ [AGENT_PACKAGE_CREATED]   ← Distribution events ││          ↓                   fire at each stage  ││ [AGENT_PACKAGE_QUEUED]                          ││          ↓                                       ││ [AGENT_PACKAGE_DISTRIBUTED]                     ││          ↓                                       ││ Adobe Developer Pipeline Service                ││          ↓                                       ││ [IMPORTER_PACKAGE_IMPORTED]                     │└──────────────────────────────────────────────────┘                     ↓         Content live on Publish/Preview

How It Works

  1. Your code calls Replicator.replicate() to publish content
  2. Sling Distribution packages content and fires AGENT_PACKAGE_CREATED event
  3. Package is queued and AGENT_PACKAGE_QUEUED event fires
  4. Package is sent to Adobe Developer pipeline and AGENT_PACKAGE_DISTRIBUTED event fires
  5. Target tier imports content and IMPORTER_PACKAGE_IMPORTED event fires
  6. Content is live on target tier (Publish or Preview)

Common Patterns

Pattern 1: Publish and Monitor

Publish content and track when it goes live:

java
// Step 1: Publish using Replication API@Referenceprivate Replicator replicator;
public void publishContent(Session session, String path) throws ReplicationException {    replicator.replicate(session, ReplicationActionType.ACTIVATE, path);}
// Step 2: Monitor completion using Distribution Events@Component(service = EventHandler.class, property = {    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED})public class PublishCompletionHandler implements EventHandler {        @Override    public void handleEvent(Event event) {        String[] paths = (String[]) event.getProperty(            DistributionEventProperties.DISTRIBUTION_PATHS        );                LOG.info("Content is now live: {}", String.join(",", paths));        // Trigger post-publish actions (cache warming, notifications, etc.)    }}

Pattern 2: Preview-First Workflow

Publish to Preview for approval, then to Publish:

java
// Workflow Step 1: Publish to Previewpublic void publishToPreview(Session session, String path) throws ReplicationException {    ReplicationOptions options = new ReplicationOptions();    options.setFilter(agent -> "preview".equals(agent.getId()));        replicator.replicate(session, ReplicationActionType.ACTIVATE, path, options);}
// Workflow Step 2: After approval, publish to Publish tierpublic void publishToProduction(Session session, String path) throws ReplicationException {    ReplicationOptions options = new ReplicationOptions();    options.setFilter(agent -> "publish".equals(agent.getId()));        replicator.replicate(session, ReplicationActionType.ACTIVATE, path, options);}

Pattern 3: Auto-Publish with Failure Handling

Auto-publish content and alert on failures:

java
// Publish handler@Component(service = EventHandler.class, property = {    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         SlingConstants.TOPIC_RESOURCE_CHANGED})public class AutoPublishHandler implements EventHandler {        @Reference    private Replicator replicator;        @Override    public void handleEvent(Event event) {        String path = (String) event.getProperty(SlingConstants.PROPERTY_PATH);                if (shouldAutoPublish(path)) {            try (ResourceResolver resolver = getServiceResolver()) {                Session session = resolver.adaptTo(Session.class);                replicator.replicate(session, ReplicationActionType.ACTIVATE, path);            } catch (Exception e) {                LOG.error("Auto-publish failed", e);            }        }    }}
// Failure monitoring@Component(service = EventHandler.class, property = {    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         DistributionEventTopics.AGENT_PACKAGE_DROPPED})public class FailureAlertHandler implements EventHandler {        @Reference    private AlertService alertService;        @Override    public void handleEvent(Event event) {        String packageId = (String) event.getProperty(            DistributionEventProperties.DISTRIBUTION_PACKAGE_ID        );                alertService.sendAlert("Distribution failed", packageId);    }}

Rate Limits and Constraints

ConstraintLimitImpact
Paths per API call (recommended)100Transactional guarantee; system auto-splits above this
Payload size10 MBExcluding binaries

Note: ReplicationOptions.setUseAtomicCalls() is @Deprecated / "no longer required" per the Cloud Service Javadoc — the system handles auto-bucketing automatically for >100 paths.

Best Practice: For large hierarchical content trees, use the Tree Activation workflow step instead of custom code.

Key Differences from AEM 6.x

FeatureAEM 6.xAEM Cloud Service
Replication APIcom.day.cq.replication.Replicator✅ Same API
Replication agentsManual configuration✅ Automatic (managed by Adobe)
Transport mechanismDirect JCR replication✅ Sling Distribution via Adobe pipeline
Preview tierNot available✅ Available (requires agent filtering)
Distribution eventsLimited✅ Full lifecycle via org.apache.sling.distribution.event
Agent configurationManual OSGi config❌ Not exposed (managed by Adobe)

When NOT to Use These Skills

Use UI workflows instead when:

  • Publishing small amounts of content manually
  • One-off publishing operations
  • Content authors can use Quick Publish or Manage Publication

Use Tree Activation workflow when:

  • Publishing large hierarchical content trees
  • Bulk operations across hundreds of paths and no custom logic is needed

Quick Reference

Replication API Basics

java
// Inject service@Referenceprivate Replicator replicator;
// Publish single pagereplicator.replicate(session, ReplicationActionType.ACTIVATE, "/content/mysite/page");
// Unpublishreplicator.replicate(session, ReplicationActionType.DEACTIVATE, "/content/mysite/page");
// Bulk publish (≤100 for transactional guarantee)replicator.replicate(session, ReplicationActionType.ACTIVATE,     new String[]{"/content/page1", "/content/page2"}, null);
// Publish to PreviewReplicationOptions options = new ReplicationOptions();options.setFilter(agent -> "preview".equals(agent.getId()));replicator.replicate(session, ReplicationActionType.ACTIVATE, "/content/page", options);
// Check statusReplicationStatus status = replicator.getReplicationStatus(session, "/content/page");boolean isPublished = status != null && status.isActivated();

Distribution Event Handling Basics

java
// Listen for distribution events@Component(service = EventHandler.class, property = {    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         DistributionEventTopics.AGENT_PACKAGE_CREATED,    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         DistributionEventTopics.AGENT_PACKAGE_DISTRIBUTED,    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         DistributionEventTopics.AGENT_PACKAGE_DROPPED,    org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" +         DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED})public class DistributionMonitor implements EventHandler {        @Override    public void handleEvent(Event event) {        String topic = event.getTopic();        String packageId = (String) event.getProperty(            DistributionEventProperties.DISTRIBUTION_PACKAGE_ID        );        String[] paths = (String[]) event.getProperty(            DistributionEventProperties.DISTRIBUTION_PATHS        );                // Handle event based on topic        if (DistributionEventTopics.AGENT_PACKAGE_DROPPED.equals(topic)) {            LOG.error("Distribution failed: {}", packageId);        } else if (DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED.equals(topic)) {            LOG.info("Content is live: {}", String.join(",", paths));        }    }}

Best Practices

  1. Use the right API: Replication API for publishing, Distribution events for monitoring
  2. Respect rate limits: ≤100 paths for transactional guarantee
  3. Handle failures: Always catch ReplicationException, monitor AGENT_PACKAGE_DROPPED events
  4. Use service users: Never use admin credentials
  5. Filter events appropriately: Only listen to events you need
  6. Validate permissions: Call replicator.checkPermission() before replication
  7. Publish only what's needed: Avoid unnecessary bulk operations

Troubleshooting

Replication Issues

IssueSolution
ReplicationExceptionCheck service user has crx:replicate permission
Content not on target tierVerify agent filter, check replication status
"Too many paths" errorUse ≤100 paths for transactional guarantee, or pass all paths — system auto-splits

Event Handling Issues

IssueSolution
Event handler not firingVerify event topic constant matches exactly
Missing event propertiesAlways null-check event properties
Handler slowing distributionUse async job processing, don't block

Detailed Documentation

For detailed examples, code samples, and advanced usage:

  • Replication API: See replication/SKILL.md
  • Sling Distribution Events: See sling-distribution/SKILL.md

References

Source and attribution

Source:adobe/skillsinplugins/aem/cloud-service/skills/content-distributionat commit940b879

License: Apache-2.0

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from adobe/skills

Prototype

adobe

Render a proposed redesign of a page on the current website as a self-contained static HTML file, then iterate via the impeccable craft loop. Per-page, idempotent, stale-aware. Use when the user asks for a redesign prototype, a before/after comparison, a design preview, a page mockup, a visual diff of the redesign, or invokes `$stardust prototype` (`/stardust:prototype` in Claude Code).

Includes scripts
Awaiting classification197updated today

Direct

adobe

Sets a redesign direction for an existing website, producing target spec files and a reasoning trace.

Design & Creative197updated today

Prepare Migration

adobe

Orchestrates a five-phase website migration preparation cascade, producing typed page inventories, a confirmed module catalog, design canon and prepared assets.

DevOps & Cloud197updated today

Testing Blocks

adobe

Guides testing of AEM Edge Delivery Services code changes: linting, mandatory browser validation, and optional unit tests.

Software Development197updated today

Ue Component Model

adobe

Guides creation and editing of the three JSON files that configure AEM Edge Delivery Services blocks in the Universal Editor.

Software Development197updated today

Preview Import

adobe

Verifies imported HTML content in a local AEM Edge Delivery Services dev server by previewing and comparing it to the original page.

Software Development197updated today