The Acquia DAM module automatically synchronizes assets between Acquia DAM and your Drupal website. When assets are updated, renamed, or deleted in Acquia DAM, the module detects these changes and updates your Drupal media entities accordingly.
How asset synchronization works
Asset synchronization keeps your Drupal media entities synchronized with their source assets in Acquia DAM through automatic version tracking and update detection.
Version tracking
Each media entity stores three key pieces of information:
Asset ID: Unique identifier for the asset in DAM.
Version ID: Specific version number of the asset in DAM.
External ID: Unique short identifier for the asset in DAM.
After an asset updates in Acquia DAM, the version ID changes. The module detects this change and updates the media entity to reference the new version.
Update detection
The module checks for updates through several mechanisms:
Cron-based checking: Automatically runs during scheduled cron jobs.
Manual checking: Triggered through the user interface button or Drush commands.
What synchronizes
When syncing occurs, the module updates:
Asset metadata such as title, description, and custom fields
Version references
File references when download and sync is active
Thumbnail images
Expiration and release dates
Asset availability status
Automatic synchronization through cron
The most common way assets stay synchronized is through automatic cron-based checking.
How cron syncing works
During each cron run, the module:
Gets a list of updated assets in Acquia DAM after the last cron run date and time in Drupal site.
Checks each asset from the list for version changes in Drupal.
Queues media entities that need updates.
Processes the queue to apply updates.
Verify cron status
Cron synchronization is active by default and requires no configuration.
To verify cron:
In the administrative menu, select Configuration.
Select Cron under System.
Verify the last cron run time.
Click Run cron to trigger an immediate check.
Cron frequency
The frequency of asset synchronization depends on your cron schedule:
Manual cron: Run when you trigger it manually.
Automated cron: Run at configured intervals such as every hour.
External cron: Run through external scheduler such as crontab.
How Drupal queue processing works
Drupal uses a queue system to handle resource-intensive tasks like the update of DAM assets. During a cron run, the module checks for DAM asset updates and adds them to a queue.
Cron triggers queue: Cron checks for updates and queues them.
Queue process: The queue is processed in batches. If the queue is large or processing is slow, updates may not appear immediately.
Manual process: You can process the queue manually with Drush:
drush queue:run acquia_dam_media_item_update
Troubleshoot: If assets do not update after cron, check the queue length, process the queue manually, and review Drupal log messages for errors.
Note
More frequent cron runs mean faster detection of asset changes but also increase server load and API usage. Balance your cron frequency based on how quickly you need updates and your server resources.
Manual synchronization methods
You can trigger asset synchronization manually when you need immediate updates or want to check specific assets.
Through the user interface
Check for updates on the media list page:
In the administrative menu, select Content.
Select Media to view all media items.
Select the Check for Update.
The system queues the media items if it detects a version change. It updates process immediately or during the next cron run.
Through Drush commands
The module provides Drush commands for more control over synchronization.
--batch-size: Number of media items to process per batch where the default is 50.
--media-type: Specific media type to check.
--finalized-version: Force a comparison against the current finalized version in Acquia DAM. Use this to ensure that Drupal follows the finalized version for all affected assets.
# Step 1: Queue assets for checking
drush acquia-dam:queue-update-assets
# Step 2: Process the queue immediately
drush acquia-dam:process-update-queue
Or use the combined command:
drush acquia-dam:update-assets
Asset version resolution
The module includes intelligent version resolution to handle different asset states in Acquia DAM.
Finalized versions
Acquia DAM assets can have multiple versions:
Draft versions: Work in progress, not finalized, unreleased, expired
Finalized versions: Approved for publication
By default, the module targets the latest finalized version of an asset, not draft versions. In most cases, when a new version is uploaded and finalized in Acquia DAM, the module detects the new version ID during cron-based syncing. It then updates the corresponding media entity in Drupal.
However, in some scenarios, simply setting the existing version as finalized in Acquia DAM, such as promoting an older version back to finalized, is not recognized as a typical content update by the DAM API. In those cases, a normal sync may not immediately pick up the change. To handle this, you can use the --finalized-version option with the update queue command to force Drupal to compare what it is using against the asset’s current finalized version in Acquia DAM and update any mismatched media items.
Version update behavior
When an asset version changes:
The module detects the new version ID.
The media entity is queued for updates.
During processing, metadata is refreshed.
If download and sync is enabled, the new file is downloaded.
The version ID is updated to match the new version.
Asset availability monitor
The module monitors asset availability and automatically updates media entities when assets are deleted or unpublished in Acquia DAM.
Availability check
During synchronization, the module checks:
Asset exists: Is the asset still in Acquia DAM?
Asset released: Has the release date passed?
Asset not expired: Has the expiration date not been reached?
Automatic unpublish
When an asset becomes unavailable in Acquia DAM:
The module detects the unavailability during sync.
The Drupal media entity is automatically unpublished.
A log entry is created noting the action.
The asset ID and version remain stored for future reference.
This prevents broken links and missing assets on your website.
Note
Assets permanently deleted in Acquia DAM do not return through the DAM API. Because Drupal relies on the API to detect changes, it cannot see a permanent deletion. As a result, the corresponding Drupal media item remains in a Published state.
Re-publish
If an asset becomes available again in Acquia DAM:
The module detects availability during the next sync.
The media entity is published.
Metadata and files are updated to current versions.
Download and sync behavior
When download and sync is enabled for a media type, syncing includes file operations.
File synchronization
For media types configured with download and sync:
Version changes trigger a file re-download.
The new file replaces the old file.
File references are updated.
How does asset sync work in Acquia DAM?
The Acquia DAM module automatically synchronizes assets between Acquia DAM and your Drupal website. When assets are updated, renamed, or deleted in Acquia DAM, the module detects these changes and updates your Drupal media entities accordingly.
How asset synchronization works
Asset synchronization keeps your Drupal media entities synchronized with their source assets in Acquia DAM through automatic version tracking and update detection.
Version tracking
Each media entity stores three key pieces of information:
Asset ID: Unique identifier for the asset in DAM.
Version ID: Specific version number of the asset in DAM.
External ID: Unique short identifier for the asset in DAM.
After an asset updates in Acquia DAM, the version ID changes. The module detects this change and updates the media entity to reference the new version.
Update detection
The module checks for updates through several mechanisms:
Cron-based checking: Automatically runs during scheduled cron jobs.
Manual checking: Triggered through the user interface button or Drush commands.
What synchronizes
When syncing occurs, the module updates:
Asset metadata such as title, description, and custom fields
Version references
File references when download and sync is active
Thumbnail images
Expiration and release dates
Asset availability status
Automatic synchronization through cron
The most common way assets stay synchronized is through automatic cron-based checking.
How cron syncing works
During each cron run, the module:
Gets a list of updated assets in Acquia DAM after the last cron run date and time in Drupal site.
Checks each asset from the list for version changes in Drupal.
Queues media entities that need updates.
Processes the queue to apply updates.
Verify cron status
Cron synchronization is active by default and requires no configuration.
To verify cron:
In the administrative menu, select Configuration.
Select Cron under System.
Verify the last cron run time.
Click Run cron to trigger an immediate check.
Cron frequency
The frequency of asset synchronization depends on your cron schedule:
Manual cron: Run when you trigger it manually.
Automated cron: Run at configured intervals such as every hour.
External cron: Run through external scheduler such as crontab.
How Drupal queue processing works
Drupal uses a queue system to handle resource-intensive tasks like the update of DAM assets. During a cron run, the module checks for DAM asset updates and adds them to a queue.
Cron triggers queue: Cron checks for updates and queues them.
Queue process: The queue is processed in batches. If the queue is large or processing is slow, updates may not appear immediately.
Manual process: You can process the queue manually with Drush:
drush queue:run acquia_dam_media_item_update
Troubleshoot: If assets do not update after cron, check the queue length, process the queue manually, and review Drupal log messages for errors.
Note
More frequent cron runs mean faster detection of asset changes but also increase server load and API usage. Balance your cron frequency based on how quickly you need updates and your server resources.
Manual synchronization methods
You can trigger asset synchronization manually when you need immediate updates or want to check specific assets.
Through the user interface
Check for updates on the media list page:
In the administrative menu, select Content.
Select Media to view all media items.
Select the Check for Update.
The system queues the media items if it detects a version change. It updates process immediately or during the next cron run.
Through Drush commands
The module provides Drush commands for more control over synchronization.
--batch-size: Number of media items to process per batch where the default is 50.
--media-type: Specific media type to check.
--finalized-version: Force a comparison against the current finalized version in Acquia DAM. Use this to ensure that Drupal follows the finalized version for all affected assets.
# Step 1: Queue assets for checking
drush acquia-dam:queue-update-assets
# Step 2: Process the queue immediately
drush acquia-dam:process-update-queue
Or use the combined command:
drush acquia-dam:update-assets
Asset version resolution
The module includes intelligent version resolution to handle different asset states in Acquia DAM.
Finalized versions
Acquia DAM assets can have multiple versions:
Draft versions: Work in progress, not finalized, unreleased, expired
Finalized versions: Approved for publication
By default, the module targets the latest finalized version of an asset, not draft versions. In most cases, when a new version is uploaded and finalized in Acquia DAM, the module detects the new version ID during cron-based syncing. It then updates the corresponding media entity in Drupal.
However, in some scenarios, simply setting the existing version as finalized in Acquia DAM, such as promoting an older version back to finalized, is not recognized as a typical content update by the DAM API. In those cases, a normal sync may not immediately pick up the change. To handle this, you can use the --finalized-version option with the update queue command to force Drupal to compare what it is using against the asset’s current finalized version in Acquia DAM and update any mismatched media items.
Version update behavior
When an asset version changes:
The module detects the new version ID.
The media entity is queued for updates.
During processing, metadata is refreshed.
If download and sync is enabled, the new file is downloaded.
The version ID is updated to match the new version.
Asset availability monitor
The module monitors asset availability and automatically updates media entities when assets are deleted or unpublished in Acquia DAM.
Availability check
During synchronization, the module checks:
Asset exists: Is the asset still in Acquia DAM?
Asset released: Has the release date passed?
Asset not expired: Has the expiration date not been reached?
Automatic unpublish
When an asset becomes unavailable in Acquia DAM:
The module detects the unavailability during sync.
The Drupal media entity is automatically unpublished.
A log entry is created noting the action.
The asset ID and version remain stored for future reference.
This prevents broken links and missing assets on your website.
Note
Assets permanently deleted in Acquia DAM do not return through the DAM API. Because Drupal relies on the API to detect changes, it cannot see a permanent deletion. As a result, the corresponding Drupal media item remains in a Published state.
Re-publish
If an asset becomes available again in Acquia DAM:
The module detects availability during the next sync.
The media entity is published.
Metadata and files are updated to current versions.
Download and sync behavior
When download and sync is enabled for a media type, syncing includes file operations.
File synchronization
For media types configured with download and sync:
Version changes trigger a file re-download.
The new file replaces the old file.
File references are updated.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Acquia DAM