Acquia DAM (Widen)
How to migrate from Drupal local media to Acquia DAM?
The Drupal local media to Acquia DAM migration sub-module in the Acquia DAM module version 1.1.18 or later lets you migrate Drupal local media assets to Acquia DAM. This sub-module preserves field data and entity references within your Drupal application.
The tool offers several key capabilities:
Migrates Drupal image, video, document, and file media types to their corresponding Acquia DAM media types.
Preserves field data and entity references across nodes, paragraphs, and other host entities.
Provides a step-by-step migration wizard in the Drupal administrative UI for a controlled, reviewable migration process.
Processes large media libraries in batches.
The migration covers:
Transitioning from local media to the Acquia DAM module.
Migrating all media assets, such as images, videos, and PDFs, along with associated metadata.
Configuring Media Library and Acquia DAM integration features.
Before you start the migration process, ensure that you:
Take a full backup of your Drupal site's database and file system.
Verify your administrative permissions to access the migration dashboard.
Confirm your permissions to install modules in Drupal.
Confirm that the upload profiles you plan to use for asset migration are configured to not expire assets on upload. For more information, visit How do I create Upload Profiles?.
Verify that all selection fields, including dropdowns and palettes, are fully populated with required values prior to migration. Any payload values missing from these fields will not be preserved in the asset metadata.
Upgrade the module using Composer or through the Drupal UI:
composer update drupal/acquia_dam:^1.1.18
Install the migration submodule using Drush or the Drupal UI:
drush en acquia_dam_migration_tools -y
Before you start the migration, configure the view display in equivalent Acquia DAM media types to match your Drupal local media types. For example, if you configure multiple view displays for the Image media type, configure similar view displays for Acquia DAM: Image.
Enable all image styles that you currently use with the Drupal local image type at /admin/config/acquia-dam/image-styles.
After completing the upgrade step, navigate to /admin/config/acquia-dam/drupal-to-dam-migration the Drupal user interface. This opens the Migration Dashboard, which provides a clear overview of the migration status.
The migration process is guided through a three-step wizard:
Media type and upload profile selection
Metadata mapping
Pre-migration review
Progress through these steps sequentially, with options to review, confirm, and proceed at your own pace.
This dashboard facilitates the migration of local media assets to Acquia DAM by mapping local media types to their corresponding media types in Acquia DAM. The table displays media types, total media item counts, upload profiles, and target media types.
Column descriptions:
Media type label and name: Displays the specific names of Drupal local media types.
Number of media items: Count of local assets in each media type that require migration.
Profile: Select the asset upload profile for handling media.
This interface provides a list of your chosen media types for the transition. Within this section, perform metadata mapping by aligning Drupal core media fields with Acquia DAM fields to ensure local data is accurately integrated into Acquia DAM.
After you review and confirm the media types selected for migration, click Save & Next to proceed to the pre-migration report, which provides a summary of the current status before the migration begins.
After saving the configuration, you can perform the migration through either of the following:
Admin user interface
Command-line interface
Verify the data and click Migrate to begin the migration process. Assets migrate in batches, and a progress bar displays the migration status in real time.
At the end of the process, the system displays a migration summary with a detailed overview of the media items successfully migrated, categorized by media type.
After you click Save configuration on the last page of the migration dashboard, you can also run the migration using the following Drush command:
Acquia DAM (Widen)drush acquia-dam:migrateAfter migration completes, verify the following:
Media Library: Open /admin/content/media and confirm migrated assets appear with correct titles, thumbnails, and media types.
Field references: Open a sample node that previously used local media and confirm the media field still resolves and renders correctly.
Views: If any Views use media entity fields (such as image fields in listings), verify they render without broken references.
Metadata: Open a migrated media item and confirm DAM fields (such as alt text, caption, and custom metadata) are populated as expected.
DAM sync status: Confirm the asset is visible in Acquia DAM and linked back to the Drupal media entity.
Download or embed behavior: Based on the download_assets setting of the target media type, confirm assets are either embedded via URL or downloaded to the Drupal file system as expected.
SVG assets (if applicable): Confirm SVG files render correctly on the front end.
To finalize the migration, complete the following steps:
Verify that permissions for content editors and administrators work as expected.
After confirming the migration is successful, clear the Drupal cache to ensure the site reflects all changes.
To synchronize assets after migration, complete the following steps:
Confirm that the Acquia DAM integration is functioning. Test media uploads, retrievals, and rendering within site content.
Troubleshoot asset rendering:
If assets from a specific media type fail to render after migration, the new media type source may not support that asset type. Refer to the documentation for the auto-resolution process to correctly map these assets to a supported media type.
If SVG assets fail to render, install the contributed SVG Image module:
Require the SVG Image module using Composer:
composer require drupal/svg_imageInstall the SVG Image module using Drush:
drush en svg_image -yIf you are using Focal Point module, post migration synchronize focal point using the following Drush command. For more information, refer to the focal point integration documentation.
drush acquia-dam:update-media-focal-pointMigration interrupted mid-batch
If the migration process is interrupted, re-run drush acquia-dam:migrate. The tool resumes from the last unprocessed batch, and already migrated assets are not duplicated.
Media items not appearing in Acquia DAM after migration
Verify the upload profile is correctly configured and the target media type is enabled.
Check Drupal logs at /admin/reports/dblog for migration errors.
Confirm DAM API credentials are valid at /admin/config/media/acquia-dam.
Metadata fields not mapped correctly
Confirm source fields exist on the Drupal media type before migration.
Verify selection fields (dropdowns and palettes) are populated in Acquia DAM prior to migration.
SVG assets not rendering after migration
Ensure the svg_image module is installed: drush en svg_image -y
Clear the cache: drush cr
Reverting a migration
There is no automated rollback. To revert:
Restore from a pre-migration database backup.
Re-enable local media types if they were disabled.
Verify entity references in content are intact by spot-checking nodes that use local media.
Target media type: A list of Acquia DAM media types from which you can select the desired target bundle for migrating the asset. The method for handling media files (sync or embed) is determined by the download_assets setting of the selected target media type.
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Target media type: A list of Acquia DAM media types from which you can select the desired target bundle for migrating the asset. The method for handling media files (sync or embed) is determined by the download_assets setting of the selected target media type.
If this content did not answer your questions, try searching or contacting our support team for further assistance.