Asset/CF location change in AEM Assets

[ShashankJa1]

Hi,

If I need to change the location of an asset or content fragment in AEM Assets (e.g., move it to a different folder) and it is referenced on a few pages, how can I do this without breaking anything and without needing to re-publish the pages? Is there a workflow or job available in AEM Assets out-of-the-box (OOTB) for this purpose?

Thanks

[SantoshSai]

Hi @ShashankJa1,

When you move an asset or a content fragment to a different location, you can do so safely using the "Move" operation provided in AEM Assets, which preserves references and updates them automatically - without breaking anything or needing to re-publish pages manually.

Use “Move” functionality via the UI

What it does:

• Updates all references (e.g., pages, templates, content fragments, Experience Fragments).

• Preserves version history and metadata.

• Optionally re-publishes the moved asset and its dependencies (if enabled).

How to Move safely via AEM Assets UI

1. Go to AEM Assets (/assets.html)

2. Navigate to the asset or content fragment.

3. Select the asset and click the "Move" icon from the top toolbar.

4. A wizard opens:

   • Select the new destination folder.

   • Enable the option “Update References” (usually checked by default).

5. Click Move.

AEM internally updates all references (including in /content, /conf, etc.) via its ReferenceUpdateService.

Does this require republishing?

• No, you don’t need to re-publish the pages unless:

  • The moved asset itself is not published yet in the new location.

  • You want the new path to be reflected on the published site (e.g., for direct asset links).

AEM uses internal resource references (UUID-based), so pages referencing the asset will automatically point to the new path, and continue working without needing republishing.

Is there a workflow or job OOTB?

Yes:

AEM OOTB services involved:

1. ReferenceUpdateService – Automatically updates all references to the moved asset.

2. Move Page/Asset Workflow – Triggers updates and asset management tasks under the hood.

3. DAM Update Asset (optional) – Might be invoked after move to refresh renditions/metadata (configurable).

You do not need to create a custom workflow unless you have special post-move logic.

[ShashankJa1]

Thank you for the detailed explanation. I appreciate it.

I have one more related question: What happens in a scenario where I need to rename a folder?

[SantoshSai]

When you rename a folder in AEM Assets (e.g., /content/dam/project/images → /content/dam/project/images-new), the situation is similar to moving assets—but with additional impact due to multiple assets potentially affected.

What AEM does when you rename a folder

1. All assets and subfolders under the renamed folder are moved to the new path.

2. References to assets inside that folder are updated via AEM’s ReferenceUpdateService, just like in a move operation.

3. Paths in components, pages, content fragments, etc. are rewritten to the new folder structure—as long as you rename via AEM UI or APIs that trigger the move service.

Important: must rename via AEM UI

To preserve references:

• Do use:

  • AEM UI’s “Move” option (which supports folder renaming).

  • Move operation in Assets Console or Sites Console.

  • Programmatic moves using PageManager.move() or JCR Session move() with ReferenceUpdateService.

• Do NOT rename using:

  • CRX/DE directly (it bypasses reference updates).

  • AEM repository browser (e.g., JCR nodes manually renamed without triggering reference services).