Org Skills

6.x → Cloud Service code refactor checklist

Supporting material for aem-cloud-migration. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/migration-journey/migration-journey and the AEM Modernization Tools documentation

Open this when planning the refactor, sizing a BPA finding, or checking whether something in the inherited codebase is going to survive.

The table

Area On 6.x Cloud Service target Tool
Project structure One package mixing /apps and /content ui.apps (application), ui.content (content), ui.config, all (container) Repository Modernizer
/etc Designs, cloud configs, tags, workflow models /conf for configuration, templates and workflow models; /content/cq:tags for tags; /apps for code Modernization Tools
OSGi configs sling:OsgiConfig nodes, .config files, custom run modes .cfg.json in ui.config under config.<runmode>; $[env:] / $[secret:] for per-environment values Repository Modernizer
Custom indexes Unversioned definitions, property and other types type="lucene" only, named <prefix>.<name>-<productVersion>-custom-<n> Index Converter
Templates Static templates with design dialogs Editable templates + policies in /conf Modernization Tools (page structure, policy import)
Components Foundation components and copies of them Core Components via proxies Modernization Tools component conversion
Dialogs Classic UI (ExtJS) Touch UI (Coral 3 / Granite) Dialog conversion tool
Asset processing DAM Update Asset workflow, launchers, custom renditions Asset microservices with processing profiles; genuinely custom steps as post-processing workflows or Asset Compute workers —
Replication Custom agents, reverse replication Managed content distribution; Replicator API only —
Dispatcher Any layout Flexible mode, validated by the dispatcher SDK Dispatcher Converter
Sessions loginAdministrative, admin resolvers Service users via repoinit with forced path system/cq:services/<proj> and set principal ACL —
File system Writes to disk, shared NFS Repository binaries or external storage; local disk is temp only and disappears —
Background work Long-running threads, schedulers on every node Idempotent Sling Jobs; work on author, not publish —
Servlets sling.servlet.paths under /bin Resource-type binding with selector and extension; path binding only when allow-listed in the dispatcher —
Authentication Custom login modules, LDAP for authors Adobe IMS for authors; SAML or an external IdP for site visitors —
Search Embedded Solr, custom search servers Oak queries with custom lucene indexes, or an external search service —
Networking Direct outbound, fixed IPs, SMTP Advanced Networking (dedicated egress IP or VPN) where needed — weeks of lead time —
Deprecated APIs Anything BPA or the build flags Replace; compiling against aem-sdk-api fails on removed APIs —

What BPA cannot see

The Best Practices Analyzer reads the repository and the code it can statically analyse. It does not run your code, so it misses whole categories. Grep for these before sizing the work:

grep -rn "loginAdministrative\|getAdministrativeResourceResolver" --include=*.java .
grep -rn "new File(\|FileOutputStream\|System.getProperty(\"user.dir\")" --include=*.java .
grep -rn "new Thread(\|Executors\.new\|ScheduledExecutorService" --include=*.java .
grep -rn '"/etc/' --include=*.java --include=*.html --include=*.js .
grep -rln "sling:OsgiConfig" --include=*.xml .
grep -rn "ReplicationAgent\|TransportHandler\|ContentBuilder" --include=*.java .
grep -rn "localhost\|:4502\|:4503" --include=*.java --include=*.json .

Each hit is a finding BPA will not report: admin sessions behind a utility class, file-system writes inside a library wrapper, threads that outlive a pod, hardcoded /etc paths that break after the move, legacy config nodes, custom replication, and environment-specific hostnames that should be $[env:] values.

Also check by hand: what happens on a pod restart mid-job, which integrations need a fixed egress IP, and whether any scheduled work assumes a single instance.

Products that do not come along

  • AEM Forms and AEM Screens have their own Cloud Service stories and are not covered by a Sites migration. Scope them separately and early; assuming they migrate with the rest is a schedule risk, not a technical one.
  • Communities, and anything that wrote user-generated content to the publish repository, needs an external store — publish writes do not survive a pod recycle.

6.5 LTS as an alternative

AEM 6.5 LTS is a supported alternative path for customers with a hard constraint (regulated hosting, an unsupported native dependency, a long-lived integration that cannot be reworked yet). It runs on a current JDK and continues to receive service packs. Record the decision the same way as any other architecture decision: the constraint, the date, and what would have to change for the Cloud Service path to become viable. It buys time; it does not remove the refactor.