Placeholders

Placeholders may be used at several places in Ditto where something should be resolved by a variable.
The general syntax of a placeholder is {{ prefix:name }}. Which placeholder values are available depends on the context where the placeholder is used.

Scope: Entity creation / modification

Whenever creating or modifying things or policies, the following placeholders may be used:

Placeholder Description
{{ request:subjectId }} the first authenticated subjectId which sent the command / did the request

Scope: Connections

In connections, the following placeholders are available in general:

Placeholder Description
{{ thing:id }} full ID composed of ‘‘namespace’’ + ‘’:’’ as a separator + ‘‘name’’
{{ thing:namespace }} Namespace (i.e. first part of an ID)
{{ thing:name }} Name (i.e. second part of an ID )
{{ header:<header-name> }} any external protocol header
{{ topic:full }} full Ditto Protocol topic path
in the form {namespace}/{entityId}/{group}/
{channel}/{criterion}/{action-subject}
{{ topic:namespace }} Ditto Protocol Namespace
{{ topic:entityId }} Ditto Protocol Entity ID
{{ topic:group }} Ditto Protocol Group
{{ topic:channel }} Ditto Protocol Channel
{{ topic:criterion }} Ditto Protocol Criterion
{{ topic:action }} Ditto Protocol Action
{{ topic:subject }} Ditto Protocol Subject (for message commands)
{{ topic:action-subject }} either Ditto Protocol Action or Subject (for message commands)

Examples

For a topic path with the intention of creating a Thing org.eclipse.ditto/device-123/things/twin/commands/create these placeholders would be resolved as follows:

Placeholder Resolved value
topic:full org.eclipse.ditto/device-123/things/twin/commands/create
topic:namespace org.eclipse.ditto
topic:entityId device-123
topic:group things
topic:channel twin
topic:criterion commands
topic:action create
topic:subject
topic:action-subject create

For a topic path with the intention of sending a message to a Thing org.eclipse.ditto/device-123/things/live/messages/hello.world these placeholders are resolved as follows:

Placeholder Resolved value
topic:full org.eclipse.ditto/device-123/things/live/messages/hello.world
topic:namespace org.eclipse.ditto
topic:entityId device-123
topic:group things
topic:channel live
topic:criterion messages
topic:action
topic:subject hello.world
topic:action-subject hello.world

Function expressions

Whenever placeholders can be used (e.g. for connections), function expressions may additionally be specified.

The syntax of such function expressions are specified similar to a UNIX pipe, e.g.:

{{ thing:name | fn:substring-before('-') | fn:default('fallback') | fn:upper() }}

The first expression in such a pipeline must always be a placeholder to start with, in the example above thing:name.
Followed are functions separated by the pipe (|) symbol - each function in the pipeline receives the value of the previous expression (which may also be empty).

The function either contains no parameters or contains parameters which are either string constants or could also be placeholders again.

Function library

The following functions are provided by Ditto out of the box:

Name Signature Description Examples
fn:default (String defaultValue) Provides the passed defaultValue when the previous expression in a pipeline resolved to empty (e.g. due to a non-defined header placeholder key).
Another placeholder may be specified which is resolved to a String and inserted as defaultValue.
fn:default('fallback')
fn:default("fallback")
fn:default(thing:id)
fn:substring-before (String givenString) Parses the result of the previous expression and passes along only the characters before the first occurrence of givenString.
If givenString is not contained, this function will resolve to empty.
fn:substring-before(':')
fn:substring-before(":")
fn:substring-after (String givenString) Parses the result of the previous expression and passes along only the characters after the first occurrence of givenString.
If givenString is not contained, this function will resolve to empty.
fn:substring-after(':')
fn:substring-after(":")
fn:lower () Makes the String result of the previous expression lowercase in total. fn:lower()
fn:upper () Makes the String result of the previous expression uppercase in total. fn:upper()
Tags: connectivity