External DAM module
Connector Pack | DAM Connector Pack |
---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
1.0.3 |
Latest |
1.0.3 |
- 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.
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 with maven
Maven is the easiest way to install the module. Add the following to your bundle:
<dependency>
<groupId>info.magnolia.external.dam</groupId>
<artifactId>magnolia-external-dam</artifactId>
<version>1.0.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.external.dam</groupId>
<artifactId>magnolia-external-dam-bynder</artifactId>
<version>1.0.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.external.dam</groupId>
<artifactId>magnolia-external-dam-s3</artifactId>
<version>1.0.3</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.
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:
|
|
|
|
|
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.
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:
|
|
|
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
Property | Description | ||
---|---|---|---|
|
required URL to your Bynder service. |
||
|
required
|
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
cacheConfigurations:
bynder:
caches:
bynder-media: maximumSize=500, expireAfterAccess=10m
bynder-all: expireAfterAccess=60m
bynder-size: 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
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.
|
|
required, Set to |
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. |
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:
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.
maxSearchTimeInMilis: 10000
Property | Description |
---|---|
|
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.
pageSize: 100
Property | Description | ||
---|---|---|---|
|
optional The maximum number of objects per request retrieved from your external system.
|
||
|
optional, default is Maximum number of objects that Bynder returns if you specify a
|
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.
External DAM module release history
External DAM module 1.0.3
Released on December 1, 2020.
This release brings a number of improvements and bug fixes
Bynder SDK 2.2.1
The Bynder SDK version has been reverted from 2.2.4 to 2.2.1.
This resolves the issue discovered in version External DAM 1.03 that blocks users from uploading assets to Bynder via Magnolia.
See EXTDAM-189.
Publish Bynder assets from within Magnolia
You can now publish Bynder assets via the Magnolia UI.
By default, all Bynder assets are private. If you want to use Bynder assets on a public page, you must publish them to make them public.
Once Bynder assets are marked as published they cannot be unpublished or made private again in Magnolia. |
See EXTDAM-62.
External DAM module 1.0.2
Released on November 18, 2020.
This release brings compatibility for Magnolia 6.2.4 and a number of improvements and bug fixes.
We have discovered an issue with Bynder SDK version 2.2.4 and External DAM 1.0.2 that blocks users from uploading assets to Bynder via Magnolia. Do not use this release if you are a Bynder connector user. External DAM 1.0.3 corrects the issue and will be released soon. |
Improved handling of large numbers of S3 assets
Magnolia has improved how large numbers (thousands) of assets in a given S3 folder are rendered.
Magnolia has a specialized method that counts the total number of assets in your S3 system instead of creating the corresponding internal objects. Since S3 only allows batches of 1000 assets to be retrieved in a given call, we iterate as many API calls as necessary to retrieve the assets stored in S3.
For example, Magnolia must make 100 API calls to retrieve 100 000 assets. Depending on your internet bandwidth, cache and other factors, this could take around 1 minute to complete. For better response times, we recommend that you store a maximum of 10 000 assets per S3 bucket.
See EXTDAM-170 and EXTDAM-138.
Configure 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 using a new parameter called maxSearchTimeInMilis
under dam-s3/config.yaml
.
By default, the maximum search time is 10 seconds (maxSearchTimeInMilis
: 10000
).
See EXTDAM-184.
Mime types
If you upload an asset that does not have a suffix, Magnolia now infers the mime type from the binary.
To avoid extra API calls to S3, we recommend you include the suffix whenever possible.
See EXTDAM-126.
Bug fixes
See EXTDAM-167.
External DAM module 1.0.1
Released on June 22nd, 2020.
This release brings compatibility for Magnolia 6.2.1 and a number of minor improvements and bug fixes:
-
[EXTDAM-105] - (Bynder) Allow upload another image when editing
-
[EXTDAM-106] - (Bynder) Set the asset’s name with the name of the upload file
-
[EXTDAM-121 ] - Cache is not applied when browsing through app-chooser
-
[EXTDAM-119] - Adjust to Periscope changes in 6.2.1
-
[EXTDAM-104] - Show notification to the user when an async action started
-
[EXTDAM-108] - (Bynder) Correct notify message with apostrophe
-
[EXTDAM-112] - (Bynder) Edit asset fails with exception
-
[EXTDAM-113] - (Bynder) Changing the image is not reflected in the tree unless the name is updated
-
[EXTDAM-114] - Periscope search is case sensitive
-
[EXTDAM-115] - (S3) Double click on bucket or folder opens the editor
-
[EXTDAM-116] - (S3) Strange behaviour deleting a folder
-
[EXTDAM-120] - (Bynder) The item deletion does not happen immediately
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 version | Magnolia CMS version |
---|---|
1.0.3 |
6.2.4 |
1.0.2 |
6.2.4 |
1.0.1 |
6.2.1 |
1.0 |
6.2 |
connector compatibility note
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 version | Bynder SDK |
---|---|
1.0 |
Tested against 2.2.0 |
Module version | AWS Java SDK |
---|---|
1.0.1 |
2.13.25 |
1.0 |
Tested against 2.9.7 |