Placeholders

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.

Entity Placeholder

Thing Placeholder

Feature Placeholder

Policy Placeholder

Policy Entry Placeholder

Connection Placeholder

Header Placeholder

Topic Placeholder

Resource Placeholder

Request Placeholder

Time Placeholder

JWT Placeholder

Scope: Entity creation / modification

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

• request placeholder
• time placeholder

Scope: OpenID Connect configuration

When configuring OpenID connect providers in a Ditto setup, the jwt: placeholder can be used in order to extract certain claims from the JWT in order to use them as authorization subjects for Ditto’s policy based authorization.

The following placeholders may be used inside the configuration file:

• JWT placeholder

In combination with functions, use of this placeholder can provide and modify the subjects to extract from a JWT in a very powerful way.
The fn:split(' ') function may for example be used in order to further split the default claim “scope”, which is by default a whitespace separated list of scopes, as an array, producing multiple entries for each provided scope.

Example:

Assuming the provided JWT looks like this:

{
  "sub": "u123456789",
  "iss": "https://<the-issuer-domain>/",
  "exp": 1490922820,
  "iat": 1490886820,
  "email": "john.doe@eclipse.org",
  "aud": "client-id-0815",
  "scopes": "openid email",
  "extra": {
    "roles": [
      "administrator",
      "super-moderator",
      "moderator"
    ]
  }
}

Applied on the example JWT, the following jwt: placeholders in combination with functions are resolved in the following way:

• {{ jwt:sub }} - resolves to "u123456789"
• {{ jwt:sub }}@{{ jwt:aud }} - resolves to "u123456789@client-id-0815"
• {{ jwt:extra/roles }} - resolves to 3 entries: "administrator", "super-moderator" and "moderator"
• {{ jwt:scopes | fn:split(' ') }} - resolves to 2 entries: "openid" and "email"
• {{ jwt:extra/roles | fn:filter('like','*moderator') }}@{{ jwt:aud }} - resolves to 2 entries: "super-moderator@client-id-0815" and "moderator@client-id-0815"

Scope: Policy actions

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

• header placeholder
• JWT placeholder
• Policy entry placeholder
• time placeholder

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:

• topic placeholder
• resource placeholder
• time placeholder Note that in RQL expressions placeholders must not be surrounded by curly braces.

Scope: Websocket Signal Enrichment

When declaring extra fields which should be enriched to a published signal for a Websocket connection, the following placeholders are available in general:

• entity placeholder
• thing placeholder
• policy placeholder
• feature placeholder
• header placeholder
• request placeholder
• resource placeholder
• topic placeholder
• time placeholder

Scope: SSE Signal Enrichment

When declaring extra fields which should be enriched to a published signal for a Websocket connection, the following placeholders are available in general:

• entity placeholder
• thing placeholder
• policy placeholder
• feature placeholder
• header placeholder
• request placeholder
• resource placeholder
• topic placeholder
• time placeholder

Scope: Connections

In connections, the following placeholders are available in general:

• entity placeholder
• thing placeholder
• policy placeholder
• connection placeholder
• feature placeholder
• header placeholder
• request placeholder
• resource placeholder
• topic placeholder
• time placeholder

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:

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:

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() }}

Normally, the first expression in such a pipeline would be a placeholder to start with, in the example above thing:name.
Functions could follow it separated by the pipe (|) symbol - each function in the pipeline receives the value of the previous expression (which may also be empty).
A function in the beginning of a pipeline would get empty as its input.

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:

RQL functions

The following RQL functions are available for fn:filter

The like function can be used with different expressions:

• * : One or more arbitrary characters
• ? : One arbitrary character
• | : Element prior to the operator OR element after the operator