Direct Download

For the most up-to-date documentation, please visit docs.brix.ch

When individual assets should be made available externally (e.g. for calls from external systems or referencing in a website) in the original or a specific download format without a PIN code as a simple link, look no further than "Direct Download". The link is static and always delivers the latest version of the CELUM Asset. This is also usefull if you want to link assets in your CMS without having to download them to the CMS. Via the regular API, the download link expires after a short time - this one doesn't.

This use case has been superseded by PublicURLs in more recent versions of CELUM

The plugin is also able to search for an asset using full-text search, a specific information field (e.g. article number), or a customer-specific criterion. In that case the first (highest ranking) found asset is returned.

Properties

To be configured in {home}/appserver/conf/custom.properties

directDownload.license

type: String, required: yes, default: -

license key (delivered by brix cross media)

directDownload.userId

type: long (user ID), required: no, default: -

The user to use for downloading and assessing permissions - otherwise a login prompt to be shown, in which case that user will be used.

Even though this property is not required, you'll probably want to configure it (except in special cases)

directDownload.relayRedirects

type: boolean, required: no, default: false

Default value for the relay parameter - whether to relay redirects through the application server instead of redirecting to the conversion/storage-server URL. This may be useful if you need static URLs for caching etc. and no upload mechanism is in place.

directDownload.searchProvider

type: bean name, required: no, default: directDownloadFulltextSearchProvider

Name of the bean that provides the search functionality for ?search=''foo'', e.g. look for something in a specific infofield. Defaults to ''directDownloadFulltextSearchProvider'' (simple full-text search).

directDownload.fallbackImage

type: bean string, required: no, default: /images/200x200_bw/icon_unsupported_filetype.png

Image to deliver when nothing could be found. An empty fallbackImage will return a plain HTTP 404.

directDownload.defaultDownloadFormat

type: string or long, required: no, default: thmb, since: 1.3

The default download format that is used when no format parameter was provided.

directDownload.trackingInfofieldId

type: long, required: no, default: -, since 1.4

Information field (noderef) that will be used for tracking consumers (such as your CMS). Make sure that it's available for your user and asset type(s).

directDownload.secret

type: String, required: no, default: -, since 1.5.1

If a secret is specified all requests need to send a valid access token or they will be denied. Only useful when the direct download links are built on the server side.

Request Parameters

Base-URL: {celum}/direct/download

id

type: long (asset ID), required: probably

The ID of the requested asset - required unless you want to use search

search

type: string, required: no, since: 1.1

Search by this term (e.g. product number), behavior depends on searchProvider setting

format

type: string or long, required: no, default: configurable

The download format ID or preview format name to use.

  • Download format IDs: see Administration > Download Format Groups and Permissions
  • Standard format names:
    • thmb (jpg up to 250x250px)
    • prvw (jpg up to 1024x1024px)
    • largeprvw (jpg up to 3000x3000px)
    • orig or original (the original file)
relay

type: boolean, required: no

Override for relaying requests (see settings above)

related

type: string, required: no, since: 1.2

Instead of returning the asset, return the first related asset of the type related. You can find all available relation-types in {home}/appserver/spring/asset-relations.xml, there look for the ID-parameter, e.g. <property name="id" value="languageVariant" />.

direction

type: string ("from" or "to"), required: no, default: "from", since: 1.2

Only for the related-parameter, looks either for a relation originating from or to the asset.

consumer

type: string, required: no, default: "directDownload", since: 1.3

Specify what service consumed this asset. This is used for the download statistics and if trackingInfofieldId is set for the usage tracking as well. E.g. /direct/download?id=1337&format=orig&consumer=Wordpress will assign (or create) a node "Wordpress" to that assets tracking infofield.

token

type: string, required: if a secret was specified, since 1.5.1

The token is built the following way: sha256hex(id + search + secret). In other words the id string (without id=), search string and secret are concatenated, then the SHA-256 message digest of the concatenated string is built and expressed as hex string.

Examples

  • Call by ID, without login - downloads a low-res PDF from an InDesign document: https://mediahub.brix.ch/direct/download?id=8290&format=81
  • Call by search term, without login - downloads a preview image: https://mediahub.brix.ch/direct/download?search=%22papilio%20en%22&format=prvw
  • Call by ID, with login (demo/demo) - downloads the original file: https://dam-demo.brix.ch/direct/download?id=3679&format=1

Release Notes

1.1

Added support for search queries

1.2

Added support for relations

1.3

Added defaultDownloadFormat setting

1.4

Added automatic usage tracking when downloading a non-preview file and trackingInfofieldId is set

1.5.1

Added protection with token and secret