Rename/Move an AEM Asset programmatically and Update References

As an AEM developer, you need to rename or move DAM assets while ensuring that all content referencing those assets remains up-to-date. However, renaming or moving an asset in AEM is not always straightforward due to underlying content references across pages, experience fragments, live copies etc

This blog explores two popular approaches to rename or move an asset in AEM and their impact on updating references, helping you choose the right strategy for your projects.

---

1. Using AssetManager.moveAsset()

AssetManager is the basic API for managing assets in AEM. It provides the moveAsset() method, which allows you to move or rename an asset by specifying its current path and the new target path.

import com.adobe.granite.asset.api.AssetManager;
...

public class RenameAssetDoNotUpdateReference extends SlingSafeMethodsServlet {

    @Override
    protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response)
            throws IOException {

        ResourceResolver resolver = request.getResourceResolver();
        AssetManager assetManager = resolver.adaptTo(AssetManager.class);

        ...
            assetManager.moveAsset(assetPath, newAssetPath);
            resolver.commit();
        ...
}

Complete file here: RenameAssetDoNotUpdateReference.java

• This operation physically renames or moves the asset within the DAM repository.
• The asset’s binary and metadata are preserved.
• However, this method does NOT update references to the asset across other AEM content such as pages or experience fragments.
• This means any page or asset live copy referencing the old asset path will break unless references are manually updated.

Use case:
AssetManager.moveAsset() is suitable if you only need to relocate or rename an asset without worrying about references (for example, during initial asset upload or isolated asset reorganizations).

---

2. Using CopyMoveCommandBuilder — to Rename/Move and Update References

AEM provides a more powerful API for moving or renaming DAM assets that automatically updates all references to the asset in the content repository: CopyMoveCommandBuilder from the com.day.cq.wcm.command.api package.

Features of this approach:

• Performs move or rename operations on assets.
• Automatically tracks and updates all references to the asset across pages, experience fragments, and other AEM managed content.
• Supports integrity checks and reference lookups.
• Can optionally publish pages that reference the asset to reflect changes immediately.

This method mimics the “Move” behavior seen in the AEM Assets UI, where references are updated transparently for content authors.

Below is the sample servlet code demonstrating this approach, which you can adapt and use in your projects:

public class AssetRenameUpdateReferencesServlet extends SlingSafeMethodsServlet {
    private final Logger logger = LoggerFactory.getLogger(getClass());

    @Reference
    private CommandBuilderFactory commandBuilderFactory;

    @Reference
    private AssetReferenceResolver assetReferenceResolver;

    @Override
    protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response)
            throws IOException {
        // Source path of the asset to be renamed
        String srcPath = "/content/dam/techrevel/skitouring1.jpg";
        // Destination path with the new name for the asset
        String dstPath = "/content/dam/techrevel/skitouring1-rename.jpg";

        ResourceResolver resolver = request.getResourceResolver();

        try {
            CopyMoveCommandBuilder copyMoveCommandBuilder = commandBuilderFactory.createCommandBuilder(CopyMoveCommandBuilder.class)
                    .withCopy(false)
                    .withResourceResolver(resolver)
                    .withAssetReferenceResolver(assetReferenceResolver)
                    .withRetrieveAllRefs(true)
                    .withShallow(false)
                    .withCheckIntegrity(true);

            // Build the argument specifying source, destination paths and reference adjustment option
            CopyMoveCommandPathArgument copyMoveCmdPathArg = (CopyMoveCommandPathArgument) copyMoveCommandBuilder.createPathArgumentBuilder()
                    .withSrcPath(srcPath)
                    .withDstPath(dstPath)
                    .withAdjustRefPaths(null)
                    .build();

           copyMoveCommandBuilder.withPathArgument(copyMoveCmdPathArg);

           Command cmd = copyMoveCommandBuilder.build();

            // Execute the rename command
            CopyMoveCommandResult result = (CopyMoveCommandResult) cmd.execute();

            if (result.executionSucceeded()) {
                response.getWriter().write("Asset renamed successfully from " + srcPath + " to " + dstPath);
            } else {    
                response.getWriter().write("Failed to rename asset: " + result.getDestinationPaths());                
            }
        } catch (Exception e) {
            response.getWriter().write("Exception: " + e.getMessage());
        }
    }

Complete file here: AssetRenameUpdateReferencesServlet.java

Additional Tips for Developers:

• Publishing: If references need to be live immediately, use the publish options provided by the CopyMoveCommandBuilder to publish affected pages.