Back-end (CELUM Plugin)

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

Quick Start

Copy the anura-{version}.jar to {home}/appserver/lib and update your {home}/appserver/conf/custom.properties.

The simplest possible configuration looks like this:

anura.license={delivered by brix}
anura.1.name=first
anura.1.userId=123

Then restart your appserver. To test if it works, point your browser to http://your.celum.server/anura/first/node.do?about=true - there you should see some basic JSON about the endpoint:

{
  "version": 2.5,
  "status": 200,
  "data": {
    "apiVersion": 2.5,
    "celumVersion": "5.12.4",
    "userId": 123,
    ...
  }
}

If it doesn't work, check the appserver.log for ch.brix.anura-messages complaining about invalid configuration properties or license problems.

General Properties

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

anura.license

type: String, required: yes, default: -

The license for this plugin (determines validity, expiration date and how many endpoints you can add). This is delivered by brix after you supply the customer's name (xxx in {home}/appserver/conf/xxx.license.dat)

anura.cleanupCronExpression

type: String, required: no, default: 0 0/5 * * * ?

How often to run the cleanup system tasks. This removes old cached entries and temporary files.

anura.flushCronExpression

type: String, required: no, default: 0 0 0 * * ?

How often to run the cache flush task. This removes everything from all caches and is mostly there to force refreshes (when you want to push an update right away)

Dispatcher Properties

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

The back end supports multiple endpoints, so you can use several backing users and show different content, depending on the user's permission. These endpoint are separated by incrementing $i in anura.$i.propertyName, e.g. anura.1.name=first and anura.2.name=second.

You can also apply properties to all dispatchers by using anura.global.propertyName=something ($i takes precedence)

In the following properties, $i = 1 will be used as an example.

anura.1.name

type: String, required: yes, default: -

The name (whatever you like) where this endpoint can be reached at. This defines the URL that you'll use in the front end, e.g. anura.1.name=foo -> https://your.celum.server/anura/foo/bar, and is the way that anura tells the different endpoints apart.

anura.1.userId

type: long, required: yes, default: -

The ID of the CELUM user that is used to evaluate all permissions of this endpoint. If you can't see something in Anura, make sure the user that you've specified has the appropriate permissions in CELUM.

anura.1.cacheTimeSeconds

type: long, required: no, default: 3600

Practically everything gets cached internally for performance reasons. This setting defines how long an individual cache entry lasts (in seconds) until it is either reloaded automatically (node structures) or evicted (everything else).

anura.1.cacheEnabled

type: boolean, required: no, default: true, since 2.7.2

Whether to enable the internal RAM cache at all. It has the same effect as the request parameter cache=false, but permanently.

This is probably only usefull if you run Anura behind a CDN that does its own caching and you want to ensure that the upstream data is up-to-date after a flush in the CDN.

anura.1.ipWhitelist

type: List of Strings (comma separated), required: no, default: -

Only answer requests from certain IPs or IP-ranges (CIDR notation is supported). E.g. 127.0.0.1,192.168.1.0/24

If CELUM is running behind a reverse proxy, the original IP may not be retained (i.e. it's always the reverse proxy's one). You may need to configure the reverse proxy to send the original IP (Apache: RemoteIPHeader X-Forwarded-For or nginx proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;) and turn on the remote IP valve CELUM's Appserver (in /opt/celum/appserver/conf/server.xml, add <Valve className="org.apache.catalina.valves.RemoteIpValve" /> to the <Host>-section.

anura.1.forceZip

type: boolean, required: no, default: false

Force even single file downloads to be delivered in a ZIP

anura.1.relayRedirects

type: boolean, required: no, default: false

Relay redirects internally instead of forwarding. Usually requests to preview files etc. are relayed to the storage server with a HTTP redirect. This can cause problems when you employ caching reverse proxies, load balancers or use CDN services for that purpose (such as cloudflare, akamai etc.). When set to true, redirects will be followed internally, so every response appears to be coming from the appserver (and hence can be cached).

Cache poisons: callback and depending on your use case also token (this will bypass authentications that use token!).
You should exclude these GET parameters when generating the cache ID (as these may change but represent the same content).


If you want to cache binary files for a different amount of time than the JSON responses (and you can't use the MIME type), the relevant parameters of asset.do are: thmb, preview and download.

anura.1.quickDownload

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

Download format IDs that should be accessible directly in the menu (0 is interpreted original). Note that this does not consider if this asset is actually available in this format, as the SDK can't answer this question yet, so you should probably only use this on formats that always work, such as the original.

anura.1.nodeTypesAsKeywords

type: List of long (comma separated), required: no, default: 103

Node type IDs to show in the detail view's path information. This basically behaves like the "keyword paths" feature in CELUM 4 and mostly exists for backwards compatibility.

anura.1.recurseTreeWithZeroAssets

type: boolean, required: no, default: true

Stops recursing on tree calls when there are no children, because there's no point in showing loads of empty children. Only works when the asset_count argument is provided (otherwise it doesn't count at all).

anura.1.linkRelationType

type: String, required: no, default: link

Name of the relation to consider being a "linked asset", see {home}/appserver/spring/asset-relations.xml -> property name="your-id".

anura.1.maxLinkRelations

type: int, required: no, default: 5

The maximum number of linked assets to load.

anura.1.nodeInfoProvider

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

Custom bean that loads additional information in node referencing infofields, such as information fields on the referenced node. Must implement the NodeInfoProvider interface:

package ch.brix.anura.provider;

public interface NodeInfoProvider {
    String getInfo(InformationFieldValue<?, ?> info, Node node, Locale locale);
}
anura.1.downloadHandler

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

Custom bean to handle asset downloads differently (e.g. prompt for login or reason etc). Known implementations:

  • anuraDefaultDownloader - simply delivers the requested file(s).
  • anuraLoginFilterDownloader - requires you to login with CELUM credentials for certain download formats.
    • anura.loginFilterDownloader.requireLogin - list of download format IDs to require a login for, e.g. 1,2,3. Since 2.6.8 you can also pass -1 to require a login for every format.
  • anuraMailInputDownloader - requires you to enter your e-mail address (and an optional reason for the download) before you can proceed.
    • anura.1.mailInputReason - also require a reason (text area) to be filled out. Default is false.
    • anura.1.mailInputCss - Custom CSS to add to the mail input, e.g. .something {foo: bar;}.
  • anuraAssetOrderDownloader - integration with the AssetOrder plugin

Must implement the DownloadHandler interface:

package ch.brix.anura.download;

public interface DownloadHandler {
    void download(AnuraRequest request, AnuraResponse response, AnuraConfig config, List<DownloadRequest> download, Locale locale) throws Exception;
}

This property is subject to license restrictions. If you've configured it but it doesn't do anything, check the appserver.log for license errors - the property might have been dropped.

anura.1.videoStreamProvider

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

Custom bean to resolve where the video file comes from (e.g. some CDN) when using the built-in video player. Must implement the VideoStreamProvider interface. If none is provided (and no videoPlayerProvider is configured), the video preview from the storage server is used. Known implementations:

  • anuraInfofieldStreamProvider - reads the file URL from an information field
    • anura.infofieldStreamProvider.sourceInfofieldId - ID of the information field to read the file URL part from, e.g. 101
    • anura.infofieldStreamProvider.prefix - Static prefix for the URL, e.g. http://your.cdn.com/videos/
    • anura.infofieldStreamProvider.suffix - Static suffix for the URL, e.g. .mp4

Must implement the VideoStreamProvider interface:

package ch.brix.anura.provider;

public interface VideoStreamProvider {
    String getVideoUrl(AssetId assetId, AnuraConfig config);
}
anura.1.videoPlayerProvider

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

Custom bean to resolve what video player URL (e.g. vimeo) to use. When configured, this will take precedence over the videoStreamProvider. Known implementations:

  • anuraInfofieldPlayerProvider - reads the player URL from an information field
    • anura.infofieldPlayerProvider.sourceInfofieldId - ID of the information field to read the player URL part from, e.g. 101
    • anura.infofieldPlayerProvider.prefix - Static prefix for the URL, e.g. https://player.vimeo.com/video/
    • anura.infofieldPlayerProvider.suffix - Static suffix for the URL, e.g. ?autoplay=true
  • Backstage integrations. You can optionally filter by stage handler by specifying anura.1.videoProviderStageHandlerId=123
    • anuraMovingImagePlayerProvider - asks the moving image backstage component. Requires the anuraMovingImage-{version}.jar to be installed.
    • anuraYoutubePlayerProvider - asks the youtube backstage component. Requires the anuraYoutube-{version}.jar to be installed.
    • anuraVimeoPlayerProvider - asks the vimeo backstage component. Requires the anuraVimeo-{version}.jar to be installed.

Must implement the VideoPlayerProvider interface:

package ch.brix.anura.provider;

public interface VideoPlayerProvider {
    String getVideoPlayer(AssetId assetId, AnuraConfig config, boolean autoplay);
}
anura.1.videoSearchRegex

type: string, required: no, default: -

Performs arbitrary search & replace on generated video URLs (only works together with videoReplaceString).

Use Case: Some players pass their player ID (look and feel) in their public URL, but it's always the same. This way you can smiply override this on a per-dispatcher basis.

anura.1.videoReplaceString

type: string, required: no, default: -

Performs arbitrary search & replace on generated video URLs (only works together with videoSearchRegex).

anura.1.propertyBlacklist

type: List of String (comma separated), required: no, default: -

Blacklists certain asset properties from being delivered in the asset details response - one of name, asset_type, created, modified, extension, filesize, downloadable, dpi, duration, dimensions, aspect_ratio, colorspace, profile, codec, pages, vector, raster, duration, scanType, frameRate, channel, bitRate, sampleRate, artist, trackTitle, albumTitle, trackNumber, year, genre

anura.1.downloadFormatBlacklist

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

Blacklist certain download formats (because of the SDK issue where you can only get download format permissions based on the file extension, rather than based on the actual asset)

anura.1.videoPlayerCss

type: String, required: no, default: -

Custom CSS to add to the built-in video player page.

anura.1.fallbackImages

type: List of String (comma separated), required: no, default: -

Specify alternative preview images if the asset doesn't have one. By default, the generic CELUM placeholder image is used. You can override this by file category, e.g. default=/images/default-dummy.jpg,image=/images/image-dummy.jpg,video=/images/video-dummy.jpg

anura.1.assetInfoFields

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

IDs of additional asset information fields to send with every asset response. Less is more, but it may be usefull for asset markers etc.

anura.1.nodeInfoFields

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

IDs of additional node information fields to send with every tree response. Less is more, but it may be usefull for asset markers etc.

anura.1.tokenVerifier

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

Custom bean to do verify access tokens sent via the token parameter. This is usefull when Anura is running in a login-protected CMS environment. In that case the CMS could for example create a hash of the SessionID and pass it as &token=.... In your custom verifier you'd then go ask the CMS if it knows a given token (and cache that for a bit!).

token verifier flow

Known implementations:

  • anuraStaticTokenVerifier - simple static token configured via the anura.1.staticToken property (built-in). The corresponding JS for the front-end would be $.anura.tokenProvider = function () {return 'sameStaticTokenAsInTheProperty';};
  • anuraLoginTokenVerifier - requires you to login with CELUM to get a token. You'll need the anura anura-login-token.jar extension and an interceptor on the front-end. Note that the flow is slightly different in this case: token verifier flow CELUM

This property is subject to license restrictions. If you've configured it but it doesn't do anything, check the appserver.log for license errors - the property might have been dropped.

anura.1.customSearchProvider

type: bean name, required: no, default: -, since: 2.7.0

Custom search parser based on the optional search_custom parameter. Through this mechanism you can implement your own business logic and return an SDK AssetFilter that will then be applied in addition to all other search parameters (AND).

There are no known public implementations. Custom implementations must implement the CustomSearchProvider interface:

package ch.brix.anura.provider.search;

public interface CustomSearchProvider {
    AssetFilter parseCustomSearch(String request, AnuraConfig anuraConfig, Locale locale);
}
anura.1.globalFilter

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

Enforces an additional, global view restriction in every response, expressed through a search filter. This filter gets applied to whatever else is happening through an AND operation. This way the asset either doesn't show up in a list response, or it triggers a not found (404) in direct queries.

The syntax is the same as the API's search, but without the search_ prefix.

Example: anura.1.globalFilter=infofield=137,null,now - filters on the information field with the ID 137 (a date field) and looks for a date between whenever and now. This simulates the Asset Availability feature, but with a custom information field.

anura.1.facetProvider

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

What method to use to provide faceted search. The only known implementation is anuraSolrSearchRequestHandler, which requires you to have setup your SOLR server accordingly.

Faceted search

Anura offers faceted search since version 2.6. In order for this to work, you'll need to add the anuraSolr-{version}.jar to {home}/appserver/lib and configure your SOLR server accordingly. Anura requires an extra index per referenced CELUM user, as permissions are not reflected in the search index, so we have to maintain a separate index per user that reflects what that user can see.

Installation

  1. go to {home}/searchserver/solrhome
  2. copy the existing assets folder and call it assetsAnura{userId} (e.g. assetsAnura42 if your anura-user has the ID 42 - check anura.$i.userId)

    Make sure the directory is writable by the tomcat user, otherwise the indexing will fail later on

  3. CELUM 5.13.4 onwards or whenever the data directory is not inside the solrhome directory: Change the dataDir property in the copied assetsAnura{userId}/conf/solrconfig.xml to <dataDir>${solr.assetsAnura{userId}.data.dir:}</dataDir> (e.g. <dataDir>${solr.assetsAnura42.data.dir:}</dataDir>)

    Next, the file assetsAnura{userId}/core.properties must be adjusted as follows: name = assetsAnura{userId}

    Depending on the age of you conf/schema.xml, you may need to add docValues="true" to certain fields (observed with date and tdate on line 130+), otherwise you get a Can't facet on a Point Field without docValues

    CELUM 5.13.3 and before: Add your new core to the solr.xml file (you can copy the assets line here as well)

    <cores adminPath="/admin/cores">
    <core name="assets" instanceDir="assets" />
    <core name="assetsAnura42" instanceDir="assetsAnura42" /> <!-- this -->
    <core name="containers" instanceDir="containers" />
    <core name="tasks" instanceDir="tasks" />
    <core name="processInstances" instanceDir="processInstances" />
    </cores>

    If you have customized the data directory of your asset core, e.g. by specifying -Dsolr.assets.data.dir=..., you'll need to change the dataDir property in the copied assetsAnura{userId}/conf/solrconfig.xml to something else, e.g. <dataDir>${solr.assetsAnura42.data.dir:}</dataDir> so you could pass -Dsolr.assetsAnura42.data.dir=... - otherwise it tries to write to the existing asset core data directory and fails.

  4. Restart the search server. In its web-UI, you should now see the new core in the "Core Selector" dropdown.
  5. Configure the facetProvider-property (e.g. anura.1.facetProvider=anuraSolrSearchRequestHandler) and restart the app server.
  6. In CELUM, go to Administration > System Tasks > Anura and start the Recreate facet search index task. Because there are no permission events in the SDK, you may also need to do that when you change the anura user's role(-assignments).
  7. You can now use facets: true in anuraSearch

Properties

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

anuraSolr.useSDKForFulltextSearch

type: boolean, required: no, default: false

Set this property to true, to use the SDK for fulltext search.

anuraSolr.facetLimit

type: boolean, required: no, default: -1

Set this property to another value 'x' to get only top 'x' facet result per faceted field. Not recommendet.

Troubleshooting

When you get either no results or all the faceted options get removed instantly after loading the page, check:

  • that the SOLR core was actually created successfully - see if it exists in the "Core Selector" on the left side of the SOLR UI. Observed mistakes include
    • Incorrect, missing or non-readable configuration files (check solr log)
    • Multiple cores using the same dataDir (see above)
    • the dataDir is not writable to the SOLR user
  • you have a current version of the conf/schema.xml and aren't missing any docValues (see above)

CELUM Login Token Verifier

One of the TokenVerifiers we provide out-of-the-box is one that lets you authenticate agains CELUM. Additionally, you can also decide which Anura endpoint a user should use based on group assignments in CELUM. Note however that the endpoint still uses its configured user - in other words this does not enable you to do user-level permissions or statistics.

Installation

Grab the anura-login-token-{version}.jar and put it in {home}/appserver/lib. You may now use anuraLoginTokenVerifier in anura.1.tokenVerifier and this snippet in your front-end.

Properties

anuraLoginToken.endPointToUserGroupMap

type: Map{String, List{Long}}, required: no, default: null

This allows you to map endpoints to user groups. In other words you can dynamically decide which Anura endpoint an authenticating user should be using for this session. Specify the endpoints with the most rights first because if a user is in several groups, he will get the first end point that was found.

Example: foo:1,2,3;bar:4,5,6;baz:7,8,9 assigns the endpoint foo to users that are in groups 1, 2 or 3, etc.

anuraLoginToken.expiresAfterNoAccessForMinutes

type: int, required: no, default: 30

Number of minutes with no access until the token expires.

anuraLoginToken.forceExpirationMinutesAfterCreation

type: int, required: no, default: 300

Number of minutes after creation whereafter a token is forced to expire, regardless of access.

anuraLoginToken.validChars

type: String, required: no, default: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-

Characters used for the token generation, they have to be valid in an URL without encoding

anuraLoginToken.tokenLength

type: int, required: no, default: 32

The length (number of characters) of the token that will be generated

Release Notes

1.0
  • Initial release
1.1
  • Added parameter to force ZIP even for single files
  • Added parameter to request extended information in node response
1.2
  • Added Cache-Control headers
  • Extended asset details response
  • Added more search parameters
1.3
  • Added support for top downloads (based on statistics)
  • Improved JSONP handling
1.4
  • Improved performance of node-Controller significantly
  • Added additional settings and an argument for bigger thumbs
  • Added timestampable ACL Cache
1.6
  • Added "Cache Cleaner" Task
  • Implemented direct streaming of audio/video previews (with Byte-Range Requests)
1.7
  • Refactored detail view response (and added legacy syntax support)
  • Added support for StreamingServices
  • Added usage reference handling (optional)
1.8
  • Added support for DirectDownloadLink
  • Added keyword_paths processing to the backend
  • Improved startup stability (celum wouldn't start if the config was wrong) and cache cleaner
  • Prevented celum from sending HTML when there's an Exception
1.9
  • Added download permission check to extended node info
  • Added support for AssetMarker (ims_custom to extended node info)
  • Added support for DownloadOrder-Plugin
  • Added parameter to download a collection directly
  • Added parameter to search by file extension
  • Improved download argument syntax (foo=1,2 insted on just foo=1&foo=2)
2.0

Released 2015-10-16

  • Complete rewrite for CELUM 5 (while keeping the API as stable as possible)
2.1

Released 2016-05-16

  • Added asset type search parameter
  • Added sort option parameters
  • Added search by ID
2.2

Released 2016-07-27

  • Added pagination support to child- and search-queries
  • Added asset relations (links)
  • Added support for global configs
  • Added download format by extension query
  • Added "navigation context" support (treat noderefs as assigned to keyword)
  • Extended asset detail response (download fotmats, noderef infos)
  • Added cache flushing system task
2.3

Released 2017-01-03

  • Added smarter cache eviction handler
  • Updated video player for 5.12.2
  • Added workaround for getting the icon of a download format
  • Added support for node info provider
  • Added license handling
  • Added abstrct DownloadHandler so you can implement your own
  • Implemented RegisteredDownloadHandler (user needs to register to get certain formats)
2.4

Released 2017-04-05

  • Added support for relaying redirects through appserver
  • Added workaround for missing dropdown locales
  • Added token verifier feature
  • Added additional accepted sort parameters
  • Added hard limit parameter (also affects result count)
  • Added support for querying multiple infofields at once
  • Added support for external video players
2.5

Released 2017-07-18

  • Added support for CELUM backstage (for video playback)
  • Added file property blacklist
  • Added configurable fallback images and player CSS
  • Added crawler support (dedicated HTML output)
  • Added basic support for infofields in asset list responses
2.6

Released 2018-04-05

  • Added faceted search
  • Added download format blacklist
  • Implemented MailInputDownloadHandler
  • Reintroduced the "top download" feature
  • Added support for deep link reverse path resolution (for lazy loading)
  • Fixed infofields not being reloaded in time
  • Added support for passing locale as a DownloadOption
  • Added asset type query support
  • Added info about existing DownloadInterceptors (paperFormat, imageEditor etc.) and preliminary support for PaperFormat DownloadOptions
2.7

Released 2019-06-19

  • Added support for querying all infofield definitions at once (by passing -1)
  • Added support for requiring a login for all download format by passing -1 to anura.loginFilterDownloader.requireLogin
  • Added support for inner AND mode in infofields by concatinating the search values with + instead of ,
  • Introduced tokenVerifier and added the staticTokenVerifier
  • Introduced customSearchProvider
  • Stoped recursing on empty trees (by default)
  • Added search & replace feature for video URLs
  • Added configuration to completely disable the internal cache (for when there's an external egde cache)
  • Added infofield capabilities to the download_for query (to show infofields in the basket)
  • Added support for searching by NodeType

Faceted Search

1.0.0
  • Initial release
1.1.3
  • Improved error handling
1.1.9
  • Improved indexing