Resources

Integration: Drupal 8.4 and later

This page describes the Acquia DAM connector for Drupal versions 8.4 and later.

The Media: Acquia DAM (media_acquiadam) Drupal module provides unidirectional syncing of media from Acquia DAM Classic to your Drupal 8 or Drupal 9 website.

Installing the connector module

Before you can use Acquia DAM Classic, you must connect your website to Acquia by installing the Media: Acquia DAM module. This connector module allows your website to exchange information with Acquia DAM Classic.

For information about installing and enabling Drupal modules on your website, see Installing a module compatible with the current Drupal version.

If you are upgrading from an older version of the connector module, you must upgrade your database by running the following command:

drush updatedb

Notes

Connecting to Acquia DAM Classic

To connect to Acquia DAM Classic:

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Configuration.

  3. Scroll to the Media section and click Acquia DAM.

  4. In the Authentication details section, enter your Username, Password, Client ID, and Client secret.

    Notes

    • If you do not have your Client ID or Client secret, contact your account manager.

    • The Username value is a user’s account name for Acquia DAM Classic, and isn’t a user’s email address.

    • The user’s account for Acquia DAM Classic must have the Acquia DAM Classic admin role. Ensure that you do not use the Acquia DAM Classic user account for adding or editing content in Acquia DAM Classic.

  5. To use the regular sync method, follow the steps in Using the regular sync method. Alternatively, use the notification-based sync method.

  6. Click Save configuration.

Best practices

  • The DAM sync user must be for DAM to Drupal sync. Do not log into DAM with the same user account for adding or editing content in DAM.

  • Name the DAM sync user for easy identification. For example, Drupal Sync User. This enables DAM administrators to know the use case for such a user and stop them from inadvertently deleting the user or changing the user role.

  • If you change the password for the DAM sync user, you must update the module settings to use the new password. If you do not do so, sync stops working.

Using the regular sync method

The regular sync method:

  1. Creates a sync queue of all DAM-synced media entities.

  2. Checks and updates such entities in batches, when cron runs.

When the end of the queue is reached, all DAM-synced media entities are requeued and the process continues.

The regular sync method is the default sync process and is used unless the Enable notifications-based synchronization option is selected in the module configuration form.

Note

You can configure cron as required to ensure that the sync process works as expected. For more information on scheduled jobs, see the Scheduled jobs section.

To use the regular Drupal sync method:

  1. Perform the steps mentioned in Connecting to Acquia DAM Classic.

  2. In the Cron settings section, select how frequently your cron job will sync your metadata and assets between your Drupal instance and your Acquia DAM Classic account. The default value is Every hour.

    If you have multiple assets, frequent synchronization can ensure timely update of assets. To update the cron interval:

    1. Set the Cron settings to Every cron run.

    2. Create a Drupal scheduled job to run media_acquiadam_asset_refresh more often than Drupal cron is set to run. For example, every five minutes or every two minutes.

      To run the queue more frequently, add the following Drush command to the cron job:

      drush queue-run media_acquiadam_asset_refresh

      Important

      You might hit an API request limit, resulting in assets not syncing as expected due to one of the following:

      • Drupal cron runs at the same time as your scheduled job.

      • Drupal cron or scheduled job runs at the same time in multiple sites or environments. Thus, media_acquiadam_asset_refresh runs multiple times concurrently, .

If you encounter an invalid_grant error, ensure that you specify the correct Username, Password, Client ID, and Client secret.

Using notifications-based sync

Notifications-based sync is an alternative method that adds an item to the sync queue only when a change is made to the asset in DAM. This reduces the size of the queue, and therefore makes the sync process more efficient.

Note

  • You can configure cron as required to ensure that the sync process works as expected. For more information on scheduled jobs, see the Scheduled jobs section.

  • Do not use notifications-based sync if you must map DAM active state to Drupal published state.

  1. Log in to your Acquia DAM Classic instance as the sync user.

  2. Click the bell icon at the bottom right.

  3. Click View all.

    The system displays the Notifications window.

  4. Click Change settings.

    The system displays the Notifications Settings pop-up window.

  5. Select the Watch all assets checkbox.

  6. Save the changes.

  7. Sign in to your Drupal website and navigate to /config/media/acquiadam.

  8. Select the Enable notification-based synchronization checkbox.

Important

  • Use the Synchronize all media assets function only when required.

  • To delete assets in DAM, set the asset to inactive in DAM and wait for sync to occur. Delete the asset from DAM only when the media entity is unpublished in Drupal.

Scheduled jobs

Out of the box, the tasks to queue items and sync the next batch of items run when Drupal cron runs. You can set the asset refresh interval in the module settings form to run Every time cron runs or at another interval.

This might be adequate for a site with a limited number of assets to sync, or a site where Drupal cron runs very frequently. However, for sites with a lot of assets to sync or a site that needs to sync assets more often, you can tune the sync process through a combination of:

  • Running Drupal cron at a regular interval that makes sense for your application.

  • Creating scheduled jobs to run asset sync at regular intervals, outside of Drupal cron.

Example:

  • Site uses the regular sync method.

  • Drupal cron is set to run hourly.

  • A scheduled job runs media_acquiadam asset refresh every five minutes, except at the top of the hour.

As a result of these steps, a batch of assets is checked or synced every five minutes. Hence, the changes in DAM reflect in Drupal faster.

Preparing to use Acquia DAM Classic with your website

After you have connected your website to Acquia DAM Classic, you must configure a new media type, an Entity Browser, and add a reference field to your preferred content type.

Acquia recommends configuring private file storage for your website, since Acquia DAM Classic asset files download locally when added to a piece of content.

The Media: Acquia DAM - Example Configuration module provides a couple of pre-configured Media Types to help kickstart the configuration process if necessary.

Configuring a Media Type

To use Acquia DAM Classic assets in content, add a Media Type entry:

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Structure.

  3. Click Media types and click Add media type.

  4. Enter a name, such as “Acquia DAM Classic media asset.”

  5. In the Media source menu, select Acquia DAM asset.

  6. Scroll to the bottom of the page and click Save.

  7. In the Media Types list, find the media type you saved, select Manage fields from the Operations menu.

  8. Click Add field.

  9. In Add a new field, select Reference > File from the menu.

  10. Enter a label for the field, such as Asset.

  11. Click Save and continue.

  12. Click Save field settings.

  13. Scroll to Allowed file extensions and enter the desired file extensions separated by spaces, such as jpg gif png svg pdf doc docx ppt pptx xls xlsx mp4 mpg mpeg webm.

  14. Click Save settings.

  15. Click the Edit tab.

  16. Scroll to the Field Mappings section, and for the File menu, select the field you created.

  17. Click Save.

Note

The Acquia DAM connector module replaces files on sync. Therefore, you must set File directory to a directory exclusive for DAM assets.

Configuring an Entity browser

To access your Acquia DAM Classic assets from the WYSIWYG editor, configure an Entity browser for your Acquia DAM Classic assets using the Acquia DAM Classic widget plugin:

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Configuration.

  3. Scroll to the Content Authoring section and click Entity Browsers.

  4. Click Add Entity Browser.

  5. Enter a label, such as Acquia Dam Classic Entity Browser.

  6. Set Display plugin to Modal. (This is the default.)

  7. Clear any value in both Width of the modal and Height of the modal fields to enable responsive width and height respectively.

  8. Click Next.

  9. Click Next until the Widgets screen appears.

  10. Select Acquia DAM in the Add widget plugin menu.

  11. Click Finish.

To configure the number of items per page in the Entity Browser, navigate to Configuration > Media > Acquia DAM (URL path: /admin/config/media/acquiadam).

Using the Entity Browser module

Use the Entity Browser module to remotely browse DAM through Drupal, provided the module is installed and configured.

  1. Select the Entity Browser module.

    The Entity Browser module automatically creates assets locally, but requires additional configuration including the Entity Browser widget.

  2. On forms, configure the entity reference fields to use the newly configured Entity Browser.

  3. Authenticate to DAM through the media to access DAM Assets.

After the configuration, Entity Browser displays all DAM assets that the current user can access and utilize. The following screen displays the folders containing DAM assets:

Once added through a piece of content, DAM assets appear on the Media content admin page like any other Media asset in Drupal.

Adding a content type field

To add a content type field for your chosen content type:

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Structure.

  3. Click Content types.

  4. From your content type row, select Manage fields from the Operations menu.

  5. Click Add field.

  6. In Add a new field, select Reference > Media from the menu.

  7. Enter a label, such as Acquia DAM Classic asset.

  8. Click Save and continue.

  9. Click Save field settings.

  10. Scroll to the Reference type section, select Acquia DAM Asset at the bottom of the page.

  11. Click Save settings.

Note

To access your Acquia DAM Classic assets from the WYSIWYG editor, configure an Entity browser for your Acquia DAM Classic assets.

Updating the form display

To update the form display to include the field you added for your chosen content type:

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Structure.

  3. Click Content > Content types.

  4. From your content type row, select Manage form display from the Operations menu.

  5. Find the DAM asset field you created earlier.

  6. In the Widget column, select Entity browser and click Settings.

  7. In the Entity type menu, select Acquia DAM Entity browser.

  8. Click Update.

  9. Scroll to the bottom of the page and click Save. The “Your settings have been saved.” notification appears at the top of the screen.

Updating display

To update the content type display to include the field you added for your chosen content type:

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Structure.

  3. Click Content Content types.

  4. From your content type row, select Manage display from the Operations menu.

  5. Find the DAM asset field you created earlier.

  6. In the Format column, select Rendered Entity from the menu.

  7. Scroll to the bottom of the page and click Save.

Configuring Embed for the WYSIWYG editor

Notes

The Entity Embed module is required for the next steps.

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. Configure an Entity browser with Display plugin set to iFrame.

  3. Navigate to Configuration > Content Authoring > Text Editor Embed Buttons (URL path: /admin/config/content/embed).

  4. Select Add embed button.

  5. Enter a value for the Label, such as Acquia DAM Classic.

  6. In Embed type, select Entity.

  7. In Entity type, select Media.

  8. In Entity Browser, select the one you created on step 2.

  9. (Optional) Specify a custom Button icon.

  10. Click Save.

Configuring Entity Embed for the WYSIWYG editor

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. Navigate to Configuration > Content authoring > Text formats and editors (URL path: /admin/config/content/formats).

  3. In Basic HTML, select Configure.

  4. In Toolbar Configuration, drag and drop the button configured for the Acquia DAM button to the Active Toolbar.

  5. In Enabled filters, select the Display embedded entities checkbox.

  6. In Filter settings, ensure the following text is displayed in Allowed HTML tags:

    <drupal-entity data-entity-type data-entity-uuid data-entity-embed-display data-entity-embed-display-settings data-align data-caption data-embed-button>

    By default, it displays as the last line.

  7. Click Save configuration.

After completing these steps, Drupal content authors can click the button in the WYSIWYG editor to access the Acquia DAM Classic entity browser.

Adding assets to Drupal

You can add assets to Drupal from Acquia DAM Classic using Drupal entities or the WYSIWYG editor.

Adding assets using Drupal entities

To add assets using Drupal entities:

  1. Sign in to your Drupal website as a user with content creation permissions.

  2. Navigate to Content > Add new content.

  3. Select a content type to add.

  4. To select an asset, click Select entities.

    The entity browser is displayed.

  5. Click a folder to view the assets inside it.

  6. Click an asset, and click Select assets.

This imports the assets into Drupal.

Adding an asset using the WYSIWYG editor

To add an asset using the WYSIWYG editor:

  1. Sign in to your Drupal website as a user with content creation permissions.

  2. Navigate to Content > Add new content.

  3. Select a content type to add.

  4. Click the WYSIWYG button.

    The entity browser is displayed.

  5. Click a folder to view the assets inside it.

  6. Click an asset, and click Select assets.

  7. Select values to choose how your content must be displayed:

    • Display as: Select a display type

    • Align: Where the image is aligned to

    • Caption: A caption for the image

  8. Click Embed.