Note: Please contact us to receive a quote for the configuration work involved in setting this up for you.
This article describes how to integrate Asset Bank with a CMS when you are happy for the assets to be specified in the CMS using fully-qualified URLs. It assumes that you are able to customise or configure the CMS so that you can show a button linking to Asset Bank in order to find and add assets (as described in this article).
You can view a simple implementation of the functionality here: https://downloads.assetbank.co.uk/prototypes/cms/
- In the CMS, when a user wants to select an asset (image, video, audio or file) for use in a template (or within some text) they click a button labelled, for example, 'Select Asset from Asset Bank'.
- This button opens Asset Bank in a popup window, using the url http://[URLOFASSETBANK]/action/selectImageForCms passing some mandatory parameters.
- The user can use Asset Bank as normal. The only difference is that on the asset detail page the user does not see the 'Download' button. Instead, they see a button (or link): 'Select for CMS'.
- When the user has chosen any download options they want (for example a pre-defined size, or re-sizing or cropping for images, conversions for videos and audio) they click a button, e.g., 'Select and Return to CMS'. This applies any download options to the asset selected, moves it to the web server and then returns the fully-qualified URL of this asset. I.e. The user is then returned to the CMS and the asset is automatically inserted into their content.
This integration acts in the same manner as an Asset Bank download (Quick Download will allow usage types to be selected, Advanced Download will allow conversions or cropping / resizing to take place depending on the asset type).
To use this functionality changes need to be made to the CMS to insert a button that takes the user to Asset Bank. In addition to this the CMS needs to be able to receive the response from Asset Bank and insert the asset into the content.
Details of the technical setup for this are given below.
Technical configuration : CMS
When users are passed to Asset Bank from the CMS they need to be authenticated. There are 4 options for authenticating the user which are described below:
- Authentication through single sign-on
If Asset Bank is integrated with an LDAP server and single sign-on is already setup for Asset Bank then this is the best method to authenticate users. When the user accesses Asset Bank they will be automatically signed on to Asset Bank providing they are accessing Asset Bank using Internet Explorer and are logged in to their workstation with an account which has been synchronised with Asset Bank. If a user is using a different browser or is not logged in to their workstation with an account synchronised with Asset Bank they will still be able to login but will have to supply their username/password.
- Manual sign-on
If single sign-on is not available then users can simply login to Asset Bank with their username/password. This method requires no extra development on the CMS side but is slightly more inconvenient for users as they have to supply their credentials. Functionality to allow users to select “Remember my username/password” can be enabled in Asset Bank so that users do not need to provide their credentials every time.
- Simple authentication
The CMS can simply provide the user’s username as a parameter when calling Asset Bank. Asset Bank will then log the user in without requiring their password. This solution is not recommended if your Asset Bank is available over the internet as it could be used to gain unauthorised access. However, it is simple to setup so could be a good option if your Asset Bank is hosted internally. See below how to configure the password requirement.
- Encrypted username authentication
The CMS can provide the user’s username to Asset Bank in an encrypted form. This is an extension to the simple authentication described above but is more secure as the encrypted username prevents unauthorised access. It requires the use of Asset Bank's 'Encrypted URL SSO Plugin'. This plugin takes a set of parameters that have been AES encrypted, decrypts the values provided and logs the user specified by the parameters into Asset Bank. It optionally takes a forwarding parameter to redirect the user to after login (which in the case of CMS integration would need to be the selectImageForCms action). For further details on setting up and using this SSO plugin please contact us.
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
If you are using the manual sign-on or simple authentication methods of connecting to the CMS then you will need to use the following URL to link to Asset Bank:
The password parameter can be omitted if using the simple authentication method. If you are using this authentication method and your Asset Bank uses SSO security then you also need to update the setting login-actions to include ;/action/loginFromCms at the end of the setting.
In either case, any users that need to login via this method will need to be ticked as 'can login from CMS' in the Admin > Users page.
A number of parameters can be supplied when calling the Asset Bank URL, these are described below:
- callbackurl (optional)
Ignore this parameter if you do not wish Asset Bank to post back this data.
- currentlocation (optional)
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 (optional)
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.
Asset Bank CMS integration can be set up to return the asset information to the CMS:
- 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. http://<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.
- 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:
<description><![CDATA[This is a test image]]></description>
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 be 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 include video types that can be played in browsers.
As well as the video file, the video asset's thumbnail (still) will also be copied. This will be given the same filename as the video clip, but with .jpg appended to the end.
For example, if the URL of the returned video clip is:
Then the URL of the video thumbnail file will be:
Technical configuration: Asset Bank
Please open the Asset Bank settings file (<tomcat>/asset-bank/WEB-INF/classes/ApplicationSettings.properties) and go to the section 'CMS Integration Settings'.
Here is a brief list of the main settings.
To enable basic CMS functionality please make the following configuration changes:
cms-type= (leave this blank to enable Asset Bank’s generic CMS integration functionality)
Whether to allow users to log in from a CMS application without providing a password. Set it to 'false' if you want to implement the "Simple Authentication" on internally hosted Asset Bank.
For each asset selected for the CMS, Asset Bank creates its converted version and stores it into a repository path which could either be absolute or relative to the webapp path:
Also the path could be local or remotely accessed through SCP, FTP or SFTP (Note: remote access details can be set using the properties starting with "cms-remote")
# The method of file transfer between the AssetBank application and an external CMS. Currently can be one of: 'local', 'scp', 'ftp' or 'sftp'
If the repository path has a corresponding URL, it can be set using this property (Note: we recommend not to use Asset Bank's Tomcat instance to serve the assets, so that they will not depending on its running status)
Allowed asset types for the CMS
Update the following setting to specify which asset types (defined by their file extension) are allowed to be inserted into the CMS. The setting value should be a semi-colon separated list of the allowed file extensions (i.e. jpg;gif;mpg;mp3):
The FTP connection can be configured to use active or passive mode:
- Asset Bank providing a parameter specifying the image URL
In order to use this method you will not need to pass any parameter when calling Asset Bank but you will need to set a return URL instead:
(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 '/'.)
Given the configuration above, after selecting the asset for the CMS then Asset Bank would return to the following URL:
- Asset Bank posting data to a callback URL
You will need to provide the 'callbackurl' parameter to which Asset Bank will post the asset data in XML format (as described in the section "Receiving the response from Asset Bank").
To specify which asset attributes should be returned you can use this property:
(In this example Asset Bank will pass the values of attributes with IDs 2, 4 and 5 and give them the corresponding tag names in the XML which is returned)