Direct Link Cache
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)
- cropToFit (optional)
- download (optional) - e.g. for retrieving a video asset
- format (optional) - the image format to retreive (valid values are: jpg, gif or png).
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 size of width X height pixels, i.e. this will define a bounding box into which the image will fit. If cropToFit is specified the image will be cropped during resizing so that it completely fills the bounding box. The aspect ratio of the source image will be maintained, unless the preserveAspectRatio parameter is specified and has a value of false, in which case the returned image will have a size of width X height pixels even if this results in the image being stretched or squashed.
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 ‘access level’ 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 access level 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:
...asset-bank/action/directLinkImage?assetId=297&width=1000&height=1000
Using an attribute to match on:
.../directLinkImage?attributeId=4&attributeValue=MyImage&width=1000&height=1000
Downloading the target file (i.e. a download dialog will be shown):
...asset-bank/action/directLinkImage?assetId=297&download=true