Migration

AEM as a Cloud Service — Code Migration

Source → target: Legacy AEM 6.x / AMS / on-prem → AEM as a Cloud Service. Scoped under skills/aem/cloud-service/skills/migration/ so this is not confused with Edge Delivery or 6.5 LTS.

This skill drives the migration workflow: BPA data, CAM/MCP, one pattern per session, and target discovery. Transformation rules and steps live in the code-assessment skill — once a finding's pattern is identified, hand off to {code-assessment}/<pattern>/SKILL.md (or the relevant shared reference under {code-assessment}/references/).

Setup: Use the aem-cloud-service install (see repository root README) so both migration and code-assessment paths are available. If you already have the monorepo open with resolvable {code-assessment} paths, no separate install step is required.

Quick start (for the person driving the agent)

One pattern per chat/session — if you ask to "fix everything," the skill will ask you to pick first (e.g. scheduler vs replication vs htlLint).

Starter prompts (copy-paste) — the Quick start table above covers each pattern individually; these add the whole-project entry point, source-specific invocations (CSV / CAM / manual), and multi-step combinations:

• "Review my code for AEMaaCS migration" — start here for a full runbook before changing anything.
• "Use the migration skill: scheduler only, BPA CSV at ./reports/bpa.csv."
• "Replication only from CAM; list projects first, I'll pick one."
• "Manual: event listener migration for .../Listener.java."
• "Fix all Classic UI and custom widget findings — CDW first, then dialogs."
• "Fix guavaCache findings using BPA CSV at ./reports/bpa.csv."

Path convention (Adobe Skills monorepo)

From the repository root (parent of the skills/ directory):

Examples: {code-assessment}/SKILL.md, {code-assessment}/scheduler/SKILL.md, {code-assessment}/references/scr-to-osgi-ds.md.

Workspace scope (IDE) — user code only

Applies to finding and editing the user's AEM project (Java, bundles, config, HTL), not to reading installed skill files under {code-assessment}.

• Treat the current IDE workspace root folder(s) (single- or multi-root) as the only boundary for searches, globs, grep, and file reads/writes for migration targets.
• Do not search parent directories, sibling folders on disk, ~, other clones, or arbitrary absolute paths to "discover" sources unless the user explicitly names those paths or asks you to include them.
• BPA CSV / CAM targets: If a filePath or class-to-file mapping does not resolve under a workspace root, stop and tell the user which paths are missing — do not hunt elsewhere on the filesystem. Ask them to open the correct project in the IDE or adjust paths.
• Manual flow: Only migrate files the user named that live under the workspace (or paths they explicitly provided). Do not expand scope by searching outside the workspace.

Required delegation (do this first)

Branch A — OSGi configs → Cloud Manager (no Java BPA pattern this session): If the user asks to scan config files, create / set up Cloud Manager environment secrets or variables, move passwords or secrets out of OSGi / .cfg.json / ui.config, or mentions $[secret:] / $[env:] for AEM CS, then read references/osgi-cfg-json-cloud-manager.md immediately and follow the product rules and workflow defined in that file (Adobe AEM as a Cloud Service OSGi + Cloud Manager behavior is reproduced there—no external doc URL required). Sleek prompts are enough — no need to name the reference file. Skip branch B for that work.

Branch B — Java / HTL / BPA pattern migration:

1. Read {code-assessment}/SKILL.md — critical rules, Java baseline links, Pattern Guides table, Manual Pattern Hints.
2. Read the pattern guide (or reference) for the single active pattern:
   • scheduler → {code-assessment}/scheduler/SKILL.md (pattern guide)
   • resourceChangeListener → {code-assessment}/resource-change-listener/SKILL.md (pattern guide)
   • replication → {code-assessment}/replication/SKILL.md (pattern guide)
   • eventListener / eventHandler → {code-assessment}/event-migration/SKILL.md (pattern guide — both JCR and OSGi Event Admin paths)
   • assetApi → {code-assessment}/asset-manager/SKILL.md (pattern guide)
   • htlLint → {code-assessment}/references/data-sly-test-redundant-constant.md (reference — HTL lint is a single shared reference, not a dedicated pattern guide)
   • vault-package-dependencies → references/vault-package-dependencies.md (reference — heuristic pom.xml scan; lives under migration only, not code-assessment, since this dependency shape never occurs in native AEMaaCS code)
   • guavaCache → references/guava-cache.md (reference — Guava cache → Caffeine swap; lives under migration only, not code-assessment, since Guava cache usage does not occur in native AEMaaCS code, only in code carried over from legacy AEM)
3. When code uses SCR, ResourceResolver, or console logging, read {code-assessment}/references/scr-to-osgi-ds.md and {code-assessment}/references/resource-resolver-logging.md (or the hub {code-assessment}/references/aem-cloud-service-pattern-prerequisites.md).

Do not transform Java or HTL until the pattern guide (or reference) is read (branch B). Branch A does not require {code-assessment} pattern guidance.

Branch C — Template Modernization (no BPA): static → editable templates and/or AEM Modernize Tools rules (structure/component/policy). Three phases: context → per-template execute → validate. Start at references/template-modernization/template-modernization-context.md; generators are editable-template-creation.md and aem-modernization.md; post-gen checks in template-modernization-validation.md. Skip branch B.

Branch D — Legacy UI Migration (legacy-ui/ sub-folders): If the user asks to convert Classic UI / ExtJS dialogs, upgrade Coral 2 dialogs, migrate custom ExtJS widgets, fix LUI or CDW BPA findings, or mentions cq:Dialog / xtype / cq:Widget:

• For dialog findings (lui pattern, legacy.dialog.classic or legacy.dialog.coral2 only):

  1. Read references/legacy-ui/dialog/context.md — getBpaFindings('lui', …), filter to dialog sub-types, skip all others with a note.
  2. convert-extjs → references/legacy-ui/dialog/extjs-to-coral3.md.
  3. upgrade-coral2 → references/legacy-ui/dialog/coral2-to-coral3.md.
  4. Validate: references/legacy-ui/dialog/validation.md.

• For custom widget findings (cdw pattern):

  1. Read references/legacy-ui/cdw/context.md — getBpaFindings('cdw', …), inventory xtypes.
  2. Per xtype: references/legacy-ui/cdw/conversion.md (apply mapping or scaffold Granite UI component).
  3. Validate: references/legacy-ui/cdw/validation.md.
  4. If the same components also have LUI legacy.dialog.classic findings, run dialog migration afterwards — all xtypes are now resolved.

Run order when both are needed: CDW first, then dialog. CDW resolves custom xtypes so dialog conversion can proceed without stops. Skip Branch B. Skip Branch C.

Branch E — Dispatcher Conversion (AMS / on-premise Apache httpd + Dispatcher → AEMaaCS; no Java BPA pattern this session):

If the user asks to convert / migrate a Dispatcher configuration to AEM as a Cloud Service, follow the 6-phase flow. It wraps Adobe's maintained @adobe/aem-cs-source-migration-dispatcher-converter as the conversion engine and adds detection, config generation, output verification, judgment, and validation on top. Start by reading references/dispatcher/context.md. Skip Branch B.

1. Inventory — run scripts/dispatcher-inventory.js (buildInventory) to detect the mode (standard / flexible / ams / already-cloud / not-dispatcher / v1 / unknown) and count filter / rewrite / cache rules. (ams is a monolithic AMS on-premise config — converted via the same on-prem executor as flexible, just labelled honestly.) Modes and signals are defined in references/dispatcher/context.md. If the mode is already-cloud, not-dispatcher, or unknown, STOP with that finding — the first two have nothing to convert, and unknown is an ambiguous/incomplete layout to confirm with the user before running the content-blind tool (resolveExecutor falls unknown through to the on-prem executor, so the agent is the gate here).
2. Plan + generate config.yaml — build the converter config per references/dispatcher/config-generation.md (per-mode mapping; variablesToReplace is a flat mapping, portsToMap is a list, appendToVhosts is a file path).
3. Execute — ensureToolInstalled (auto-installs the Adobe tool into the gitignored scripts/dispatcher-tool/node_modules/ on first use) then runConverter (scripts/dispatcher-run.js); the executor is selected by mode (standard → main.js, flexible / on-prem → singleFileMain.js).
4. Verify + normalize — run scripts/dispatcher-verify.js and apply references/dispatcher/output-verification.md. HARD STOP on filter-acl-loss (an empty filters.any when the baseline had filter rules): the conversion is not usable until it is resolved.
5. Judgment + cross-boundary — apply the decision catalog in references/dispatcher/conversion-patterns.md; hand any Cloud Manager environment variables to Branch A (OSGi → Cloud Manager); flag CDN-candidate rules. Target end-state conventions are in references/dispatcher/current-sdk-conventions.md. To operationalize this handoff, run scripts/dispatcher-crossboundary.js to build the Cloud Manager variable handoff artifact, then apply references/dispatcher/cross-boundary.md to route each concern — CM vars → Branch A; immutable freshness → the dispatcher skill's sdk(diff-baseline); security headers / edge → security-hardening; validation → config-authoring.
6. Validate — validate the converted src per references/dispatcher/validation.md (delegates to the dispatcher skill's SDK validator + guardrails); iterate until clean. Do not present the result as done on validation failure. After validation, render the consolidated report with scripts/dispatcher-report.js (renderReport → writeReport) as conversion-report.md, which includes the coverage counts, the CM handoff, and the delegated next-checks checklist.

When to Use This Skill

• Migrate legacy AEM Java toward Cloud Service–compatible patterns (scheduler, ResourceChangeListener, replication, EventListener/EventHandler, AssetManager)
• Fix HTL (Sightly) lint warnings (data-sly-test: redundant constant value comparison)
• Fix Vault package install-time dependencies (day/cq60/product:*) blocking package installation on AEMaaCS
• Swap Guava cache (com.google.common.cache.*) for Caffeine (guavaCache)
• OSGi → Cloud Manager secret/variable externalization (Branch A), Template Modernization (Branch C), Legacy UI dialog/CDW migration (Branch D)
• Drive work from BPA (CSV or cached collection) or CAM via MCP, one pattern per session
• Dispatcher Conversion: Branch E — convert AMS / on-premise Apache+Dispatcher configs to AEMaaCS via Adobe's dispatcher-converter, with mode detection, config generation, output verification (filter/ACL hard-gate), cross-boundary handoff, and SDK validation. References: references/dispatcher/.

Branch routing and the read-first delegation for each entry above are defined once in Required delegation — this list is only the "when."

Prerequisites

• Project source and Maven/Gradle build
• BPA CSV or MCP access optional but recommended
• For htlLint: ui.apps or equivalent content package with .html HTL templates

BPA findings — flow

Scripts run via getBpaFindings (see Calling the helper); do not reimplement collection logic by hand unless the helper is unavailable.

The helper has two independent paths, chosen by what the caller configures:

1. MCP configured (mcpFetcher + projectId passed) → first call fetches all findings from MCP and caches them to <collectionsDir>/mcp/<projectId>/<pattern>.json. Every call (first and subsequent) reads from the MCP cache and returns one batch.
2. MCP not configured, BPA CSV provided → first call parses the CSV and writes the unified-collection JSON to <collectionsDir>/unified-collection.json. Every call reads from the CSV cache and returns one batch.

The two caches are disjoint — MCP sessions and CSV sessions never shadow each other. If neither is configured, the helper reports no-source and the agent asks for one.

Batching is mandatory on every path: getBpaFindings returns a batch of 5 (result.targets) plus a result.paging envelope { total, returned, offset, limit, nextOffset, hasMore }. Process one batch, report, stop, and resume only on the user's go-ahead — full rules in Batched processing (batch size 5) below.

Note: htlLint does not appear in BPA CSV — it uses proactive rg discovery instead. See htlLint flow below.

CAM via MCP (summary)

Use fetch-cam-bpa-findings-by-pattern for code-transformer pattern flows (scheduler, assetApi, eventListener, resourceChangeListener, eventHandler, guavaCache, lui, cdw) and fetch-cam-bpa-findings-by-importance when the user instead asks "what are the critical/major/advisory/info findings?" (returns the latest BPA report's authoritative _COUNT_<code> rows at one importance level, sorted by descending count). Either tool requires explicit user confirmation of the project before being called — ask the user for their CAM project name or ID; the tools resolve it internally (prefer projectId when known). Do not pass an unconfirmed project name string. Full tool schemas, REST notes, retries, and error handling: references/cam-mcp.md.

Calling the helper

Scripts live under ./scripts/ (next to this SKILL.md).

const { getBpaFindings } = require('./scripts/bpa-findings-helper.js');

// First batch (defaults: limit=5, offset=0)
const result = await getBpaFindings(pattern, {
  bpaFilePath: './cleaned_file6.csv',
  collectionsDir: './unified-collections',
  projectId: '...',
  mcpFetcher: mcpFunction
  // limit: 5,   // implicit default
  // offset: 0,  // implicit default
});

// Next batch — only after the user says to continue
if (result.paging?.hasMore) {
  const next = await getBpaFindings(pattern, {
    bpaFilePath: './cleaned_file6.csv',
    collectionsDir: './unified-collections',
    projectId: '...',
    mcpFetcher: mcpFunction,
    offset: result.paging.nextOffset
  });
}

result:

• success, source ('unified-collection' | 'bpa-file' | 'mcp-server' | …)
• message (includes a human-readable batch status)
• targets — the current batch (length <= limit)
• paging: { total, returned, offset, limit, nextOffset, hasMore } — always present on successful calls

To disable batching for a one-off programmatic caller, pass limit: null. The skill workflow itself never does this.

Collection caching

Collections live under ./unified-collections/. If a collection exists and the user supplies a new CSV, ask whether to reuse or re-process.

Reading a BPA CSV

Filter rows where pattern matches the session pattern. Typical columns: pattern, filePath, message.

MCP errors and fallback

Critical: On MCP failure, stop the workflow immediately and give the user the exact tool error message (verbatim), including "not found" / 404-style project errors. Do not continue with migration steps, infer a different CAM project from the workspace, or switch to manual/local migration on your own.

Exception: enablement restriction errors (prefix documented in references/cam-mcp.md) must be shown verbatim with no paraphrase and no automatic fallback until the user addresses them.

After stopping, you may summarize what failed in plain language and, if helpful, re-show projects from list-projects. Only continue when the user explicitly directs the next step (e.g. correct project id/name from the list, BPA CSV path, or specific Java files for manual flow).

For retries, error categories, and when user-directed CSV/manual paths are allowed, follow references/cam-mcp.md; still no silent fallback. Never hide tool errors from the user.

Optional prompt after stop (user must reply): "Reply with the CAM project to use (id or name from the list), a path to your BPA CSV, or the Java files for a manual migration."

Pattern guides

Do not duplicate the pattern table here. Use {code-assessment}/SKILL.md → Pattern Guides — five patterns each have a pattern guide ({code-assessment}/<pattern>/SKILL.md); shared topics (SCR→DS, ResourceResolver/SLF4J, HTL lint, prerequisites hub) stay as references ({code-assessment}/references/<file>.md); vault-package-dependencies is a migration-only reference (references/vault-package-dependencies.md), not a {code-assessment} pattern guide. See Branch B step 2 above for the per-pattern routing table.

Workflow

Step 0: Migration runbook (review / scan entry point)

When the user opens with a broad review/scan request — "review my code for AEMaaCS migration", "scan my project for AEM migration", or similar — and does not name a single pattern, generate a read-only migration runbook before any apply work.

The runbook covers every pattern the migration skill can address. Each pattern declares a detection strategy — CSV-eligible patterns run the priority cascade; the others keep their existing discovery behaviour:

htlLint, osgiConfig, vault-package-dependencies, and the content-scan fallback for lui/cdw/templateModernization are heuristic (tagged confidence: heuristic in the cache) — candidate matches, not compiler-validated. BPA-sourced lui/cdw/templateModernization/replication/guavaCache findings are authoritative. Out of scope: inject-in-sling-model and outdated-dependencies (those belong to code-assessment's own runbook, not migration).

BPA is the source of truth when a report is available. lui/cdw/templateModernization/replication are read from the BPA CSV/CAM (the parser now extracts these subtypes and excludes _COUNT_*/_STAT summary rows), so the runbook counts match your BPA report's LUI-dialog / CDW / static-template / REP tallies. lui keeps only the dialog sub-types (legacy.custom.component → create-component; legacy.static.template is counted under templateModernization). The .content.xml scan is only the fallback when no BPA source is present — and it can undercount relative to BPA when the flagged legacy nodes live in packages (e.g. acs-commons) not in the project source. replication: BPA replication.agent findings when a report is present, else the analyzer detects Replicator usage from source.