# 6.x → Cloud Service code refactor checklist

> **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:

```bash
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.
