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
Please 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.
Pre-migration requirements
Before you start the migration process, do the following:
Complete 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 update modules in Drupal.
Steps to migrate
If your system already uses the latest version of the media_acquiadam module (2.1.x) and acquia_dam version 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 -ycommand or navigate to the /update.php page in your Drupal installation. This process also enables the media_acquiadam module.
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.
Media Source Selection
Media Type Selection
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 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 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.
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.
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.
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.
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
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.
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:
Migrate asset data with the following Drush command:
drush acquiadam:migrate-data
Clear the Drupal cache to ensure that the site reflects all changes.
Asset update and synchronization
To synchronize the asset after data migration, complete the following steps:
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:
For assets that do not have version_id or external_id, run the following Drush command separately for each media type:
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
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
After the update, clear the Drupal cache to ensure that the system reflects the changes:
drush cr
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.
To ensure that assets are correctly located after migration, run the following Drush command for each migrated media type:
After the update, clear the Drupal cache to ensure that the system reflects the changes:
drush cr
Ensure that the Acquia DAM integration works correctly. Test media uploads, retrievals, and rendering within the content of the site.
Troubleshoot asset rendering: 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 for the auto-resolution process to correctly map these assets to an appropriate media type.
Post migration
To finalize the migration process, complete the following steps:
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:
Remove the Acquia DAM Asset Importer contributed module with the following Composer command:
composer remove drupal/acquiadam_asset_import
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
Clear the cache.
Ensure that permissions for content editors and administrators work as expected.
After you ensure that the integration works:
Remove unnecessary legacy fields with the following Drush command:
drush acquiadam:post-migrate
Clear the Drupal cache to ensure that the site reflects all changes.
Uninstall the Media: Acquia DAM module.
How do I migrate from Media: Acquia DAM to the Acquia DAM module?
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 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
Please 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.
Pre-migration requirements
Before you start the migration process, do the following:
Complete 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 update modules in Drupal.
Steps to migrate
If your system already uses the latest version of the media_acquiadam module (2.1.x) and acquia_dam version 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 -ycommand or navigate to the /update.php page in your Drupal installation. This process also enables the media_acquiadam module.
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.
Media Source Selection
Media Type Selection
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 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 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.
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.
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.
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.
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
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.
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:
Migrate asset data with the following Drush command:
drush acquiadam:migrate-data
Clear the Drupal cache to ensure that the site reflects all changes.
Asset update and synchronization
To synchronize the asset after data migration, complete the following steps:
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:
For assets that do not have version_id or external_id, run the following Drush command separately for each media type:
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
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
After the update, clear the Drupal cache to ensure that the system reflects the changes:
drush cr
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.
To ensure that assets are correctly located after migration, run the following Drush command for each migrated media type:
After the update, clear the Drupal cache to ensure that the system reflects the changes:
drush cr
Ensure that the Acquia DAM integration works correctly. Test media uploads, retrievals, and rendering within the content of the site.
Troubleshoot asset rendering: 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 for the auto-resolution process to correctly map these assets to an appropriate media type.
Post migration
To finalize the migration process, complete the following steps:
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:
Remove the Acquia DAM Asset Importer contributed module with the following Composer command:
composer remove drupal/acquiadam_asset_import
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
Clear the cache.
Ensure that permissions for content editors and administrators work as expected.
After you ensure that the integration works:
Remove unnecessary legacy fields with the following Drush command:
drush acquiadam:post-migrate
Clear the Drupal cache to ensure that the site reflects all changes.
Acquia DAM