Direct Download

No UI

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 useful 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 IT Solutions)

directDownload.userId

type: long (user ID), required: probably, 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.

Alternatively you can pass the secret as an Authorization header, e.g. Authorization: Bearer <your-secret> - in this case there is no need for hashing as described for token, as it's not visible in the URL (since 1.8.2-6.4.0/1.6.9-15.3.4). Authentication is an alias.

Defining a secret and using hashed tokens is strongly recommended, as only this will protect the secret from a MITM attack. In other words, only use the header when hashing is not possible for technical reasons.

BREAKING CHANGE as of 6.17: you need to add this to the sdk.property.whitelist=directDownload.secret in order for CELUM not censor this property

directDownload.showMenu

type: boolean, required: no, default: false, since 1.9

Whether to show a context menu entry that allows the users to directly generate and share a direct download link in the UI.

directDownload.visibleForGroup

type: List of long (comma-separated), required: no, default: -, since 1.9

To which user group ID(s) to show the menu to (only relevant when directDownload.showMenu=true)

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

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)
  • Public URL by passing publicurl (since 1.8) - requires additional parameters:
    • description (required) the description of the desired PublicURL (think of this as a key)
    • provider (optional) the provider of the desired PublicURL
    • instance (optional) the instance of the desired PublicURL
relay

type: boolean, required: no

Override for relaying requests (see settings above)

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, where you can 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.

This does not apply when requesting thumbnails or previews

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 - download a low-res PDF (format 81) from an InDesign document (Asset 8290): https://your.server/direct/download?id=8290&format=81
  • Call by search term "papilio en" - download the preview image: https://your.server/direct/download?search=%22papilio%20en%22&format=prvw

Compatibility Matrix

directDownload CELUM (min. version)
1.0 - 1.3 5.12.3
1.4 - 1.5 5.12.4
1.6 5.13.4
1.7 - 1.9 6.4.0, tested up to 6.16.0

Release Notes

1.0

Released 2017-04-21

Initial release

1.1

Released 2017-05-22

Added support for search queries

1.2

Released 2017-09-06

Added support for relations

1.3

Released 2018-01-22

Added defaultDownloadFormat setting

1.4

Released 2018-02-08

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

1.5

Released 2019-01-07

Added protection with token and secret

1.6

Released 2019-08-29

Added filename resolver capability

1.7

Released 2020-01-24

Established compatibility with CELUM 6.x, added X-Robots-Tag

1.8

Released 2021-09-16

Added PublicURL support

1.9

Released 2022-01-03

Added a share context menu