Overview

Asset Bank can be configured to integrate with a CMS system, allowing CMS users to select assets from Asset Bank to be directly imported to their CMS project without the need for downloading the asset first.

From a users perspective, the steps are:

• In the CMS, a user will click a button called 'Select asset from Asset Bank' or similar.
• The button opens up Asset Bank in a pop-up window.
• The user can browse or search Asset Bank as usual, the only difference being that when they find the asset they want, instead of a 'Download' button they will see a 'Select for CMS' button.
• Users can select from any download options that are configured or create their own sizing or crop.
• The user is then returned to the CMS with the asset inserted into their content.

You can view a simple implementation of the functionality here: https://downloads.assetbank.co.uk/prototypes/cms/.

Considerations

For cloud-hosted customers, the files used in the CMS must be stored outside of Asset Bank. This means transferring the files to a file storage that you own, such as an S3 bucket, or to the server hosting the CMS if you host it yourself.

Additionally to this, functionality changes need to be made to the CMS to insert a button that takes the user to Asset Bank. The CMS also needs to be able to receive the response from Asset Bank and insert the asset into the content.

Technical configuration - CMS side

This is the configuration that you will need to do within the CMS. We provide this documentation and can help with specific questions you have but we are unable to configure this on your behalf.

Authentication method

When passed to Asset Bank from the CMS, users will need to authenticate as an Asset Bank user. Usually, this means the CMS taking the user to the Asset Bank login page where the user can log in with their username and password or through SSO if that is configured for your Asset Bank.

Linking to Asset Bank from the CMS

The CMS will need to be modified to allow users to access Asset Bank to select an asset. This is normally done by adding a button to the content editor which links to Asset Bank, via the URL:

https://example.assetbank-server.com/assetbank-example/action/selectImageForCms

If you are using the simple authentication method of connecting to the CMS then you will need to use the following URL to link to Asset Bank:

https://example.assetbank-server.com/assetbank-example/action/loginFromCms?username=[username]&password=[password]

A number of optional parameters can be supplied when calling the Asset Bank URL, these are described below.

callbackurl - This is a URL on the client’s server that Asset Bank will post the information back to. Data is posted back in XML format (more details of this are given in the next section). This page is then responsible for using Javascript to insert the asset into the CMS. This method is used rather than Asset Bank posting back directly to the CMS to avoid cross-site scripting issues (Javascript cannot be used to transfer data between pages on different domains).
Ignore this parameter if you do not wish Asset Bank to post back this data.

currentlocation - The current location within the CMS can be passed to Asset Bank. This will allow Asset Bank to automatically log the location where the asset is being used. This is then available in asset usage reports.

placeholder - A placeholder location can be passed to Asset Bank. This is simply passed back to the CMS but it allows the CMS to have multiple places to insert assets from Asset Bank on the same page. When the response is received from Asset Bank it will contain the placeholder so the CMS will know which area this request refers to.

Receiving the response from Asset Bank

The integration can be set up to return the asset information to the CMS in one of two ways:

• By Asset Bank providing a parameter to a return URL
  Asset Bank will call the provided CMS return URL (the setting cms-return-url) passing the complete URL to the asset which has been selected, e.g. https://<Your-Cms-Return-Url>?imageUrl=<Image-Url>/image.jpg. This will only happen if a callBackUrl was not provided in the link to Asset Bank from the CMS.
• By Asset Bank posting data to a callback URL
  Asset Bank will post two pieces of information to the callbackUrl, if it was specified in the link to Asset Bank from the CMS. The first of these is simply the placeholder so that the CMS knows which piece of content this request relates to (if there are more than one).
  The system also passes back the URL of the asset and optionally metadata about the asset in XML format. If the cms-repository-url setting has a value then the URL will be a fully qualified link to the image. Otherwise, it will be the path of the image on disk.
  Further instructions on how to specify which attributes within Asset Bank are supplied to the CMS are provided below.
  Any number of text attributes can be sent to the CMS (for example to specify a caption or alt text for the asset without the user having to enter these manually).
  An example of the XML response received is shown below:

<xml> 
  <url><![CDATA[http://cms-server/image.jpg]]></url> 
  <title><![CDATA[Test image]]></title> 
  <description><![CDATA[This is a test image]]></description> 
  <width><![CDATA[500]]></width> 
  <height><![CDATA[700]]></height> 
</xml>  

Selecting Video Assets

Video assets can be selected for CMS in Asset Bank, just like images. The URL to the asset returned to the CMS will link to a copy of the video's source file, so make sure that the allowed file types (see the cms-allowed-formats setting below) only includes video types that can be played in browsers.

As well as the video file, the video asset's thumbnail will also be copied. This will be given the same filename as the video but with .jpg appended to the end.

For example, if the URL of the returned video clip is https://cms-server/my-video.mp4 then the URL of the video thumbnail file will be https://cms-server/my-video.mp4.jpg.

Technical configuration - Asset Bank side

When configuring the CMS integration, we will need to update the relevant settings in Asset Bank. Therefore, we will request the following information.

Transferring the data

Converted versions of assets that have been selected for use in the CMS must be stored off of the Asset Bank server, in a storage device that you own. Therefore we will need to know the following information on how to transfer the data to the storage server.

# The transfer protocol for transferring the files. Can be SCP, FTP or SFTP.
cms-file-transfer-method =
# The hostname of the storage server.
cms-remote-host =
# The port to use on the storage server.
cms-remote-port =
# The username to connect to the storage server with.
cms-remote-username =
# The password of the user.
cms-remote-password =
# The private key of the user (only for SCP or SFTP, ignored if cms-remote-password is set).
cms-remote-private-key =
# For FTP transfers is the transfer active or passive. Can be true or false.
cms-remote-passive-mode =
# The absolute path for the data to be transfered to on the storage server.
cms-repository-path =

Returning to the CMS

Once a selected asset has been converted and sent to the storage server with the above details, Asset Bank will return the user to the CMS and provide information to the CMS about the transferred data. For this, we will need to know the following.

# The URL corresponding to the location set in cms-repository-path to be passed to the CMS.
cms-repository-url =
# The URL to return to the user to.
cms-return-url = https://example.cms.url/your-cms/index.jsp
# A suffix that will be added to the return URL. If this suffix has a value, the filename will be added to this. Don't add a trailing /.
cms-return-url-suffix = ?imageUrl=/cms-images
# The URL to call to cancel. Leave blank if the user should just close the window.
cms-cancel-url =

With the above examples for cms-return-url and cms-return-url-suffix, Asset Bank will instruct the CMS to find the file at https://example.cms.url/your-cms/index.jsp?imageUrl=/cms-images/selected_file.jpg.

Additional settings

There are a few additional settings that can be configured.

# The file types that are allowed to be sent to the CMS. Delimit each with a ; character (eg. jpg;png;gif).
cms-allowed-formats =
# Whether or not to use the embedded data mappings to embed metadata in the files sent to the CMS. Can be true or false.
cms-embed-metadata =
# If true, filenames will have a number appended if that filename already exists. If false, existing files with the same filename will be replaced.
cms-destination-filenames-unique =
 # A list of attribute IDs and corresponding XML tag names to be passed to the CMS (e.g. 2:title,4:description,5:altText)
cms-attributes =

For on-premise customers

On-premise customers will need to first ensure that the CMS integration is included in their license. Please check the [tomcat]/webapps/asset-bank/WEB-INF/classes/license.lic file, which should have 'cms' listed in the list of Features. If it does not, please contact our support team. Do not edit this file yourself as it will invalidate the license.

Once you have confirmed that the CMS integration is licensed, open the [tomcat]/webapps/asset-bank/WEB-INF/classes/ApplicationSettings.properties file and update all of the above settings. When you're ready to test the integration set the below setting and restart the Tomcat service.

enable-cms-integration=true