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.
How the sync process works
Understanding the sync workflow helps you choose the right options.
Default sync behavior (cron and basic Drush)
When cron runs or you execute drush acquia-dam:queue-update-assets without options:
Fetch from DAM API: Query DAM for assets modified since the last sync (tracked through Drupal state).
Categorize assets:
Unpublish group: Assets that are deleted, expired, or unreleased are unpublished immediately.
Update group: Assets that are released and need metadata or file sync are queued for processing.
Process updates: Queue worker updates metadata, downloads files (if active), and publishes media.
Update timestamp: Store current time for next incremental sync.
Efficiency: Only processes assets DAM reports as changed — fast and lightweight.
With --finalized-version option
When you add the --finalized-version flag:
Execute default sync (steps 1–3 above).
Track processed media: Remember which media items were handled.
Check remaining media: For all media not in DAM's change list, query DAM for current finalized version, compare with Drupal's stored version, and queue if mismatch detected.
Process all queued updates.
Use case: Catches edge cases where finalized version changes without updating lastEditDate.
Trade-off: More thorough but slower as it checks every media item individually.
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 queues the asset and process during the next cron run.
Through Drush commands
The module provides Drush commands for more control over synchronization.
--since: Unix timestamp. Only process assets modified since this time. Default: 0 (processes all assets from DAM). Use this for incremental updates.
--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.
Examples:
# Queue all assets (default behavior)
drush acquia-dam:queue-update-assets
# Queue only recently changed assets (incremental)
drush acquia-dam:queue-update-assets --since=1234567890
# Queue with batches
drush acquia-dam:queue-update-assets --batch-size=100
# Queue specific media type
drush acquia-dam:queue-update-assets --media-type=acquia_dam_image_asset
# Queue all + check finalized versions for media not in DAM's change list
drush acquia-dam:queue-update-assets --finalized-version
# Combine timestamp filter with finalized version check
drush acquia-dam:queue-update-assets --since=1234567890 --finalized-version
# Process specific media type with larger batches
drush acquia-dam:queue-update-assets --batch-size=100 --media-type=acquia_dam_image_asset
When should I use the --finalized-version?
Use the --finalized-version option when you want to:
Ensure that Drupal updates its media entities to follow a version recently marked as finalized in Acquia DAM.
Force the module to compare the version ID in Drupal against the current finalized version in Acquia DAM and queue any mismatches for update.
Perform a comprehensive check of all media items in your system, not just those DAM reports as recently changed. This is particularly useful after:
Promoting an older version to finalized in DAM.
Bulk operations in DAM that may not trigger lastEditDate updates.
Initial site setup or after long periods without sync.
Troubleshooting sync discrepancies.
Note
This option is more thorough but slower, as it checks every media item in Drupal against DAM's current finalized version. For regular maintenance, the default behavior (processing only reported changes) is usually sufficient.
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.
How the sync process works
Understanding the sync workflow helps you choose the right options.
Default sync behavior (cron and basic Drush)
When cron runs or you execute drush acquia-dam:queue-update-assets without options:
Fetch from DAM API: Query DAM for assets modified since the last sync (tracked through Drupal state).
Categorize assets:
Unpublish group: Assets that are deleted, expired, or unreleased are unpublished immediately.
Update group: Assets that are released and need metadata or file sync are queued for processing.
Process updates: Queue worker updates metadata, downloads files (if active), and publishes media.
Update timestamp: Store current time for next incremental sync.
Efficiency: Only processes assets DAM reports as changed — fast and lightweight.
With --finalized-version option
When you add the --finalized-version flag:
Execute default sync (steps 1–3 above).
Track processed media: Remember which media items were handled.
Check remaining media: For all media not in DAM's change list, query DAM for current finalized version, compare with Drupal's stored version, and queue if mismatch detected.
Process all queued updates.
Use case: Catches edge cases where finalized version changes without updating lastEditDate.
Trade-off: More thorough but slower as it checks every media item individually.
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 queues the asset and process during the next cron run.
Through Drush commands
The module provides Drush commands for more control over synchronization.
--since: Unix timestamp. Only process assets modified since this time. Default: 0 (processes all assets from DAM). Use this for incremental updates.
--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.
Examples:
# Queue all assets (default behavior)
drush acquia-dam:queue-update-assets
# Queue only recently changed assets (incremental)
drush acquia-dam:queue-update-assets --since=1234567890
# Queue with batches
drush acquia-dam:queue-update-assets --batch-size=100
# Queue specific media type
drush acquia-dam:queue-update-assets --media-type=acquia_dam_image_asset
# Queue all + check finalized versions for media not in DAM's change list
drush acquia-dam:queue-update-assets --finalized-version
# Combine timestamp filter with finalized version check
drush acquia-dam:queue-update-assets --since=1234567890 --finalized-version
# Process specific media type with larger batches
drush acquia-dam:queue-update-assets --batch-size=100 --media-type=acquia_dam_image_asset
When should I use the --finalized-version?
Use the --finalized-version option when you want to:
Ensure that Drupal updates its media entities to follow a version recently marked as finalized in Acquia DAM.
Force the module to compare the version ID in Drupal against the current finalized version in Acquia DAM and queue any mismatches for update.
Perform a comprehensive check of all media items in your system, not just those DAM reports as recently changed. This is particularly useful after:
Promoting an older version to finalized in DAM.
Bulk operations in DAM that may not trigger lastEditDate updates.
Initial site setup or after long periods without sync.
Troubleshooting sync discrepancies.
Note
This option is more thorough but slower, as it checks every media item in Drupal against DAM's current finalized version. For regular maintenance, the default behavior (processing only reported changes) is usually sufficient.
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 (Widen)