Page tree
Skip to end of metadata
Go to start of metadata


The DAM Connector Pack modules allow you to connect to your external DAM and make your existing assets, including videos, PDFs and images, available directly within Magnolia. 

Module structure

artifactIDDescription

magnolia-external-dam-parent

Parent reactor.

magnolia-external-dam

Provides the foundation for integrating with S3 and Bynder and a sample component for using assets in the Pages app.

magnolia-external-dam-bynder

Provides a default implementation to connect to Bynder.

magnolia-external-dam-s3

Provides a default implementation to connect to Amazon S3.

Installing

Maven is the easiest way to install the modules. Add the following dependencies to your webapp. All the other necessary dependencies will be brought in automatically:

<dependency>
  <groupId>info.magnolia.external.dam</groupId>
  <artifactId>magnolia-external-dam</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.external.dam</groupId>
  <artifactId>magnolia-external-dam-bynder</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.external.dam</groupId>
  <artifactId>magnolia-external-dam-s3</artifactId>
  <version>1.0</version>
</dependency>

Configuration

This section explains how to configure the connection between the External DAM module and your external asset management solution. Essentially, you:

  • Provide connection credentials for your external solution.
  • Configure the cache if necessary.

You can create or edit the configuration in the JCR or the File System (YAML) under <module-name>/external-dams/<definition-name>.

Before you configure the connection, make sure you know:

  • Which solution you want to connect to. Default implementations are provided for:
    • AWS S3
    • Bynder
  • Connection credentials for your solution.

AWS S3 connection configuration

To use AWS S3 assets in Magnolia, you must have a working AWS account.

Credentials

You need AWS S3 credentials to connect your S3 buckets and display their content in Magnolia. Credentials consist of two parts: 

  • AWS access key ID
  • AWS secret access key

Add these credentials to your Magnolia instance in the Password manager app. For example:

  aws-credentials



aws_access_key_id


aws_secret_access_key



The  magnolia-aws-foundation module handles all Amazon connections from Magnolia.  This module is installed automatically by Maven when you install the External DAM module.

Configuring an AWS S3 bucket whitelist

By default, all the buckets in the S3 account you connect to are displayed. If you do not want to display all your buckets, you can configure a whitelist under /dam-s3/config.yaml using regex.

For example:

whitelistedBuckets:
- "^a.*"
- a-particular-bucket

Bynder connection configuration

To use Bynder assets in Magnolia, you must have a working Bynder account.

API token

You need a permanent OAuth 2.0 API token from Bynder to access the assets.

To generate a token, see this Bynder documentation: https://help.bynder.com/system/oauth2-permanent-tokens.htm

You can use the token value directly in the yaml configuration or add the permanent token to your Magnolia instance in the Password manager app and reference the path in the configuration. For example:

  bynder-credentials



 bynder_permanent_token

Connecting

Add your connection configuration under /dam-bynder/config.yaml.

bynderPortalURL: https://magnoliaintegration.getbynder.com
permanentToken: <client_secret_or_path_to_password_manager>
Connection properties
PropertyDescription
bynderPortalURL

required

URL to your Bynder service.

permanentToken

required

A permanent OAuth 2.0 API token from Bynder or the path to the Passwords app where the token is stored. 

Configuring the cache

This connector pack uses Caffeine, a high-performance Java cache library, to manage caching for external assets via a Magnolia helper module called magnolia-addon-commons-cache.

For Bynder and S3 caching, you can specify the behavior of the caches. Essentially, you can configure all the parameters available in CaffeineSpec. For example:

  • Set a maximum cache size.
  • Define how often the cache expires.

Additionally, you can:

  • Enable or disable the cache. 

You configure caching through decoration under /<dam-connector>/decorations/addon-commons-cache/config.yaml.

Bynder default configuration

/dam-bynder/decorations/addon-commons-cache/config.yaml
cacheConfigurations:
  bynder:
    caches:
      bynder-media: maximumSize=500, expireAfterAccess=10m
      bynder-all: expireAfterAccess=60m
    enabled: true

S3 default configuration

/dam-s3/decorations/addon-commons-cache/config.yaml
cacheConfigurations:
  s3:
    caches:
      s3-objects: maximumSize=500, expireAfterAccess=10m
      s3-buckets: expireAfterAccess=60m
    enabled: true
Cache configuration properties
PropertyDescription

caches

required

Use CaffeineSpec properties to specify the cache behavior such as the maximum size of the cache and when cache entries expire for each cache.

For example:

<cacheName-1>: maximumSize=500, expireAfterAccess=10m

<cacheName-2>: expireAfterAccess=60m

enabled

required, true by default

Set to false to disable caching.

Bynder loading times

Note that the Bynder API may be very slow in some regions. For example, one image upload may take up to 20 seconds in EU regions. This may cause some actions to fail in the Magnolia UI and the cache to be invalidated.

For more information, see https://github.com/Bynder/bynder-js-sdk/issues/43.

Usage

The  magnolia-external-dam submodule provides a sample Text and external image page component so that editors and marketers can select and use external assets in the Pages app. See DAM Connector Pack for an example.

Release history

External DAM module 1.0

Released on April 6, 2020.

Initial release of the DAM Connector Pack for integrating with Bynder and Amazon S3, so that you can use your assets directly in Magnolia. 

See DAM Connector Pack for an overview of the functionality provided.

DAM Connector Pack compatibility

Module versionMagnolia CMS version

1.0 

6.2


A note about connector compatibilty

The third-party versions listed below are the versions Magnolia has developed and tested against. If you don’t see a particular version listed, it simply means that we do not routinely test on it.

If you are using another version of the third-party tool and run into compatibility issues, please contact our Support team

Module versionBynder SDK
1.0Tested against 2.2.0
Module versionAWS Java SDK
1.0Tested against 2.9.7