Models

Connection

object

idstring

The generated unique identifier of the connection

namestring

The name of the connection

connectionTypeConnectionTypeamqp-091amqp-10http-pushmqttmqtt-5kafka,honorequired

The type of a connection

connectionStatusConnectivityStatusopenclosedfailedmisconfiguredunknownrequired

The status of a connection or resource

uristringrequired

The URI of the connection

sourcesArray<Source>required

The subscription sources of this connection

Show child attributes

A subscription source subscribed by this connection

addressesArray<string>

The source addresses this connection consumes messages from. The "telemetry", "events", "command_response" aliases should be used for connections of type "hono".

consumerCountinteger1

The number of consumers that should be attached to each source address

qosinteger

Maximum Quality-of-Service level to request when subscribing for messages

authorizationContextArray<string>

The authorization context defines all authorization subjects associated for this source

enforcementobject

Defines an enforcement for this source to make sure that a device can only access its associated Thing.

Show child attributes

inputstringrequired

The input value of the enforcement that should identify the origin of the message (e.g. a device id). You can use placeholders within this field depending on the connection type. E.g. for AMQP 1.0 connections you can use {{ header:[any-header-name] }} to resolve the value from a message header.

Example

{{ header:device_id }}

filtersArray<string>required

An array of filters. One of the defined filters must match the input value from the message otherwise the message is rejected.

acknowledgementRequestsobject

Contains requests to acknowledgements which must be fulfilled before a message consumed from this source is technically settled/ACKed at the e.g. message broker.

Show child attributes

includesArray<string>required

Acknowledgement requests to be included for each message consumed by this source.

filterstring

Optional filter to be applied to the requested acknowledgements - takes an fn:filter() function expression

Example

[
  "fn:filter(header:qos,'ne',0)"
]

payloadMappingArray<string>

A list of payload mappings that are applied to messages received via this source. If no payload mapping is specified the standard Ditto mapping is used as default.

headerMappingobject

Ditto protocol headers computed from external headers and certain properties of the Ditto protocol messages created by payload mapping.

replyTargetobject

Configuration for sending responses of incoming commands.

Show child attributes

enabledboolean

Whether reply target is enabled.

addressstringrequired

The target address where responses of incoming commands from the parent source are published to. The following placeholders are allowed within the target address:

Thing ID: {{ thing:id }}
Thing Namespace: {{ thing:namespace }}
Thing Name: {{ thing:name }} (the part of the ID without the namespace)
Ditto protocol topic attribute: {{ topic:[topic-placeholder-attr] }}
Ditto protocol header value: {{ header:[any-header-name] }}

If placeholder resolution fails for a response, then the response is dropped. NOTE Use "command" alias for connections of type "hono".

Example

[
  "{{ header:device_id }}",
  "{{ source:address }}"
]

headerMappingobject

External headers computed from headers and other properties of Ditto protocol messages.

expectedResponseTypesArray<string>responseerrornack

Contains a list of response types that should be published to the reply target.

targetsArray<Target>required

The publish targets of this connection

Show child attributes

A publish target served by this connection

addressstring

The target address where events, commands and messages are published to. The following placeholders are allowed within the target address:

Thing ID: {{ thing:id }}
Thing Namespace: {{ thing:namespace }}
Thing Name: {{ thing:name }} (the part of the ID without the namespace) NOTE Use "command" alias for connections of type "hono".

topicsArray<string>_/_/things/twin/events_/_/things/live/commands_/_/things/live/events_/_/things/live/messages_/_/policies/announcements_/_/connections/announcements

The topics to which this target is registered for

qosinteger

Maximum Quality-of-Service level to request when subscribing for messages

authorizationContextArray<string>

The authorization context defines all authorization subjects associated for this target

issuedAcknowledgementLabelstring

The optional label of an acknowledgement which should automatically be issued by this target based on the technical settlement/ACK the connection channel provides.

payloadMappingArray<string>

A list of payload mappings that are applied to messages sent via this target. If no payload mapping is specified the standard Ditto mapping is used as default.

headerMappingobject

External headers computed from headers and other properties of Ditto protocol messages.

specificConfigobject

Configuration which is only applicable for a specific connection type

clientCountnumber

How many clients on different cluster nodes should establish the connection

failoverEnabledboolean

Whether or not failover is enabled for this connection

validateCertificatesboolean

Whether or not to validate server certificates on connection establishment

mappingDefinitionsPayloadMappingDefinitions

List of mapping definitions where the key represents the ID of each mapping that can be used in sources and targets to reference a mapping.

Show child attributes

[key: string]PayloadMappingDefinition

A mapping definition consisting of the used mappingEngine and the options required by this engine.

Show child attributes

mappingEnginestringrequired

The mapping engine used to process incoming and outgoing messages. Available mapping engines are JavaScript, Normalized, ConnectionStatus, RawMessage, Ditto, ImplicitThingCreation, and UpdateTwinWithLiveResponse.

optionsobjectrequired

Configuration options specific to the used mapping engine:

JavaScript

incomingScript (string, required): The mapping script for incoming messages
outgoingScript (string, required): The mapping script for outgoing messages
loadBytebufferJS (boolean, optional): Whether or not ByteBufferJS library should be included (default: false)
loadLongJS (boolean, optional): Whether or not LongJS library should be included (default: false)

Normalized

fields (string, optional): Comma separated list of fields included in the normalized message (default: all fields included)

ConnectionStatus

thingId (string, required): The ID of the thing
featureId (string, optional): The ID of the modified feature (default: ConnectionStatus)

RawMessage

outgoingContentType (string, optional): The fallback content type for outgoing messages.
incomingMessageHeaders (object, optional): The fallback headers for incoming messages containing the necessary information to map them to message commands and responses. The relevant header keys are: content-type, ditto-message-subject, ditto-message-direction, ditto-message-thing-id, ditto-message-feature-id and status. The header values may contain placeholder expressions.

Ditto

no options required

ImplicitThingCreation

thing (object, required): The template of the thing to be implicitly created

UpdateTwinWithLiveResponse

dittoHeadersForMerge (object, optional): The Ditto headers to use for constructing the "merge thing" command for updating the twin, may for example add a condition to apply in order to update the twin (default ditto headers: response-required: false, if-match: "*").

incomingConditionsobject

Optional conditions to be checked before applying the mapping engine to inbound messages. Can use placeholders and functional expressions.

outgoingConditionsobject

Optional conditions to be checked before applying the mapping engine to outbound messages. Can use placeholders and functional expressions.

mappingContextMappingContextdeprecated

MappingContext to apply in this connection containing JavaScript scripts mapping from external messages to internal Ditto Protocol messages. Usage of MappingContext is deprecated, use PayloadMappingDefinitions instead.

Show child attributes

incomingScriptstringrequired

The mapping script for incoming messages

outgoingScriptstringrequired

The mapping script for outgoing messages

loadBytebufferJSbooleanrequired

Whether or not ByteBufferJS library should be included

loadLongJSbooleanrequired

Whether or not LongJS library should be included

sshTunnelobject

The configuration of a local SSH port forwarding used to tunnel the connection to the actual endpoint.

Show child attributes

enabledbooleanrequired

Whether the tunnel is enabled

Example

true

uristringrequired

The URI of the SSH host in the format ssh://[host]:[port].

Example

ssh://some.host:2222

credentialsobjectrequired

The credentials used to authenticate at the SSH host. Password and public key authentication are supported.

Show child attributes

typestringpasswordpublic-keyrequired

The type of credentials used to authenticate. Either password or public-key.

Example

password

usernamestringrequired

The username used for the authentication.

Example

user42

passwordstring

The password used for authentication when credentials type password is used.

Example

secret!

publicKeystring

Public key in PEM base64-encoded format using X.509 syntax. This field is required for credentials type public-key.

Example

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

privateKeystring

Private key in PEM base64-encoded format using PKCS #8 syntax. This field is required for credentials type public-key.

Example

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

validateHostboolean

Whether the SSH host is validated using the provided fingerprints.

Example

true

knownHostsArray<string>

A list of accepted public key fingerprints. One of these fingerprints must match the fingerprint of the public key the SSH host provides.

Example

[
  "MD5:e0:3a:34:1c:68:ed:c6:bc:7c:ca:a8:67:c7:45:2b:19"
]

tagsArray<string>

The tags of the connection

Example

{
  "id": "string",
  "name": "string",
  "connectionType": "amqp-091",
  "connectionStatus": "open",
  "uri": "string",
  "sources": [
    {
      "addresses": [
        "string"
      ],
      "consumerCount": 1,
      "qos": 0,
      "authorizationContext": [
        [
          "ditto:myAuthorizationSubject",
          "device:{{ header:device_id }}"
        ]
      ],
      "enforcement": {
        "input": "{{ header:device_id }}",
        "filters": [
          [
            "{{ thing:id }}",
            "{{ thing:namespace }}/{{ thing:name }}"
          ]
        ]
      },
      "acknowledgementRequests": {
        "includes": [
          "string"
        ],
        "filter": [
          "fn:filter(header:qos,'ne',0)"
        ]
      },
      "payloadMapping": [
        [
          "Ditto",
          "status"
        ]
      ],
      "headerMapping": {},
      "replyTarget": {
        "enabled": true,
        "address": [
          "{{ header:device_id }}",
          "{{ source:address }}"
        ],
        "headerMapping": {},
        "expectedResponseTypes": [
          "response"
        ]
      }
    }
  ],
  "targets": [
    {
      "address": "string",
      "topics": [
        "_/_/things/twin/events"
      ],
      "qos": 0,
      "authorizationContext": [
        [
          "ditto:myAuthorizationSubject"
        ]
      ],
      "issuedAcknowledgementLabel": "string",
      "payloadMapping": [
        [
          "javascript"
        ]
      ],
      "headerMapping": {}
    }
  ],
  "specificConfig": {},
  "clientCount": 0,
  "failoverEnabled": true,
  "validateCertificates": true,
  "mappingDefinitions": {},
  "mappingContext": {
    "incomingScript": "string",
    "outgoingScript": "string",
    "loadBytebufferJS": true,
    "loadLongJS": true
  },
  "sshTunnel": {
    "enabled": true,
    "uri": "ssh://some.host:2222",
    "credentials": {
      "type": "password",
      "username": "user42",
      "password": "secret!",
      "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
    },
    "validateHost": true,
    "knownHosts": [
      "MD5:e0:3a:34:1c:68:ed:c6:bc:7c:ca:a8:67:c7:45:2b:19"
    ]
  },
  "tags": [
    "string"
  ]
}

Docs by Sourcey