---
title: "How does asset sync work in Acquia DAM?"
date: "2026-03-24T08:16:59+00:00"
summary: "Discover how Acquia DAM streamlines asset syncing for efficient digital content management across your organization."
image:
type: "page"
url: "/acquia-dam/how-does-asset-sync-work-acquia-dam"
id: "37ff8404-5902-4e52-a4bf-a8ceeab3eda7"
---

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:

1.  **Cron-based checking**: Automatically runs during scheduled cron jobs.
2.  **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:

1.  In the administrative menu, select **Configuration**.
2.  Select **Cron** under **System**.
3.  Verify the last cron run time.
4.  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:

1.  **Fetch from DAM API:** Query DAM for assets modified since the last sync (tracked through Drupal state).
2.  Categorize assets:
    1.  **Unpublish group:** Assets that are deleted, expired, or unreleased are unpublished immediately.
    2.  **Update group:** Assets that are released and need metadata or file sync are queued for processing.
3.  **Process updates:** Queue worker updates metadata, downloads files (if active), and publishes media.
4.  **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:

1.  Execute default sync (steps 1–3 above).
2.  **Track processed media:** Remember which media items were handled.
3.  **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.
4.  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:

1.  In the administrative menu, select **Content**.
2.  Select **Media** to view all media items.
3.  Select the **Check for Update**.
    
    ![Acquia-DAM_check-for-updates](https://acquia.widen.net/content/submmldyrs/web/a1f63_Acquia-DAM-asset-sync-check-for-update.png?w=720&v=4f984ca9-e1b3-4185-b088-6e08d739f091&itok=dSpD1O1U)
    
    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.

#### Queue assets for update

Check assets and queue those that need updates:

    drush acquia-dam:queue-update-assets [--since=<timestamp>] [--batch-size=<number>] [--media-type=<type>] [--finalized-version]

**Options:**

*   **\--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.

#### Process the update queue

Process queued updates immediately:

    drush acquia-dam:process-update-queue [--limit=<number>]

**Options:**

*   **\--limit**: Maximum queue items to process. Default: 0 (no limit).

**Examples:**

    drush acquia-dam:process-update-queue
    drush acquia-dam:process-update-queue --limit=100

#### Combined workflow

For immediate synchronization, use both commands:

    # Quick sync(only reported changes)
    drush acquia-dam:queue-update-assets
    drush acquia-dam:process-update-queue
    
    # Comprehensive sync (include finalized version check)
    drush acquia-dam:queue-update-assets –finalized-version
    drush acquia-dam:process-update-queue

Or use the combined command:

    # Quick sync
    drush acquia-dam:update-assets
    
    # Comprehensive sync
    drush acquia-dam:update-assets --since=0 --finalized-version --batch-size=100

### Troubleshoot sync issues

If specific assets are not syncing:

1.  Processes recent DAM changes.
    
        drush acquia-dam:queue-update-assets
    
2.  Process the queue: 
    
        drush acquia-dam:process-update-queue
    
3.  If still not synced then execute comprehensive check.
    
        drush acquia-dam:queue-update-assets --finalized-version
    
4.  Process the queue: 
    
        drush acquia-dam:process-update-queue
    

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:

1.  The module detects the unavailability during sync.
2.  The Drupal media entity is automatically unpublished.
3.  A log entry is created noting the action.
4.  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.