basic-placeholders.md

title	keywords	tags	permalink
Placeholders	placeholder, function, expression, substring, default, lower, upper	connectivity	basic-placeholders.html

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 {% raw %}{{ prefix:name }}{% endraw %}. 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
{%raw%}{{ request:subjectId }}{%endraw%}	the first authenticated subjectId which sent the command / did the request
{%raw%}{{ time:now }}{%endraw%}	the current timestamp in ISO-8601 format as string in UTC timezone
{%raw%}{{ time:now_epoch_millis }}{%endraw%}	the current timestamp in "milliseconds since epoch" formatted as string

Scope: Policy actions

In policy actions, the following placeholders are available in general:

Placeholder	Description
{%raw%}{{ header:<header-name> }}{%endraw%}	HTTP header values passed along the HTTP action request
{%raw%}{{ jwt:<jwt-body-claim> }}{%endraw%}	any standard or custom claims in the body of the authenticated JWT - e.g., jwt:sub for the JWT "subject"
{%raw%}{{ policy-entry:label }}{%endraw%}	label of the policy entry in which the token integration subject is injected
{%raw%}{{ time:now }}{%endraw%}	the current timestamp in ISO-8601 format as string in UTC timezone
{%raw%}{{ time:now_epoch_millis }}{%endraw%}	the current timestamp in "milliseconds since epoch" formatted as string

Scope: RQL expressions when filtering for Ditto Protocol messages

When using RQL expressions in scope of either change notifications or subscriptions for live messages, the following placeholders are available in general:

Placeholder	Description
topic:full	full Ditto Protocol topic path in the form {namespace}/{entityName}/{group}/ {channel}/{criterion}/{action-subject}
topic:namespace	Ditto Protocol topic namespace
topic:entityName	Ditto Protocol topic entity name
topic:group	Ditto Protocol topic group
topic:channel	Ditto Protocol topic channel
topic:criterion	Ditto Protocol topic criterion
topic:action	Ditto Protocol topic action
topic:subject	Ditto Protocol topic subject (for message commands)
topic:action-subject	either Ditto Protocol topic action or topic subject (for message commands)
resource:type	the type of the Ditto Protocol path , one of: "thing" "policy" "message" "connection"
resource:path	the affected resource's path being the Ditto Protocol path in JsonPointer notation, e.g. / when a complete thing was created/modified/deleted
time:now	the current timestamp in ISO-8601 format as string in UTC timezone
time:now_epoch_millis	the current timestamp in "milliseconds since epoch" formatted as string

Scope: Connections

In connections, the following placeholders are available in general:

Placeholder	Description
{%raw%}{{ entity:id }}{%endraw%}	full ID composed of ''namespace'' + '':'' as a separator + ''name'' for things and policies
{%raw%}{{ entity:namespace }}{%endraw%}	Namespace (i.e. first part of an ID) for things and policies
{%raw%}{{ entity:name }}{%endraw%}	Name (i.e. second part of an ID ) for things and policies
{%raw%}{{ thing:id }}{%endraw%}	full ID composed of ''namespace'' + '':'' as a separator + ''name''
{%raw%}{{ thing:namespace }}{%endraw%}	the namespace (i.e. first part of an ID) of the related thing
{%raw%}{{ thing:name }}{%endraw%}	the name (i.e. second part of an ID ) of the related thing
{%raw%}{{ feature:id }}{%endraw%}	the ID of the feature (only available if the processed signal was related to a feature)
{%raw%}{{ header:<header-name> }}{%endraw%}	external header value for connection sources, or Ditto protocol header value for targets and reply-targets (both case-insensitive)
{%raw%}{{ request:subjectId }}{%endraw%}	primary authorization subject of a command, or primary authorization subject that caused an event
{%raw%}{{ topic:full }}{%endraw%}	full Ditto Protocol topic path in the form {namespace}/{entityName}/{group}/ {channel}/{criterion}/{action-subject}
{%raw%}{{ topic:namespace }}{%endraw%}	Ditto Protocol topic namespace
{%raw%}{{ topic:entityName }}{%endraw%}	Ditto Protocol topic entity name
{%raw%}{{ topic:group }}{%endraw%}	Ditto Protocol topic group
{%raw%}{{ topic:channel }}{%endraw%}	Ditto Protocol topic channel
{%raw%}{{ topic:criterion }}{%endraw%}	Ditto Protocol topic criterion
{%raw%}{{ topic:action }}{%endraw%}	Ditto Protocol topic action
{%raw%}{{ topic:subject }}{%endraw%}	Ditto Protocol topic subject (for message commands)
{%raw%}{{ topic:action-subject }}{%endraw%}	either Ditto Protocol topic action or topic subject (for message commands)
{%raw%}{{ resource:type }}{%endraw%}	the type of the Ditto Protocol path , one of: thing, policy, message or connection
{%raw%}{{ resource:path }}{%endraw%}	the affected resource's path being the Ditto Protocol path in JsonPointer notation, e.g. / when a complete thing was created/modified/deleted
{%raw%}{{ time:now }}{%endraw%}	the current timestamp in ISO-8601 format as string in UTC timezone
{%raw%}{{ time:now_epoch_millis }}{%endraw%}	the current timestamp in "milliseconds since epoch" formatted as string

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:entityName	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:entityName	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.:

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

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:filter	(String filterValue, String rqlFunction, String comparedValue)	Removes the result of the previous expression in the pipeline unless the condition specified by the parameters is satisfied.	fn:filter(header:response-required,'eq','true') fn:filter(header:response-required,'exists') fn:filter(header:response-required,'exists','false')
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()
fn:replace	(String from, String to)	Replaces a string with another using Java's String::replace method.	fn:replace('foo', 'bar')