Note: In older versions of Asset Bank 'folders' were called 'access levels'
The direct link cache provides an action (URL) that converts and returns an image based on request parameters, if the conversion has previously been done then the image is returned from a cache.
The action receives the following parameters:
- assetId or attributeId + attributeValue (mandatory)
- width (mandatory)
- height (mandatory)
- preserveAspectRatio (optional)
- preserveColorSpace (optional)
- cropToFit (optional) - this defaults to true
- download (optional) - e.g. for retrieving a video asset
- format (optional) - the image format to retrieve (valid values are: jpg, gif or png).
- fillBackground (optional) - fill the background of the bounding box if cropToFit=false
- fillBackgroundColour (optional) - specify the background fill colour in hexadicimal - six characters are required but no hash character, e.g black would be fillBackgroundColour=000000
This action will return an image created from the asset where the specified attribute has the specified value or where the assets id matches the given assetId parameter (if it matches a non-image asset then an error code will be returned, and if the value matches more than one asset then an arbitrary asset will be chosen from the matching ones).
The attribute referred to by attributeId must be a textual attribute (e.g. it cannot be a date or dropdown).
The returned image will have a maximum pixel size defined by the width and height parameters. By default the aspect ratio of the original image will be maintained and the image will be resized and cropped as required so it completely fills a bounding box of width X height pixels. Alternatively if the cropToFit parameter is specified and has a value of false the aspect ratio will be maintained but no cropping will take place such that the image will fit, but may not completely fill the bounding box. By default the requested image will be converted to the RGB colour space unless the preserveColorSpace is set to true. Finally if both the cropToFit and preserveAspectRatio parameters are specified and have values of false no cropping will take place and the image will be stretched and/or squashed so it completely fills the bounding box
If the format parameter is passed then the resulting image should be returned in the format requested. If the format isn't specified then the image will be a GIF if the source image is a GIF, a PNG if the source is PNG and a JPEG otherwise.
Before creating the image Asset Bank will check to see if it already has the required image (including size) in a cache – if so it will returned the cached version. Cached versions will be deleted if the source image is changed, or its asset record is deleted. The location of the cache is defined by the direct-image-link-cache-dir which is relative to the file-cache-directory setting.
To ensure that Asset Bank’s security model isn’t compromised there is a setting that controls the permission level that requests to this action have. The setting is direct-image-link-permission-group and this should contain the ID of one of Asset Bank’s ‘groups’. The folders permissions assigned to this group will applied in order to determine whether or not a particular image can be viewed using the new action.
If a requested image is not in an folder that is visible to this group then the action will return a ‘no permission’ code (HTTP status code 403) If the application setting does not contain a valid group ID then the new action will return the ‘no permission’ code for all requests.
Step-by-Step Instructions to enable this functionality
- Create a new group (called for example 'Direct Link Group')
- Set relevant permissions in this group (this is where you decide what assets will be available for direct link, and what will not)
- When editing this new group (Admin > Groups > Edit) , you will see its 'id' in the URL, note this down (e.g. ...viewGroup?id=13...).
- Edit your Asset Bank settings file (<tomcat home>\webapps\asset-bank\WEB-INF\classes\ApplicationSettings.properties) and add the 'id' after the equals sign for the following setting:
Then save the settings file, and re-start your Asset Bank web application to enable this feature
URLs to call the action will look like this:
Using asset ID:
Using an attribute to match on:
Downloading the target file (i.e. a download dialog will be shown):