This document provides answers to common questions about the integration and management of assets between Acquia DAM and Drupal.
General
Do users have the same permissions to assets in the module as in DAM?
Yes, users authenticate into DAM first, so their permissions match. Check the user's role permissions if they do not see the correct assets.
Why do I see a 401 Unauthorized Error when I access the Acquia DAM Media Browser in Drupal?
When you access Acquia DAM assets, a 401 Unauthorized Error in the Drupal Media Browser means your current authentication token has expired or is invalid.
To resolve this issue and restore proper access, you must re-authenticate your account with Acquia DAM with the following steps:
Log in to your Drupal application.
Navigate to your user profile, which is usually located at /user.
In your profile menu, click the Acquia DAM tab.
Click Log out to disconnect your Drupal user from Acquia DAM.
After you log out, click Authorize to re-establish a secure connection and obtain a new, valid token.
This process immediately restores your access to DAM assets within the Drupal Media Browser.
Creating and managing DAM media
How do I add a new Acquia DAM asset to Drupal content if I cannot use the /media/add form?
In the new Acquia DAM module, DAM media items are created through the Media Library and not the /media/add form. When you visit /media/add for a DAM media type, the form is disabled and displays a message such as: “Media items cannot be added from this form, only through the media library when editing content.”. To add a DAM asset:
Edit the piece of content where you want to use it.
Open the Media Library from the relevant media field.
Select or search for the desired DAM asset.
This workflow ensures that all DAM media are created and linked with a consistent process, to preserve a clean 1:1 relationship between Acquia DAM assets and Drupal media entities.
Why is Acquia DAM media not supported by Acquia DAM when I paste the /media/add form asset IDs?
In the Acquia DAM module, the ability to fetch and create media items directly by pasting an Asset ID into the /media/add form has been intentionally removed. In earlier implementations, this pattern could inadvertently allow multiple Drupal media items to be mapped to the same DAM asset ID. This led to data inconsistencies, confusion about which version was correct, and problems maintaining a clean 1:1 relationship between assets in Acquia DAM and media entities in Drupal.
To avoid these issues, you are required to select DAM assets through the Media Library when you edit content. After you visit the /media/add form for a DAM media type, the form is disabled and displays a warning such as "Media items cannot be added from this form, only through the media library when editing content." This ensures that all DAM media assets are created and managed through a standardized workflow and that each Drupal media item is reliably linked to a single DAM asset.
Acquia addresses customer feedback about adding DAM assets independently through the /media/add form. All options are evaluated to support this in a way that preserves data integrity and clean 1:1 asset mapping between Acquia DAM and Drupal.
What happens when assets are updated in the Acquia DAM system?
Assets updated in the Acquia DAM system are automatically reflected through the cron job. Additionally, editors have the option to manually run the Check for update action within the Drupal application under the DAM media listing to ensure that the updated assets are quickly reflected in Drupal.
What happens if assets are not updated in the Drupal application after changes are made to the finalized version in the Acquia DAM system?
Even if the cron job runs, the assets are not automatically updated in the Drupal application when the finalized version is changed in the Acquia DAM system. Editors must manually use Check for update within the DAM media listing in Drupal to ensure that the updated assets are promptly reflected in the application.
How do I ensure Drupal updates an asset when I finalize an older version in Acquia DAM?
When you upload a new version of an asset in Acquia DAM and mark it as finalized, Drupal normally detects that change during the next cron run and updates the corresponding media item (or you can force it sooner with Check for update in the DAM media listing).
However, if you revert to an older version of an asset and mark that older version as finalized, the DAM system does not always treat this as a standard asset update event. In those cases, the DAM API may not return any change for Drupal to process, so cron and the DAM media update queue do not update the media item, even though they are running correctly.
To force Drupal to pick up this change, you can:
In Acquia DAM, set the older version as finalized and make a small, non‑critical change to a metadata field such as a temporary description or tag value and the revert the temporary metadata change. This causes the asset to be treated as updated and included in the integration.
Allow Drupal cron and the internal acquia_dam_media_item_update queue to run, or run the update queue manually, or use Check for update on the specific media item in Drupal.
This limitation only affects some cases where you finalize an older version. Uploading a new version and finalizing it continues to trigger updates as expected.
Why are not my DAM assets updated in Drupal right after cron runs?
Drupal uses cron together with an internal update queue to keep Acquia DAM assets in sync. When cron runs, it detects changes in Acquia DAM (such as new versions, metadata updates, or Pending Delete state) and adds affected assets to the acquia_dam_media_item_update queue.
Updates only appear in Drupal after this queue is processed. If the queue is large, backed up, or not running regularly, assets may not look updated immediately even though cron has run.
What happens when asset metadata is updated in the Acquia DAM system?
The asset metadata in the Drupal application automatically updates after the scheduled cron job runs when metadata changes are made in the Acquia DAM system. Additionally, editors can manually trigger Sync metadata from the DAM media listing within Drupal to immediately reflect the latest asset metadata updates.
How can I ensure Drupal uses the latest finalized versions of assets from Acquia DAM?
After a new version of an asset is uploaded and finalized in Acquia DAM, Drupal picks up that change when the scheduled cron job runs. Editors can also use Check for update on the DAM media listing to refresh individual assets. However, the DAM API does not treat all changes to which version is marked as finalized as content updates. To ensure that all Drupal media items use the latest finalized versions from Acquia DAM, run the following Drush command in the Drupal environment to queue updates based on finalized versions:
After cron and the relevant queues finish processing, Drupal media reflects the latest finalized versions of the corresponding DAM assets.
How can I keep Acquia DAM assets in Drupal in sync on an ongoing basis?
To keep DAM assets synchronized between Acquia DAM and Drupal:
Ensure that Drupal cron runs on a regular schedule for example, daily or weekly. This ensures that the system detects and queues asset updates and Pending Delete changes for processing.
Periodically verify that the acquia_dam_media_item_update queue processes correctly and does not retain a large backlog.
If many assets appear out of sync, for example after a period without cron, run the following command:
drush acquia-dam:update-assets
What does the drush acquia-dam:update-assets command do?
The drush acquia-dam:update-assets command updates existing Drupal media items that use Acquia DAM assets to match the latest information in Acquia DAM. This tool pulls current asset data, such as status and metadata, from Acquia DAM and applies those updates to the corresponding DAM-backed media items in Drupal.
If some assets in Drupal remain out of sync with their state in Acquia DAM, run this command to update those media items in bulk. For example, use this if an asset appears as Published in Drupal after an administrator deletes it or moves it to Pending Delete in the DAM.
drush acquia-dam:update-assets
When should I use drush acquia-dam:update-assets?
Use drush acquia-dam:update-assets to force a bulk synchronization of DAM asset information into Drupal.
Use this command in the following scenarios:
Assets are deleted or moved to Pending Delete in Acquia DAM but appear as Published in the Media Library of Drupal.
Metadata in Drupal is inconsistent or outdated after multiple updates to assets in Acquia DAM.
To recover or clean up after a period without regular cron runs, where many DAM asset updates accumulated.
How does drush acquia-dam:update-assets relate to cron and the DAM media update queue?
Under normal operation:
Drupal detects changes in Acquia DAM, such as expiration, unreleased status, Pending Delete, or metadata changes, when cron runs.
Cron adds the affected assets to the internal acquia_dam_media_item_update queue.
Queue workers process those items and update the corresponding media in Drupal.
If cron does not run regularly, or if the acquia_dam_media_item_update queue remains backed up, assets can appear out of sync. For example, deleted or Pending Delete assets might still appear as Published. In that case:
First, check the queue status:
drush queue:list
Look for acquia_dam_media_item_update.
If there are items pending, process them:
drush queue:run acquia_dam_media_item_update
If you still have a larger set of assets that appear out of sync, you can then use:
drush acquia-dam:update-assets
to force a broader refresh of asset information from Acquia DAM into Drupal.
What happens if assets are expired or unreleased in the Acquia DAM system?
The cron job sets assets to unpublished in the Drupal application to automatically handle these changes.
What happens if assets are deleted in the Acquia DAM system?
When an asset is deleted in Acquia DAM and detected by Drupal, the corresponding media item is unpublished during the next cron run or when Check for update runs for that asset. Drupal relies on cron and the internal asset update queue to apply these changes. If those processes experience delays or do not run regularly, deleted assets can temporarily appear as Published in Drupal until the system processes the updates.
Why do some deleted or Pending Delete DAM assets still appear as published in Drupal?
After an administrator deletes an asset in Acquia DAM and it enters a Pending Delete state, the system does not unpublish it in Drupal immediately. Drupal must first run cron to detect updated or deleted assets from Acquia DAM. The system then processes the internal asset update queue to apply those changes to media items. If cron does not run regularly, or if a backlog exists in the update queue, deleted or pending‑delete assets can temporarily appear as Published in Drupal. After cron runs, and the asset update queue finishes processing, the system unpublishes the corresponding media items.
How can I speed up unpublishing of deleted or Pending Delete DAM assets in Drupal?
The system normally unpublishes deleted or Pending Delete assets from Acquia DAM in Drupal the next time cron runs and the asset update queue processes. To perform these updates sooner, an administrator account can run Drupal cron manually and process any remaining DAM media updates. Examples include running the relevant queues or a full asset update command in the Drupal environment. After those processes complete, the system unpublishes the associated Drupal media items for those assets.
What should I check if deleted or Pending Delete DAM assets are still published in Drupal?
If deleted or Pending Delete assets in Acquia DAM remain published in Drupal, first confirm that Drupal cron runs regularly. Cron detects updated or deleted assets from Acquia DAM and adds them to the internal asset update queue. Next, verify that the DAM media update queue actually processes and does not remain backed up. If items still remain in the queue, process them immediately. Run the following Drush command in the Drupal environment:
drush queue:run acquia_dam_media_item_update
After cron runs and the DAM media update queue is processed, the corresponding Drupal media items for those deleted or pending-delete assets are unpublished automatically.
Why do some assets that were deleted in Acquia DAM still appear as published on the Drupal site?
After an administrator permanently deletes an asset in Acquia DAM, the DAM API no longer returns it. Because Drupal relies on the API to detect changes, the system cannot detect the deletion and therefore does not receive an update to unpublish the corresponding media item. Consequently, the Drupal media item can remain in a Published state despite the permanent deletion of the asset in Acquia DAM. To correct this for a specific item, update the respective asset in Drupal. Select Check for update on the DAM media listing. This action adds the asset to the update queue to ensure that the system processes it during the next cron run.
What happens if assets are deleted in the Drupal application?
It is not advisable to delete assets from a Drupal application. It disrupts the sync process, as the deleted assets cannot be restored. Consequently, you need to reattach the assets to the content manually.
Can I extend the media sources of supported asset types?
Currently, the supported asset types in Acquia DAM include Audio, Documents, Generic, Image, PDF, Spinset, and Video. It is not possible to extend the media sources of these types at this time.
What happens to existing assets when the Download and Sync Assets option is enabled?
All assets are served directly from the local file system.
How can I serve assets through my web application domain?
Enable Download and sync assets.
Which Drupal file system should I use for the Download and sync assets option (public or private)?
When you enable Download and sync assets, Acquia DAM assets are copied to and retrieved from your Drupal file system instead of directly from Acquia DAM. The downloaded assets use the default file system, either public or private, that the site uses for managed files at the time of feature activation.
Use the public file system when synchronized DAM assets need to be publicly accessible on the web without any additional access checks.
Use the private file system when synchronized DAM assets must be protected by Drupal access control and served only to authenticated or authorized users.
Ensure that the default file system choice matches security and access requirements after you enable Download and sync assets.
Can I switch from the public file system to the private file system, or vice versa, after I enable Download and sync assets?
No. Switching between the public and private file systems for already downloaded DAM assets is not supported. After assets synchronize and store on a particular file system, they must remain there. If you change the underlying file system configuration after an administrator enables Download and sync, assets can lead to broken file references, access issues, or inconsistent behavior. To use a different file system setup, plan and configure it before you turn on Download and sync assets.
What should I consider before enabling Download and sync assets with respect to the Drupal file system?
Before an administrator enables Download and sync assets, review the following:
Access requirements: Decide whether synchronized Digital Asset Management (DAM) assets must remain publicly accessible or restricted. Configure the Drupal default file system, either public or private, accordingly.
Long‑term choice: Plan for the fact that you cannot switch between public and private file systems for these assets later.
Serving behavior: The web server typically serves public file system assets directly. Drupal serves private file system assets through access checks, which can affect performance and how media is presented.
To confirm the correct file system configuration, ensure that assets downloaded from Acquia DAM behave as expected after you enable Download and sync assets.
Why are SVG image assets from Acquia DAM broken with Drupal image styles out of the box?
Drupal does not natively apply image styles to SVG files in the same way, it applies them to raster formats such as JPEG or PNG. Consequently, SVG assets synchronized from Acquia DAM might not render correctly or respond to image styles out of the box, even though other image formats do.
How can I make SVG image assets from Acquia DAM work with Drupal image styles?
To enable proper handling of SVG assets with image styles in Drupal, use the contributed SVG Image module. This module adds SVG‑specific support to the image system of Drupal. This ensures that SVG assets can participate in the image style and display alongside other image formats.
An Acquia DAM asset in Drupal appears under the wrong media type or is not rendering properly. What should I do?
If an administrator assigns a DAM-backed media item to the wrong DAM media type, use acquia-dam:resolve-asset-media-type to correct it. For example, this applies if an image or archive asset exists as a generic DAM media item, or if the item does not render correctly due to media type handling.
To resolve these issues:
Verify the media type of the affected media item in Drupal and confirm whether it matches the asset format in Acquia DAM, such as image, video, document, or archive.
If the media type appears incorrect or too generic, run:
drush acquia-dam:resolve-asset-media-type
Limit the command to the relevant DAM media type using the --media-type option if needed.
The command compares media items against asset metadata in Acquia DAM and moves them to appropriate DAM media types. This action often resolves the issue by applying the correct media-type-specific configuration and display behavior.
What does the acquia-dam:resolve-asset-media-type Drush command do?
The acquia-dam:resolve-asset-media-type command scans existing Drupal media items that use Acquia DAM assets. It verifies whether each item has an assignment to the correct DAM media type based on the asset metadata in Acquia DAM. After the command finds a media item on an incorrect media type, the system updates that item to the correct type.
For example:
When an SVG asset resolves as Generic and exists under a generic DAM media type, this command moves it to the correct Image DAM media type.
When a ZIP file exists under a generic DAM media type, this command moves it to the correct Archive DAM media type.
Run the command as:
# Process all DAM media types in batches of 50 (default)
drush acquia-dam:resolve-asset-media-type
# Process in batches of 100 items
drush acquia-dam:resolve-asset-media-type --batch-size=100
# Process only a specific DAM media type
drush acquia-dam:resolve-asset-media-type --media-type=acquia_dam_image_asset
The command processes media items in batches and provides a summary of how many were processed and how many were updated.
When should I run acquia-dam:resolve-asset-media-type?
Run acquia-dam:resolve-asset-media-type if you suspect some Acquia DAM assets in Drupal use the wrong DAM media type. Common scenarios include:
If an administrator enables or updates DAM media types: For example, this applies if SVG or archive assets existed under a generic media type and now have dedicated media types available.
During cleanup or migration work: Use this if you want to standardize existing media to ensure that each asset attaches to the most appropriate DAM media type.
To limit the impact, adjust the batch size, up to 200 per batch, with --batch-size. Alternatively, target a single DAM media type with --media-type if you only need to correct one specific type.
How many methods are available for importing assets from the Acquia DAM system into the Drupal application?
There are two ways to import assets into the Drupal file system from Acquia DAM:
with categories filters
with asset group filters
Can I import assets from all categories with a single click?
No, the administrator must select individual categories in order to import assets from each category.
Can I import assets that do not belong to any category?
No, only assets that belong to a specific category can be imported, unless you are filtering by asset group.
Can I import assets with a sub-category?
Yes, it supports sub-categories up to 10 levels deep in the hierarchy.
Does clicking the save button import all assets immediately?
No, the Save button only saves the configuration to import assets for a specific category or asset group. The cron job processes the configuration and imports the assets in batches.
If new assets are added to the Acquia DAM System, should I resave the configuration to import them?
No, the configuration is saved once, and the cron job automatically picks up the saved configuration. It handles the import of any newly added assets without the need to resave the configuration.
What happens if asset categories or assets groups are removed?
The cron job only imports assets that belong to the saved configurations. Any removed categories or asset groups are not considered for asset import in the scheduled cron job.
Why are some assets in the Drupal file system not visible after the cron job?
The cron job imports assets in batches, so it is possible that not all assets were processed in the current run. The remaining assets are imported during the next scheduled cron job. If you need to import the assets sooner, you can manually trigger the cron job.
I am using the new bulk import, does that mean DAM embed URLs are not used for the migrated content?
Assets are retrieved based on the media type options you selected. If you have not enabled the Download & Sync assets feature, the assets are delivered through the embed option.
Why are some Acquia DAM assets missing when I run a bulk import in Drupal?
The bulk import feature in the Acquia DAM module only imports assets that are currently released and available. Assets that are unreleased or expired in Acquia DAM are excluded from the bulk import and therefore do not appear in Drupal after the import completes. To include an asset in a bulk import, ensure that it is released and not expired in Acquia DAM before you run the import.
How can I check which assets are imported before I run a bulk import from Acquia DAM?
The bulk import feature only brings in assets that are currently released and not expired in Acquia DAM. Before you run a bulk import, review assets directly in Acquia DAM. Use the UI filters for release and expiration status to examine which assets are eligible. The system excludes any assets that are unreleased or expired from the import. These assets do not appear in Drupal until the status in Acquia DAM changes to released and active.
This document provides answers to common questions about the integration and management of assets between Acquia DAM and Drupal.
General
Do users have the same permissions to assets in the module as in DAM?
Yes, users authenticate into DAM first, so their permissions match. Check the user's role permissions if they do not see the correct assets.
Why do I see a 401 Unauthorized Error when I access the Acquia DAM Media Browser in Drupal?
When you access Acquia DAM assets, a 401 Unauthorized Error in the Drupal Media Browser means your current authentication token has expired or is invalid.
To resolve this issue and restore proper access, you must re-authenticate your account with Acquia DAM with the following steps:
Log in to your Drupal application.
Navigate to your user profile, which is usually located at /user.
In your profile menu, click the Acquia DAM tab.
Click Log out to disconnect your Drupal user from Acquia DAM.
After you log out, click Authorize to re-establish a secure connection and obtain a new, valid token.
This process immediately restores your access to DAM assets within the Drupal Media Browser.
Creating and managing DAM media
How do I add a new Acquia DAM asset to Drupal content if I cannot use the /media/add form?
In the new Acquia DAM module, DAM media items are created through the Media Library and not the /media/add form. When you visit /media/add for a DAM media type, the form is disabled and displays a message such as: “Media items cannot be added from this form, only through the media library when editing content.”. To add a DAM asset:
Edit the piece of content where you want to use it.
Open the Media Library from the relevant media field.
Select or search for the desired DAM asset.
This workflow ensures that all DAM media are created and linked with a consistent process, to preserve a clean 1:1 relationship between Acquia DAM assets and Drupal media entities.
Why is Acquia DAM media not supported by Acquia DAM when I paste the /media/add form asset IDs?
In the Acquia DAM module, the ability to fetch and create media items directly by pasting an Asset ID into the /media/add form has been intentionally removed. In earlier implementations, this pattern could inadvertently allow multiple Drupal media items to be mapped to the same DAM asset ID. This led to data inconsistencies, confusion about which version was correct, and problems maintaining a clean 1:1 relationship between assets in Acquia DAM and media entities in Drupal.
To avoid these issues, you are required to select DAM assets through the Media Library when you edit content. After you visit the /media/add form for a DAM media type, the form is disabled and displays a warning such as "Media items cannot be added from this form, only through the media library when editing content." This ensures that all DAM media assets are created and managed through a standardized workflow and that each Drupal media item is reliably linked to a single DAM asset.
Acquia addresses customer feedback about adding DAM assets independently through the /media/add form. All options are evaluated to support this in a way that preserves data integrity and clean 1:1 asset mapping between Acquia DAM and Drupal.
What happens when assets are updated in the Acquia DAM system?
Assets updated in the Acquia DAM system are automatically reflected through the cron job. Additionally, editors have the option to manually run the Check for update action within the Drupal application under the DAM media listing to ensure that the updated assets are quickly reflected in Drupal.
What happens if assets are not updated in the Drupal application after changes are made to the finalized version in the Acquia DAM system?
Even if the cron job runs, the assets are not automatically updated in the Drupal application when the finalized version is changed in the Acquia DAM system. Editors must manually use Check for update within the DAM media listing in Drupal to ensure that the updated assets are promptly reflected in the application.
How do I ensure Drupal updates an asset when I finalize an older version in Acquia DAM?
When you upload a new version of an asset in Acquia DAM and mark it as finalized, Drupal normally detects that change during the next cron run and updates the corresponding media item (or you can force it sooner with Check for update in the DAM media listing).
However, if you revert to an older version of an asset and mark that older version as finalized, the DAM system does not always treat this as a standard asset update event. In those cases, the DAM API may not return any change for Drupal to process, so cron and the DAM media update queue do not update the media item, even though they are running correctly.
To force Drupal to pick up this change, you can:
In Acquia DAM, set the older version as finalized and make a small, non‑critical change to a metadata field such as a temporary description or tag value and the revert the temporary metadata change. This causes the asset to be treated as updated and included in the integration.
Allow Drupal cron and the internal acquia_dam_media_item_update queue to run, or run the update queue manually, or use Check for update on the specific media item in Drupal.
This limitation only affects some cases where you finalize an older version. Uploading a new version and finalizing it continues to trigger updates as expected.
Why are not my DAM assets updated in Drupal right after cron runs?
Drupal uses cron together with an internal update queue to keep Acquia DAM assets in sync. When cron runs, it detects changes in Acquia DAM (such as new versions, metadata updates, or Pending Delete state) and adds affected assets to the acquia_dam_media_item_update queue.
Updates only appear in Drupal after this queue is processed. If the queue is large, backed up, or not running regularly, assets may not look updated immediately even though cron has run.
What happens when asset metadata is updated in the Acquia DAM system?
The asset metadata in the Drupal application automatically updates after the scheduled cron job runs when metadata changes are made in the Acquia DAM system. Additionally, editors can manually trigger Sync metadata from the DAM media listing within Drupal to immediately reflect the latest asset metadata updates.
How can I ensure Drupal uses the latest finalized versions of assets from Acquia DAM?
After a new version of an asset is uploaded and finalized in Acquia DAM, Drupal picks up that change when the scheduled cron job runs. Editors can also use Check for update on the DAM media listing to refresh individual assets. However, the DAM API does not treat all changes to which version is marked as finalized as content updates. To ensure that all Drupal media items use the latest finalized versions from Acquia DAM, run the following Drush command in the Drupal environment to queue updates based on finalized versions:
After cron and the relevant queues finish processing, Drupal media reflects the latest finalized versions of the corresponding DAM assets.
How can I keep Acquia DAM assets in Drupal in sync on an ongoing basis?
To keep DAM assets synchronized between Acquia DAM and Drupal:
Ensure that Drupal cron runs on a regular schedule for example, daily or weekly. This ensures that the system detects and queues asset updates and Pending Delete changes for processing.
Periodically verify that the acquia_dam_media_item_update queue processes correctly and does not retain a large backlog.
If many assets appear out of sync, for example after a period without cron, run the following command:
drush acquia-dam:update-assets
What does the drush acquia-dam:update-assets command do?
The drush acquia-dam:update-assets command updates existing Drupal media items that use Acquia DAM assets to match the latest information in Acquia DAM. This tool pulls current asset data, such as status and metadata, from Acquia DAM and applies those updates to the corresponding DAM-backed media items in Drupal.
If some assets in Drupal remain out of sync with their state in Acquia DAM, run this command to update those media items in bulk. For example, use this if an asset appears as Published in Drupal after an administrator deletes it or moves it to Pending Delete in the DAM.
drush acquia-dam:update-assets
When should I use drush acquia-dam:update-assets?
Use drush acquia-dam:update-assets to force a bulk synchronization of DAM asset information into Drupal.
Use this command in the following scenarios:
Assets are deleted or moved to Pending Delete in Acquia DAM but appear as Published in the Media Library of Drupal.
Metadata in Drupal is inconsistent or outdated after multiple updates to assets in Acquia DAM.
To recover or clean up after a period without regular cron runs, where many DAM asset updates accumulated.
How does drush acquia-dam:update-assets relate to cron and the DAM media update queue?
Under normal operation:
Drupal detects changes in Acquia DAM, such as expiration, unreleased status, Pending Delete, or metadata changes, when cron runs.
Cron adds the affected assets to the internal acquia_dam_media_item_update queue.
Queue workers process those items and update the corresponding media in Drupal.
If cron does not run regularly, or if the acquia_dam_media_item_update queue remains backed up, assets can appear out of sync. For example, deleted or Pending Delete assets might still appear as Published. In that case:
First, check the queue status:
drush queue:list
Look for acquia_dam_media_item_update.
If there are items pending, process them:
drush queue:run acquia_dam_media_item_update
If you still have a larger set of assets that appear out of sync, you can then use:
drush acquia-dam:update-assets
to force a broader refresh of asset information from Acquia DAM into Drupal.
What happens if assets are expired or unreleased in the Acquia DAM system?
The cron job sets assets to unpublished in the Drupal application to automatically handle these changes.
What happens if assets are deleted in the Acquia DAM system?
When an asset is deleted in Acquia DAM and detected by Drupal, the corresponding media item is unpublished during the next cron run or when Check for update runs for that asset. Drupal relies on cron and the internal asset update queue to apply these changes. If those processes experience delays or do not run regularly, deleted assets can temporarily appear as Published in Drupal until the system processes the updates.
Why do some deleted or Pending Delete DAM assets still appear as published in Drupal?
After an administrator deletes an asset in Acquia DAM and it enters a Pending Delete state, the system does not unpublish it in Drupal immediately. Drupal must first run cron to detect updated or deleted assets from Acquia DAM. The system then processes the internal asset update queue to apply those changes to media items. If cron does not run regularly, or if a backlog exists in the update queue, deleted or pending‑delete assets can temporarily appear as Published in Drupal. After cron runs, and the asset update queue finishes processing, the system unpublishes the corresponding media items.
How can I speed up unpublishing of deleted or Pending Delete DAM assets in Drupal?
The system normally unpublishes deleted or Pending Delete assets from Acquia DAM in Drupal the next time cron runs and the asset update queue processes. To perform these updates sooner, an administrator account can run Drupal cron manually and process any remaining DAM media updates. Examples include running the relevant queues or a full asset update command in the Drupal environment. After those processes complete, the system unpublishes the associated Drupal media items for those assets.
What should I check if deleted or Pending Delete DAM assets are still published in Drupal?
If deleted or Pending Delete assets in Acquia DAM remain published in Drupal, first confirm that Drupal cron runs regularly. Cron detects updated or deleted assets from Acquia DAM and adds them to the internal asset update queue. Next, verify that the DAM media update queue actually processes and does not remain backed up. If items still remain in the queue, process them immediately. Run the following Drush command in the Drupal environment:
drush queue:run acquia_dam_media_item_update
After cron runs and the DAM media update queue is processed, the corresponding Drupal media items for those deleted or pending-delete assets are unpublished automatically.
Why do some assets that were deleted in Acquia DAM still appear as published on the Drupal site?
After an administrator permanently deletes an asset in Acquia DAM, the DAM API no longer returns it. Because Drupal relies on the API to detect changes, the system cannot detect the deletion and therefore does not receive an update to unpublish the corresponding media item. Consequently, the Drupal media item can remain in a Published state despite the permanent deletion of the asset in Acquia DAM. To correct this for a specific item, update the respective asset in Drupal. Select Check for update on the DAM media listing. This action adds the asset to the update queue to ensure that the system processes it during the next cron run.
What happens if assets are deleted in the Drupal application?
It is not advisable to delete assets from a Drupal application. It disrupts the sync process, as the deleted assets cannot be restored. Consequently, you need to reattach the assets to the content manually.
Can I extend the media sources of supported asset types?
Currently, the supported asset types in Acquia DAM include Audio, Documents, Generic, Image, PDF, Spinset, and Video. It is not possible to extend the media sources of these types at this time.
What happens to existing assets when the Download and Sync Assets option is enabled?
All assets are served directly from the local file system.
How can I serve assets through my web application domain?
Enable Download and sync assets.
Which Drupal file system should I use for the Download and sync assets option (public or private)?
When you enable Download and sync assets, Acquia DAM assets are copied to and retrieved from your Drupal file system instead of directly from Acquia DAM. The downloaded assets use the default file system, either public or private, that the site uses for managed files at the time of feature activation.
Use the public file system when synchronized DAM assets need to be publicly accessible on the web without any additional access checks.
Use the private file system when synchronized DAM assets must be protected by Drupal access control and served only to authenticated or authorized users.
Ensure that the default file system choice matches security and access requirements after you enable Download and sync assets.
Can I switch from the public file system to the private file system, or vice versa, after I enable Download and sync assets?
No. Switching between the public and private file systems for already downloaded DAM assets is not supported. After assets synchronize and store on a particular file system, they must remain there. If you change the underlying file system configuration after an administrator enables Download and sync, assets can lead to broken file references, access issues, or inconsistent behavior. To use a different file system setup, plan and configure it before you turn on Download and sync assets.
What should I consider before enabling Download and sync assets with respect to the Drupal file system?
Before an administrator enables Download and sync assets, review the following:
Access requirements: Decide whether synchronized Digital Asset Management (DAM) assets must remain publicly accessible or restricted. Configure the Drupal default file system, either public or private, accordingly.
Long‑term choice: Plan for the fact that you cannot switch between public and private file systems for these assets later.
Serving behavior: The web server typically serves public file system assets directly. Drupal serves private file system assets through access checks, which can affect performance and how media is presented.
To confirm the correct file system configuration, ensure that assets downloaded from Acquia DAM behave as expected after you enable Download and sync assets.
Why are SVG image assets from Acquia DAM broken with Drupal image styles out of the box?
Drupal does not natively apply image styles to SVG files in the same way, it applies them to raster formats such as JPEG or PNG. Consequently, SVG assets synchronized from Acquia DAM might not render correctly or respond to image styles out of the box, even though other image formats do.
How can I make SVG image assets from Acquia DAM work with Drupal image styles?
To enable proper handling of SVG assets with image styles in Drupal, use the contributed SVG Image module. This module adds SVG‑specific support to the image system of Drupal. This ensures that SVG assets can participate in the image style and display alongside other image formats.
An Acquia DAM asset in Drupal appears under the wrong media type or is not rendering properly. What should I do?
If an administrator assigns a DAM-backed media item to the wrong DAM media type, use acquia-dam:resolve-asset-media-type to correct it. For example, this applies if an image or archive asset exists as a generic DAM media item, or if the item does not render correctly due to media type handling.
To resolve these issues:
Verify the media type of the affected media item in Drupal and confirm whether it matches the asset format in Acquia DAM, such as image, video, document, or archive.
If the media type appears incorrect or too generic, run:
drush acquia-dam:resolve-asset-media-type
Limit the command to the relevant DAM media type using the --media-type option if needed.
The command compares media items against asset metadata in Acquia DAM and moves them to appropriate DAM media types. This action often resolves the issue by applying the correct media-type-specific configuration and display behavior.
What does the acquia-dam:resolve-asset-media-type Drush command do?
The acquia-dam:resolve-asset-media-type command scans existing Drupal media items that use Acquia DAM assets. It verifies whether each item has an assignment to the correct DAM media type based on the asset metadata in Acquia DAM. After the command finds a media item on an incorrect media type, the system updates that item to the correct type.
For example:
When an SVG asset resolves as Generic and exists under a generic DAM media type, this command moves it to the correct Image DAM media type.
When a ZIP file exists under a generic DAM media type, this command moves it to the correct Archive DAM media type.
Run the command as:
# Process all DAM media types in batches of 50 (default)
drush acquia-dam:resolve-asset-media-type
# Process in batches of 100 items
drush acquia-dam:resolve-asset-media-type --batch-size=100
# Process only a specific DAM media type
drush acquia-dam:resolve-asset-media-type --media-type=acquia_dam_image_asset
The command processes media items in batches and provides a summary of how many were processed and how many were updated.
When should I run acquia-dam:resolve-asset-media-type?
Run acquia-dam:resolve-asset-media-type if you suspect some Acquia DAM assets in Drupal use the wrong DAM media type. Common scenarios include:
If an administrator enables or updates DAM media types: For example, this applies if SVG or archive assets existed under a generic media type and now have dedicated media types available.
During cleanup or migration work: Use this if you want to standardize existing media to ensure that each asset attaches to the most appropriate DAM media type.
To limit the impact, adjust the batch size, up to 200 per batch, with --batch-size. Alternatively, target a single DAM media type with --media-type if you only need to correct one specific type.
How many methods are available for importing assets from the Acquia DAM system into the Drupal application?
There are two ways to import assets into the Drupal file system from Acquia DAM:
with categories filters
with asset group filters
Can I import assets from all categories with a single click?
No, the administrator must select individual categories in order to import assets from each category.
Can I import assets that do not belong to any category?
No, only assets that belong to a specific category can be imported, unless you are filtering by asset group.
Can I import assets with a sub-category?
Yes, it supports sub-categories up to 10 levels deep in the hierarchy.
Does clicking the save button import all assets immediately?
No, the Save button only saves the configuration to import assets for a specific category or asset group. The cron job processes the configuration and imports the assets in batches.
If new assets are added to the Acquia DAM System, should I resave the configuration to import them?
No, the configuration is saved once, and the cron job automatically picks up the saved configuration. It handles the import of any newly added assets without the need to resave the configuration.
What happens if asset categories or assets groups are removed?
The cron job only imports assets that belong to the saved configurations. Any removed categories or asset groups are not considered for asset import in the scheduled cron job.
Why are some assets in the Drupal file system not visible after the cron job?
The cron job imports assets in batches, so it is possible that not all assets were processed in the current run. The remaining assets are imported during the next scheduled cron job. If you need to import the assets sooner, you can manually trigger the cron job.
I am using the new bulk import, does that mean DAM embed URLs are not used for the migrated content?
Assets are retrieved based on the media type options you selected. If you have not enabled the Download & Sync assets feature, the assets are delivered through the embed option.
Why are some Acquia DAM assets missing when I run a bulk import in Drupal?
The bulk import feature in the Acquia DAM module only imports assets that are currently released and available. Assets that are unreleased or expired in Acquia DAM are excluded from the bulk import and therefore do not appear in Drupal after the import completes. To include an asset in a bulk import, ensure that it is released and not expired in Acquia DAM before you run the import.
How can I check which assets are imported before I run a bulk import from Acquia DAM?
The bulk import feature only brings in assets that are currently released and not expired in Acquia DAM. Before you run a bulk import, review assets directly in Acquia DAM. Use the UI filters for release and expiration status to examine which assets are eligible. The system excludes any assets that are unreleased or expired from the import. These assets do not appear in Drupal until the status in Acquia DAM changes to released and active.
Acquia DAM (Widen)