Surge Migrate

Deprecated on Cloud Service

Replacing JCR observation listeners in AEM as a Cloud Service

On Cloud Service, instances scale up and down and restart during releases. Work triggered from a JCR observation listener can run on several instances or be lost on restart. Adobe's migration tooling treats event listeners and handlers as patterns to convert.

Affected packages and APIs

  • javax.jcr.observation.EventListener

What to use instead

org.apache.sling.api.resource.observation.ResourceChangeListener for notification, and Sling Jobs (JobManager + JobConsumer) for work that must run exactly once.

How to fix it

  1. Classify each listener: light notification, or work that must not be lost.
  2. Convert notifications to ResourceChangeListener with resource.paths and resource.change.types properties.
  3. Move heavy or must-run work into a Sling Job topic and a JobConsumer.
  4. Make job processing idempotent; jobs can be retried.

Cloud Service

@Component(service = ResourceChangeListener.class, property = {
  ResourceChangeListener.PATHS + "=/content/acme",
  ResourceChangeListener.CHANGES + "=CHANGED"
})
public class PageChangeListener implements ResourceChangeListener {
  @Reference JobManager jobs;
  public void onChange(List<ResourceChange> changes) {
    changes.forEach(c -> jobs.addJob("acme/page/changed", Map.of("path", c.getPath())));
  }
}

How we detect it

  • Readiness scan rule jcr-observation: JCR observation listeners.

Best Practices Analyzer reports it under DG.

Can agents fix it?

Partial. The conversion is mechanical; deciding which events need guaranteed processing is a review decision.

Source: Adobe Experience League. Checked 19 October 2026.