Bynder extension configuration

This page explains how to configure the connection between the External DAM module and your Bynder external asset management solution.

Essentially, you:

  • Provide connection credentials for Bynder.

  • Enable the subapp to display in the Magnolia Assets app.

  • 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>.

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

Padlock 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

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.

Enabling your subapp

By default, the Bynder subapp is disabled.

To enable it, decorate the Magnolia Assets app under <dam-connector>/decorations/dam and set the enabled property to true.

dam-bynder/decorations/dam/dam.config.yaml
providers:
  bynderProvider:
    identifier: bynder
    enabled: true
    class: info.magnolia.external.dam.bynder.BynderAssetProvider
    renderers:
      bynder:
        class: info.magnolia.external.dam.bynder.BynderAssetRenderer
        proxyMode: true
        mediaTypes:
          audio: 'audio/*'
          application: 'application/*'
          video: 'video/*'
          image: 'image/*'

Configuring a single asset provider for link fields

You can configure a link field to limit your users to selecting assets from only one asset provider.

This is possible from External DAM 1.0.7 (DAM module 3.0.8). Previously, you had to use the aggregated damLinkField and users had to choose from all the enabled asset providers.

This example shows a dialog definition with two link fields, each limited to different asset providers:

external-dam/dialogs/components/textExternalImage.yaml
form:
  properties:
    bynder:
      $type: damLinkField
      chooserId: dam-bynder:chooser
      datasource:
        class: info.magnolia.dam.app.data.AssetDatasourceDefinition
        name: bynder
    jcr:
      $type: linkField
      converterClass: info.magnolia.ui.editor.converter.JcrAssetConverter
      datasource:
        $type: jcrDatasource
        workspace: website

Configuring the cache

This integration framework 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 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
      bynder-size: expireAfterAccess=60m
    enabled: true

Cache configuration properties

Property Description

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 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("bynder-objects")

Configuring pagination to improve response times

Magnolia retrieves pages of objects from 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 properties pageSize and bynderMaxNumberPerRequest.

dam-bynder/config.yaml
pageSize: 100
Property Description

pageSize

optional

The maximum number of objects per request retrieved from Bynder is 100.

bynderMaxNumberPerRequest

optional, default is 1000 (Bynder only)

Maximum number of objects that Bynder returns if you specify a pageSize greater than 1000.

See the Bynder documentation: https://bynder.docs.apiary.io/#reference/oauth-1.0a/retrieve-assets, limit parameter.

Configuring the proxy service to protect private asset URLs

To protect the URLs of private Bynder assets rendered in Magnolia, you must use the proxy service provided.

The proxy service is also required if you want to use Bynder image variations.

The proxy service enforces security by generating a Magnolia URL that hides the private Bynder URL.

If you don’t use the proxy service, private Bynder URLs are exposed in published Magnolia pages for example.

When using the proxy, if you want to make a Bynder asset public, for example an image asset used in the Pages app, you must publish the image as well as the page in Magnolia.

You can enable or disable the proxy service using the proxyMode parameter. The functionality is provided via the BynderAssetRenderer.

The proxy service is only available with Magnolia 6.2.6+. If you use an earlier version of Magnolia Core, you must disable the proxy service.
dam-bynder/decorations/dam/dam.config.yaml
providers:
  bynderProvider:
    identifier: bynder
    enabled: false
    class: info.magnolia.external.dam.bynder.BynderAssetProvider
    renderers:
      bynder:
        class: info.magnolia.external.dam.bynder.BynderAssetRenderer
        proxyMode: true
        mediaTypes:
          audio: 'audio/*'
          application: 'application/*'
          video: 'video/*'
          image: 'image/*'
Property Description

proxyMode

optional, default is true

Enables or disables the proxy service.

  • When set to true, the proxy mode is enabled. The Bynder asset generates a Magnolia URL to hide the Bynder URL and the asset is served through the Magnolia instance.

  • When set to false, the proxy mode is disabled. The Bynder asset generates a Bynder URL and the asset is served directly by Bynder. Private Bynder URLs may be exposed.

Using Bynder image derivatives

You must enable proxy mode to use Bynder derivatives in Magnolia.

Bynder provides image derivatives (referred to as variations or renditions in Magnolia) by default, such as:

  • small

  • medium

  • large

  • original

  • thumbnail

These derivatives can be used as the rendition names in the Magnolia DAM templating function (damfn).

For example, to retrieve the small Bynder derivative:

/templates/pages/sample.ftl
<!DOCTYPE html>
<html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}">
  <head>
    [@cms.page /]
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>${content.windowTitle!content.title!}</title>
  </head>
  <body class="sample-dam ${cmsfn.language()}">

    <div class="container">
      <h3>Bynder ID: ${content.assetId}</h3>

      <h4>small</h4>
      <img src="${damfn.getAssetLink(content.assetId, "small")}"/>

    </div>
  </body>
</html>

Only image type Bynder asset derivatives can be used in Magnolia.

To see which derivatives are available for a given Bynder image, look in the Size variations field in the asset details view:

Bynder derivatives information

Magnolia falls back to the original derivative if the requested derivative is unavailable.

Retrieving Bynder derivatives differs from using typical Magnolia image variations:

  • You don’t have to define image variations in a theme when using Bynder derivatives.

  • In your template script, instead of the Magnolia asset itemKey or renditionName, you use the Bynder derivative name (such as small, medium, large, original).

For more information about Bynder derivatives, see following pages in the Bynder documentation:

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta
X

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.