Page History
HTML Wrap | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||
|
HTML Wrap | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Related topics: |
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.
Table of Contents | ||
---|---|---|
|
Module structure
artifactID | Description |
---|---|
| Parent reactor. |
| Provides the foundation for integrating with S3 and Bynder and a sample component for using assets in the Pages app. |
| Provides a default implementation to connect to Bynder. |
| 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:
Multiexcerpt | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
|
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.
Info |
---|
If you want to connect to another third-party tool, extend the Magnolia DAM API and create your own asset provider. |
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 | ||
| ||
|
Info |
---|
The |
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:
Code Block |
---|
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 | ||
|
Connecting
Add your connection configuration under /dam-bynder/config.yaml
.
Code Block | ||
---|---|---|
| ||
bynderPortalURL: https://magnoliaintegration.getbynder.com permanentToken: <client_secret_or_path_to_password_manager> |
Connection properties
Property | Description |
---|---|
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
Code Block | ||||
---|---|---|---|---|
| ||||
cacheConfigurations: bynder: caches: bynder-media: maximumSize=500, expireAfterAccess=10m bynder-all: expireAfterAccess=60m bynder-size: expireAfterAccess=60m enabled: true |
S3 default configuration
Code Block | ||||
---|---|---|---|---|
| ||||
cacheConfigurations: s3: caches: s3-objects: maximumSize=500, expireAfterAccess=10m s3-buckets: expireAfterAccess=60m s3-count: maximumSize=500, expireAfterAccess=10m s3-pages: maximumSize=500, expireAfterAccess=10m |
Cache configuration properties
Property | Description |
---|---|
| 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:
|
enabled | required, Set to |
Note | ||
---|---|---|
| ||
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. |
Manually flushing the cache
If you want to flush the cache, you can either set the cache expiry to a very short time (see above) or configure a script in the Groovy app to flush the cache manually. For example:
Code Block | ||
---|---|---|
| ||
import info.magnolia.objectfactory.Components cacheManager = Components.getComponent(info.magnolia.addon.commons.cache.CacheManager) cacheManager.evictCache("s3-objects") |
Configuring the maximum search time for S3
You can configure the maximum time the system spends searching for S3 assets to be displayed in the Magnolia interface.
Code Block | ||||
---|---|---|---|---|
| ||||
maxSearchTimeInMilis: 10000 |
| optional The maximum time the system spends searching for S3 assets. By default, the maximum search time is 10 seconds. For example: maxSearchTimeInMilis: 10000 |
Configuring pagination to improve response times
Magnolia retrieves pages of objects from Amazon S3 and Bynder and then obtains the assets you require from those pages. The pages are cached.
You can configure the size of a page of objects using the property pageSize
.
Bynder has an additional property you can use if you set the page size to more than 1000 objects.
Code Block | ||||
---|---|---|---|---|
| ||||
pageSize: 100 |
pageSize | optional The maximum number of objects per request retrieved from your external system.
For S3, the minimum value possible is 100. The maximum is 1000. |
bynderMaxNumberPerRequest | optional, default is Maximum number of objects that Bynder returns if you specify a See the Bynder documentation: https://bynder.docs.apiary.io/#reference/oauth-1.0a/retrieve-assets, limit parameter. |
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.