/asset-manager

name: asset-manager
description: AEM Cloud Service expert skill for the Asset Manager API (com.day.cq.dam.api.AssetManager). Covers two migration paths — Path A (create/upload, replacing createAssetForBinary/getAssetForBinary/client-facing createAsset with Direct Binary Access via @adobe/aem-upload) and Path B (delete, replacing removeAssetForBinary with in-JVM resolver.delete() + commit or external HTTP Assets API with IMS bearer tokens). Covers IMS authentication, service-user setup with crx delete permissions, asset processing pipeline, common pitfalls (hardcoded credentials, AEM calling its own HTTP API), and composition with replication/event-migration skills.
license: Apache-2.0

Asset Manager API — AEM as a Cloud Service

Overview

`com.day.cq.dam.api.AssetManager` is **not removed** on AEM CS — but several of its operations are. The binary-path APIs that relied on direct filesystem access (`createAssetForBinary`, `getAssetForBinary`, `removeAssetForBinary`) **do not exist on CS** because the cloud runtime does not expose a filesystem path to the AEM JVM. Binary I/O for client uploads moves to **Direct Binary Access** — bytes flow directly between the client and Adobe's binary store, bypassing the JVM entirely.

**API status on AEMaaCS:**

| API | Status | What to use instead | |-----|--------|---------------------| | `AssetManager.getAsset(path)` | ✅ **Supported** | No change — still works for reads | | `AssetManager.createAsset(path, InputStream, mimeType, doSave)` | ⚠️ **Strongly discouraged for client-facing uploads** (2 GB binary limit, blocks the JVM, asset-processing pipeline expects Direct Binary Access). Still callable for in-JVM utilities where the binary is small and already in the JVM (bundled resources, fixtures, back-office imports). | **Direct Binary Access** for client uploads (`@adobe/aem-upload` JavaScript SDK). In-JVM small-file creation OK. | | `AssetManager.createAssetForBinary(binaryFilePath, doSave)` | ❌ **Removed** — relied on filesystem path the cloud runtime does not expose | **Direct Binary Access** | | `AssetManager.getAssetForBinary(binaryFilePath)` | ❌ **Removed** | `resolver.getResource(repoPath).adaptTo(Asset.class)` — look up by repository path, not binary path | | `AssetManager.removeAssetForBinary(binaryFilePath, doSave)` | ❌ **Removed** | In-JVM: `resolver.delete(resource) + resolver.commit()`. External: HTTP Assets API `DELETE /api/assets{path}` |

**Three CS-specific principles:**

| Principle | Why | |-----------|-----| | Binary I/O for client uploads goes Direct Binary Access — never through the JVM | The cloud runtime does not have a JVM-accessible filesystem; bytes through the JVM are slow, memory-bound, and blocked by a 2 GB ceiling | | In-JVM delete uses `resolver.delete()` + `resolver.commit()` with a service user — never AEM calling its own HTTP API | Self-looping HTTP adds latency, requires credentials you shouldn't store, and breaks idempotency | | External callers authenticate with **IMS / dev-console bearer tokens** — never hardcoded passwords or `userId:password` strings | AEMaaCS has no admin user with a static password; IMS service credentials are the only supported external auth path |

---

Classification — choose before making any changes

**Uses `AssetManager.createAssetForBinary(...)` or `AssetManager.getAssetForBinary(...)`** (removed APIs) → Apply **Path A** (C1–C3).

**Uses `AssetManager.createAsset(path, InputStream, mimeType, doSave)` in a client-facing servlet** (accepts upload from a browser or external caller) → Apply **Path A** — migrate to Direct Binary Access (C2 client-facing branch).

**Uses `AssetManager.removeAssetForBinary(...)`** (removed API) → Apply **Path B** (D1–D3).

**Uses both a removed create API AND a removed delete API** → Apply **Path A first, then Path B**. Both transformations are independent.

**Uses `AssetManager.getAsset(path)` only** (read access) → Already compliant — no migration needed.

**Uses `AssetManager.createAsset(path, InputStream, mimeType, doSave)` in an in-JVM back-office utility** (scheduled import, test fixture, asset post-processing — binary is already in the JVM and small) → Already supported — verify the surrounding code uses a service-user resolver and closes the stream in try-with-resources, then skip.

**One pattern per session.** If the file has multiple flows, migrate one direction (create OR delete) at a time.

**Before starting:** Read [`../references/aem-cloud-service-pattern-prerequisites.md`](../references/aem-cloud-service-pattern-prerequisites.md) and apply SCR→DS, service-user, and SLF4J fixes if present in the same changeset.

---

Discovery

Detection is performed by the analyzer ([`../scripts/analyze.sh`](../scripts/README.md)), run by the runbook:

bash ../scripts/analyze.sh <workspace-root> --pattern asset-manager

**Match criteria (what the detector flags):** in a file importing **`com.day.cq.dam.api.AssetManager`**, a call to **`createAssetForBinary`**, **`getAssetForBinary`**, **`removeAssetForBinary`**, or **`createAsset`**. **One finding per call site** (each call is individually actionable, unlike the class-level patterns), with the call as the snippet. Parse-level only — gated on the import; the receiver type is not resolved, so an unrelated `createAsset(...)` in the same file could match (rare).

Resolution contract

**guided** — `apply (guided)`. The analyzer reports each legacy call site; remediation is judgment-based, routed by the call (create/upload → C1–C3, delete → D1–D3) and applied in an apply session.

| Call site | Disposition | |---|---| | `createAssetForBinary` / `getAssetForBinary` (removed on CS) | apply (guided) → C1–C3 | | `removeAssetForBinary` (removed on CS) | apply (guided) → D1–D3 | | Client-facing `createAsset(...)` upload | apply (guided) → C1–C3 (Direct Binary Access) | | In-JVM back-office `createAsset(...)` with a service-user resolver | skipped: `already-compliant` | | Test code (`src/t