![No UI](https://img.shields.io/static/v1?label=UI&message=none&color=inactive) 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. [MINITOC] ## 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](#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](#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](#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 ` - in this case there is no need for hashing as described for [token](#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. ##### 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 ##### search > type: string, required: no, since: 1.1 Search by this term (e.g. product number), behavior depends on [searchProvider](#directdownload-searchprovider) setting ##### format > type: string or long, required: no, default: [configurable](#directdownload-defaultdownloadformat) 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) ##### 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`, where you can look for the ID-parameter, e.g. ``. ##### direction > type: string ("from" or "to"), required: no, default: "from", since: 1.2 Only for the [related](#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](#directdownload-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](#directdownload-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](#search) queries ##### 1.2 > Released 2017-09-06 Added support for [relations](#related) ##### 1.3 > Released 2018-01-22 Added [defaultDownloadFormat](#directdownload-defaultdownloadformat) setting ##### 1.4 > Released 2018-02-08 Added automatic usage tracking when downloading a non-preview file and [trackingInfofieldId](#directdownload-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