Integration: Drupal 8.4 and later¶

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.

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.

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.

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.

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.

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.

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¶

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.