--- title: "How do I migrate from Media: Acquia DAM to the Acquia DAM module?" date: "2025-05-20T11:13:56+00:00" summary: "Streamline your Drupal asset management: Migrate from Media: Acquia DAM to Acquia DAM module with our step-by-step guide." image: type: "page" url: "/acquia-dam/how-do-i-migrate-media-acquia-dam-acquia-dam-module" id: "996221d5-ba41-4ab6-8abd-95698cefe8a8" --- Table of contents will be added The Media: Acquia DAM to Acquia DAM migration tool lets you transfer media types within the Drupal application. Features -------- The tool offers several key features and capabilities: * Transfers media types with associated assets efficiently between different modules. * Preserves site and user authentication during the migration of digital assets and associated metadata. * Integrates key features such as embed and download options with no disruption to ongoing workflows. * Enhances platform capabilities and functionalities, which enables users to migrate media types to Acquia DAM with no effect on the media system. * Provides the flexibility to uninstall the [media\_acquiadam](https://www.drupal.org/project/media_acquiadam) module. Scope of migration ------------------ The migration covers: * Transition of integration from the [media\_acquiadam](https://www.drupal.org/project/media_acquiadam) module to the [acquia\_dam](https://www.drupal.org/project/acquia_dam/releases/1.1.2) module. * Migration of all media assets, such as images, videos, and PDFs, along with associated metadata. * Configuration of the Media Library and Acquia DAM integration features. Important considerations ------------------------ Be aware of the following changes in the new module: * **Entity Browser** support has been discontinued, use the Media Library instead. * Copy-paste of `asset_id` in the media add form is not supported in Acquia DAM, use the Media Library instead. Note Media components within Site Studio that were using the media type provided by Media: Acquia DAM module will not be affected by the migration itself. However, these components may retain the media type that was deleted during the migration within their "bundles" list. While this has no impact on the functionality or usage of the component or Site Studio as a whole, it is recommended that you re-save those components post migration to remove the deleted media type from the component's configuration. Pre-migration requirements -------------------------- Before you start the migration process, do the following: 1. Complete a full backup of your Drupal site's database and file system. 2. Verify your administrative permissions to access the migration dashboard. 3. Confirm your permissions to update modules in Drupal. 4. Uninstall the **Media: Acquia DAM - Reporting** module, as this reporting functionality is not currently supported in the new Acquia DAM module. Steps to migrate ---------------- If your system already uses the latest version of the [media\_acquiadam module (2.1.x)](https://www.drupal.org/project/media_acquiadam) and [acquia\_dam version 1.1.5](https://www.drupal.org/project/acquia_dam/releases/1.1.5) or newer, and you have previously performed the database update, you may skip the version upgrade and database update. ### Upgrade to the latest version (2.1.x):  Upgrade the module with Composer or through the Drupal UI. composer require drupal/media_acquiadam:^2.1 ### Run database update:  You must run the database update to apply necessary database schema changes and configuration updates. This step ensures that the new version of the Media Acquia DAM module functions correctly. Use the `drush updb -y` command or navigate to the _/update.php_ page in your Drupal installation. This process also enables the [media\_acquiadam](https://www.drupal.org/project/media_acquiadam) module. ![Run database update](https://acquia.widen.net/content/070514f2-8e41-4634-a7b2-1e3c458aa57d/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000KxSHi.png) ### Use the migration dashboard to perform migration After the upgrade and database update steps are completed, navigate to the migration path `/admin/config/acquia-dam/migration` within the Drupal user interface. This leads to the _Migration Dashboard_, which provides a clear overview of the migration status. A 3-step wizard guides you through the migration process to ensure a smooth and structured migration experience. 1. Media Source Selection 2. Media Type Selection 3. Pre-Migration Review You can progress through the steps sequentially, with options to review, confirm, and proceed at your own pace. #### Media source selection This dashboard helps you migrate legacy media types to Acquia DAM. It provides a map between [media\_acquiadam](https://www.drupal.org/project/media_acquiadam "https://www.drupal.org/project/media_acquiadam") media types to their corresponding media sources in Acquia DAM. The table displays the media types, the total number of media items, the display handler for media assets, and the target media source that requires migration. This dashboard enables you to track the progress and completion of the migration. The details of each column are: * **Media type label and name**: You may change the label during the migration to the Acquia DAM system. * **Number of media items**: Count of DAM assets in each media type that requires migration. * **Method to handle media files**: Two methods are provided: * **Sync**: This method renders assets locally. * **Embed**: This method renders assets from the Widen CDN.  **Target source type**: You receive a list of Acquia DAM media sources. You must select the target source for asset migration. ![Media source selection](https://acquia.widen.net/content/cfa5bd7c-2400-473e-b7e7-bf2bd3ff258e/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000Kxvrb.png) #### Media type selection This page displays a list of new media types from the Acquia DAM module. Select the checkbox on the same row as any media type that you do not want to keep. You must indicate if you want to keep the suggested media types. Select them for deletion if they are not required. Note If you deselect any suggested media type, a warning appears to alert you about potential duplication within the system. ![Media type selection](https://acquia.widen.net/content/11d04983-fc9e-4cd4-a8c4-13f2d6f4ae89/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000Ky3lv.png) #### Pre-migration review After you review and confirm the media types selected for deletion, click **Save & Next** to move to the final step. This action takes you to the pre-migration report, which provides a summary of the current status before the migration begins. ![Pre-migration review](https://acquia.widen.net/content/1d616ba6-1763-4e1f-8e7e-afc786be9bc2/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000KxcnN.png) ### Migration interfaces After the configuration is saved, migration can be performed through either of the following: * Admin user interface * Command-line interface #### Through the Admin user interface Verify the data and click **Migrate** to begin the migration process. The assets migrate in batches. A progress bar displays the status of the migration in real time. ![real time progress](https://acquia.widen.net/content/97d7a47b-c183-4833-9275-b36b4e069300/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000KyPfx.png) At the end of the process, the system displays a migration summary. This summary provides a detailed overview of the media items successfully migrated, categorized by each media type. ![Through admin user interface](https://acquia.widen.net/content/073a2548-266e-4023-a881-6f70fa423116/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000KyQFR.png) Note The media type provided by the **Media: Acquia DAM** module remains after migration, it is not deprecated or deleted. Instead, the source plugins for this media type are updated to use the new **Acquia DAM** module. #### Through the command-line interface After you click **Save** on the last page of the migration dashboard, you can choose to do the asset migration with the Drush command: drush acquiadam:migrate ![Through Command-line interface](https://acquia.widen.net/content/23ade636-447f-414d-ab28-432d7050f806/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000KyQov.png) ### Validate migration After the migration, ensure that: * All media types and associated assets are transferred and visible in the Acquia DAM Library at `/admin/content/media`. * Metadata, files, and references remain intact in the content. * Duplicate media types are deleted from the system. ![Validate migration](https://acquia.widen.net/content/0bbdc2d6-1399-4a30-b85e-6ede8d76a876/web/ka0Pb000000FK9h00N6g00000WDN1a0EMPb00000Ky8SE.png) ### Asset data migration  Note * Only perform these steps if you are following a configuration synchronization approach for migration. * After the config deployment, assets temporarily stop rendering until the data migration is complete. You must perform this data migration activity as soon as possible after the config deployment to minimize downtime. To finalize the asset data migration, complete the following steps: 1. Migrate asset data with the following Drush command: drush acquiadam:migrate-data 2. Clear the Drupal cache to ensure that the site reflects all changes. ### Post migration  To finalize the migration process, complete the following steps: 1. If you use the _Acquia DAM Asset Importer_ module, switch to the _Acquia DAM Bulk Asset Import_ submodule. To migrate the configuration from the _Acquia DAM Asset Importer_ contributed module to the _Acquia DAM Bulk Asset Import_ submodule, complete the following steps: 1. Remove the _Acquia DAM Asset Importer_ contributed module with the following Composer command:   composer remove drupal/acquiadam_asset_import 2. Run database updates to ensure that the system applies necessary database schema changes and configuration updates for the _Acquia DAM Bulk Asset Import_ submodule with the following Drush command: drush updb 3. Clear the cache. 2. Ensure that permissions for content editors and administrators work as expected. 3. After you ensure that the integration works: 1. Remove unnecessary legacy fields with the following Drush command: drush acquiadam:post-migrate 2. Clear the Drupal cache to ensure that the site reflects all changes. 3. Uninstall the _Media: Acquia DAM_ module. ### Asset update and synchronization To synchronize the asset after data migration, complete the following steps: 1. All assets are missing both the version\_id and external\_id, meaning the assets are out of sync. To make all assets in sync, complete the following steps: 1. For assets that do not have `version_id` or `external_id`, run the following Drush command separately for each media type: drush acquia-dam:update-assets --media-type= 2. Ensure that the asset update queue: `acquia_dam_media_item_update` is empty before you upload or retrieve media with the Drush command: drush queue:list 3. If the queue is not empty, process the asset update queue to fetch the `version_id` and `external_id` of the asset from Acquia DAM with the Drush command: drush queue:run acquia_dam_media_item_update 4. After the update, clear the Drupal cache to ensure that the system reflects the changes: drush cr 2. If you selected the **Sync** option during Media Type Migration, you may optionally complete the following steps to download assets into the `**dam**` directory. If skipped, assets are served from the legacy `**acquiadam**` directory. 1. To ensure that assets are correctly located after migration, run the following Drush command for each migrated media type: drush acquia-dam:download-assets --redownload 2. After the update, clear the Drupal cache to ensure that the system reflects the changes: drush cr 3. Ensure that the Acquia DAM integration works correctly. Test media uploads, retrievals, and rendering within the content of the site. 4. Troubleshoot asset rendering: 1. If assets from a specific media type fail to render correctly after migration, the new media type source may not support that asset type. To resolve this, refer to the [documentation](/acquia-dam/how-do-i-use-media-type-auto-resolution-feature "How do I use the media type Auto-Resolution feature?") for the auto-resolution process to correctly map these assets to an appropriate media type. 2. If SVG assets fail to render correctly after migration, you will need to download and install the contributed [Svg Image](https://www.drupal.org/project/svg_image) module. 1. Require the Svg Image module with the following Composer command: composer require drupal/svg_image 2. Install the Svg Image module with the following Drush command: drush in svg_image