Rename/Move an AEM Asset programmatically and Update References

[#1]

Rename/Move an AEM Asset programmatically and Update References  by Aanchal Sikka

Overview

Renaming or moving assets in AEM while keeping all references intact is a common challenge for developers. Basic APIs like AssetManager.moveAsset() can rename or relocate assets but do not update references across your site, often leading to broken links.

This blog breaks down two approaches:

• Using AssetManager.moveAsset() for simple moves without reference updates.

• Alternate way with CopyMoveCommandBuilder, which renames assets and automatically updates all references, ensuring content consistency.

The blog includes sample servlet code demonstrating how to implement the CopyMoveCommandBuilder approach. 

Link to blog: https://techrevel.blog/2025/10/07/rename-move-an-aem-asset-programmatically-and-update-references/ 

Q&A

Please use this thread to ask questions relating to this article

[#2]

@aanchal-sikka  Thanks for sharing 

[#3]

@aanchal-sikka, thanks for sharing this, very insightful breakdown! 👏

The comparison between AssetManager.moveAsset() and CopyMoveCommandBuilder is super helpful, since maintaining references is one of the trickiest parts of asset management in AEM.

Just checking: how you usually approach asset moves in your projects. Do you tend to stick with AssetManager.moveAsset() for simpler scenarios, or do you mostly go with CopyMoveCommandBuilder to handle reference updates automatically? I’d love to hear your thoughts on the trade-offs you consider when choosing between the two.

[#4]

Thanks for the query @kautuk_sahni 

We use assetManager.moveAsset() for moving assets that aren't referenced by other AEM resources (e.g., Sites, language copies). This is suitable for assets like product images syndicated to external platforms (Amazon, Walmart) where reference checking is not needed. If references exist, we use CopyMoveCommandBuilder.