Configuring a Content Management System (CMS) to integrate with Asset Bank

Overview

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

Summary

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

A basic demo of this functionality is available at the following URL:
http://www.assetbank.co.uk/prototypes/cms/

This demo show the ability for the user to choose a asset and apply download options like re-sizing or cropping where appropriate (permissions allowing). 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

Authentication method

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 descried below:

  1. 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.
  2. 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.
  3. 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.
  4. 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 in to 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 support@assetbank.co.uk .

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

http://[URLOFASSETBANK]/action/selectImageForCms

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:

http://[URLOFASSETBANK]/action/loginFromCms?username=[username]&password=[password]

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/loginFromCmsat 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, which are described below:

  • callbackurl (optional)
    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 (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.

Receiving the response from Asset Bank

Asset Bank CMS integration can be set up to return the asset information to the CMS:

  • Passing a parameter to a return URL
    The system will call the provided 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
    (See our demo http://www.assetbank.co.uk/prototypes/cms/)
  • Posting data to a callback URL
    Asset Bank will post two pieces of information to the callBackUrl specified. 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.
    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>  

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 brief list of the main settings.

Enabling CMS integration

To enable basic CMS functionality please make the following configuration changes:

enable-cms-integration=true
cms-type= (leave this blank to enable Asset Bank’s generic CMS integration functionality) 

Authentication Method

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.

cms-login-requires-password=true

Storing and Serving Assets for CMS

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:

cms-repository-path=c:/cms


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'
cms-file-transfer-method=local

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)

cms-repository-url=http://my-server/cms

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):

cms-allowed-formats=jpg;gif;mpg;mp3

From v3.1565

The FTP connection can be configured to use active or passive mode:

Passive Mode

cms-remote-passive-mode=true  

Active Mode

cms-remote-passive-mode=false   

Returning to CMS

  • Passing a parameter to a return 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:
cms-return-url=http://my-server/cms-images/index.jsp   

cms-return-url-suffix
=?imageUrl=/cms-images/images (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:
http://my-server/cms-images/index.jsp?imageUrl=/cms-images/images/selected_image.jpg

  • 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 section "Receiving the response from Asset Bank").
    To specify which asset attributes should be returned you can use this property:
cms-attributes=2:title,4:description,5:altText (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)

Was this article helpful?

Yes No

Thanks for your feedback!