blob: 651c303bd4c34f6497f8e17e629ed9336921b606 [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="connectivity, connection, connectivity, mapping, connection, integration, placeholder, qos, at least once, delivery, guarantee">
<title> Connections • Eclipse Ditto™ • a digital twin framework</title>
<link rel="stylesheet" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/modern-business.css">
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/boxshadowproperties.css">
<link rel="stylesheet" href="css/theme-ditto.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Organization",
"url": "https://eclipse.org/ditto/",
"logo": "https://eclipse.org/ditto/images/ditto.svg"
}
</script>
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="images/favicon-96x96.png" sizes="96x96">
<link rel="alternate" type="application/rss+xml" title="Eclipse Ditto Blog" href="https://www.eclipse.org/ditto/feed.xml">
<!-- Eclipse Foundation cookie consent: -->
<link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
<script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>
<script>
$(document).ready(function() {
$("#tg-sb-link").click(function() {
$("#tg-sb-sidebar").toggle();
$("#tg-sb-content").toggleClass('col-md-9');
$("#tg-sb-content").toggleClass('col-md-12');
$("#tg-sb-icon").toggleClass('fa-toggle-on');
$("#tg-sb-icon").toggleClass('fa-toggle-off');
});
});
</script>
</head>
<script>
(function(w,d,s,l,i){
w[l]=w[l]||[];
w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});
var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),
dl=l!='dataLayer'?'&l='+l:'';
j.async=true;
j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5WLCZXC');
</script>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container topnavlinks">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-ditto-home" href="index.html">&nbsp;<img src="images/ditto_allwhite_symbolonly.svg" class="ditto-navbar-symbol" alt="Home"> <img src="images/ditto_allwhite_textonly.svg" class="ditto-navbar-symbol-text" alt="Eclipse Ditto™"></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<!-- toggle sidebar button -->
<!--<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>-->
<!-- entries without drop-downs appear here -->
<li><a href="blog.html">Blog</a></li>
<li><a href="intro-overview.html">Documentation</a></li>
<li><a href="http-api-doc.html">HTTP API</a></li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="https://github.com/eclipse/ditto" target="_blank">
<img src="images/GitHub-Mark-Light-32px.png" alt="Sources at GitHub">
</a></li>
<li><a href="https://github.com/eclipse/ditto-clients" target="_blank">
<img src="images/GitHub-Mark-Light-32px.png" alt="SDK sources at GitHub">SDKs
</a></li>
<li><a href="https://github.com/eclipse/ditto-examples" target="_blank">
<img src="images/GitHub-Mark-Light-32px.png" alt="Example sources at GitHub">examples
</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Links<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://projects.eclipse.org/projects/iot.ditto" target="_blank">Eclipse Ditto Project</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/364/" target="_blank">Forum</a></li>
<li><a href="https://ci.eclipse.org/ditto/" target="_blank">Jenkins</a></li>
<li><a href="https://dev.eclipse.org/mhonarc/lists/ditto-dev/" target="_blank">Mailing list archives</a></li>
<li><a href="https://gitter.im/eclipse/ditto" target="_blank">Gitter.im chat</a></li>
</ul>
</li>
<!--comment out this block if you want to hide search-->
<li>
<!--start search-->
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="//cdnjs.cloudflare.com/ajax/libs/simple-jekyll-search/0.0.9/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'search.json',
searchResultTemplate: '<li><a href="{url}" title="Connections">{title}</a></li>',
noResultsText: 'No results found.',
limit: 10,
fuzzy: true,
})
</script>
<!--end search-->
</li>
</ul>
</div>
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<div class="container">
<div id="main">
<!-- Content Row -->
<div class="row">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle">
<label for="docVersion">Eclipse Ditto™ version:</label>
<div class="select-wrapper">
<select id="docVersion" name="docVersion">
<option value="">development</option>
<option value="2.0">2.0</option>
<option value="1.5">1.5</option>
<option value="1.4">1.4</option>
<option value="1.3">1.3</option>
<option value="1.2">1.2</option>
<option value="1.1">1.1</option>
<option value="1.0">1.0</option>
</select>
</div>
<div id="dev-warning">
<div markdown="span" class="alert alert-warning" role="alert" style="font-size:0.6em"><i class="fa fa-warning"></i> <b>Important:</b> This documentation reflects the latest 'development'. You might want to choose a released version.</div>
</div>
</li>
<li class="subfolders">
<a href="#"><span></span>Introduction</a>
<ul>
<li><a href="intro-overview.html">Overview</a></li>
<li><a href="intro-digitaltwins.html">Digital twins</a></li>
<li><a href="intro-hello-world.html">Hello world</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Release Notes</a>
<ul>
<li><a href="release_notes_201.html">2.0.1</a></li>
<li><a href="release_notes_200.html">2.0.0</a></li>
<li><a href="release_notes_151.html">1.5.1</a></li>
<li><a href="release_notes_150.html">1.5.0</a></li>
<li class="subfolders">
<a href="#"><span></span>Archive</a>
<ul>
<li><a href="release_notes_140.html">1.4.0</a></li>
<li><a href="release_notes_130.html">1.3.0</a></li>
<li><a href="release_notes_121.html">1.2.1</a></li>
<li><a href="release_notes_120.html">1.2.0</a></li>
<li><a href="release_notes_115.html">1.1.5</a></li>
<li><a href="release_notes_113.html">1.1.3</a></li>
<li><a href="release_notes_112.html">1.1.2</a></li>
<li><a href="release_notes_111.html">1.1.1</a></li>
<li><a href="release_notes_110.html">1.1.0</a></li>
<li><a href="release_notes_100.html">1.0.0</a></li>
<li><a href="release_notes_090.html">0.9.0</a></li>
<li><a href="release_notes_080.html">0.8.0</a></li>
<li><a href="release_notes_100-M2.html">1.0.0-M2</a></li>
<li><a href="release_notes_100-M1a.html">1.0.0-M1a</a></li>
<li><a href="release_notes_090-M2.html">0.9.0-M2</a></li>
<li><a href="release_notes_090-M1.html">0.9.0-M1</a></li>
<li><a href="release_notes_080-M3.html">0.8.0-M3</a></li>
<li><a href="release_notes_080-M2.html">0.8.0-M2</a></li>
<li><a href="release_notes_080-M1.html">0.8.0-M1</a></li>
<li><a href="release_notes_030-M2.html">0.3.0-M2</a></li>
<li><a href="release_notes_030-M1.html">0.3.0-M1</a></li>
<li><a href="release_notes_020-M1.html">0.2.0-M1</a></li>
<li><a href="release_notes_010-M3.html">0.1.0-M3</a></li>
<li><a href="release_notes_010-M1.html">0.1.0-M1</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Installation</a>
<ul>
<li><a href="installation-building.html">Building Ditto</a></li>
<li><a href="installation-running.html">Running Ditto</a></li>
<li><a href="installation-operating.html">Operating Ditto</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Basic concepts</a>
<ul>
<li><a href="basic-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Model entities</a>
<ul>
<li><a href="basic-thing.html">Thing</a></li>
<li><a href="basic-feature.html">Feature</a></li>
<li><a href="basic-policy.html">Policy</a></li>
<li><a href="basic-namespaces-and-names.html">Namespaces and Names</a></li>
<li><a href="basic-metadata.html">Thing Metadata</a></li>
<li><a href="basic-errors.html">Errors</a></li>
</ul>
</li>
<li><a href="basic-auth.html">Authentication and Authorization</a></li>
<li><a href="basic-messages.html">Messages</a></li>
<li><a href="basic-signals.html">Signals</a></li>
<li class="subfolders">
<a href="#"><span></span>Signal types</a>
<ul>
<li><a href="basic-signals-command.html">Command</a></li>
<li><a href="basic-signals-commandresponse.html">Command response</a></li>
<li><a href="basic-signals-errorresponse.html">Error response</a></li>
<li><a href="basic-signals-event.html">Event</a></li>
<li><a href="basic-signals-announcement.html">Announcement</a></li>
</ul>
</li>
<li><a href="basic-apis.html">APIs</a></li>
<li class="active"><a href="basic-connections.html">Connections</a></li>
<li><a href="basic-placeholders.html">Placeholders</a></li>
<li><a href="basic-changenotifications.html">Change notifications</a></li>
<li><a href="basic-rql.html">RQL expressions</a></li>
<li><a href="basic-enrichment.html">Signal enrichment</a></li>
<li><a href="basic-search.html">Search</a></li>
<li><a href="basic-acknowledgements.html">Acknowledgements / QoS</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Advanced concepts</a>
<ul>
<li><a href="advanced-data-by-pass.html">Data By-Pass</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Architecture</a>
<ul>
<li><a href="architecture-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Services</a>
<ul>
<li><a href="architecture-services-policies.html">Policies</a></li>
<li><a href="architecture-services-things.html">Things</a></li>
<li><a href="architecture-services-things-search.html">Things-Search</a></li>
<li><a href="architecture-services-connectivity.html">Connectivity</a></li>
<li><a href="architecture-services-concierge.html">Concierge</a></li>
<li><a href="architecture-services-gateway.html">Gateway</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>HTTP API</a>
<ul>
<li><a href="httpapi-overview.html">Overview</a></li>
<li><a href="httpapi-concepts.html">Concepts</a></li>
<li><a href="httpapi-search.html">Search</a></li>
<li><a href="httpapi-messages.html">Messages</a></li>
<li><a href="httpapi-protocol-bindings-websocket.html">WebSocket protocol binding</a></li>
<li><a href="httpapi-protocol-bindings-cloudevents.html">Cloud Events HTTP protocol binding</a></li>
<li><a href="httpapi-sse.html">Server sent events</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Connectivity API</a>
<ul>
<li><a href="connectivity-overview.html">Overview</a></li>
<li><a href="connectivity-manage-connections.html">Manage connections</a></li>
<li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x protocol binding</a></li>
<li><a href="connectivity-mapping.html">Payload mapping</a></li>
<li><a href="connectivity-header-mapping.html">Header mapping</a></li>
<li><a href="connectivity-tls-certificates.html">TLS certificates</a></li>
<li><a href="connectivity-ssh-tunneling.html">SSH tunneling</a></li>
<li><a href="connectivity-hmac-signing.html">HMAC signing</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Client SDK</a>
<ul>
<li><a href="client-sdk-overview.html">Overview</a></li>
<li><a href="client-sdk-java.html">Java</a></li>
<li><a href="client-sdk-javascript.html">JavaScript</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Ditto Protocol</a>
<ul>
<li><a href="protocol-overview.html">Overview</a></li>
<li><a href="protocol-twinlive.html">Twin/live channel</a></li>
<li><a href="protocol-specification.html">Specification</a></li>
<li><a href="protocol-specification-topic.html">Protocol topic</a></li>
<li><a href="protocol-specification-errors.html">Errors</a></li>
<li><a href="protocol-specification-things.html">Things group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-things-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-things-merge.html">Merge</a></li>
<li><a href="protocol-specification-things-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-things-delete.html">Delete</a></li>
<li><a href="protocol-specification-acks.html">Acknowledgements</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ search/messages</a>
<ul>
<li><a href="protocol-specification-things-search.html">Search</a></li>
<li><a href="protocol-specification-things-messages.html">Messages</a></li>
</ul>
</li>
<li><a href="protocol-specification-policies.html">Policies group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/announcements</a>
<ul>
<li><a href="protocol-specification-policies-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-policies-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-policies-delete.html">Delete</a></li>
<li><a href="protocol-specification-policies-announcement.html">Announcement</a></li>
</ul>
</li>
<li><a href="protocol-specification-connections.html">Connections group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ announcements</a>
<ul>
<li><a href="protocol-specification-connections-announcement.html">Announcement</a></li>
</ul>
</li>
<li><a href="protocol-bindings.html">Bindings</a></li>
<li><a href="protocol-examples.html">Examples</a></li>
<li class="subfolders">
<a href="#"><span></span>→ Things examples</a>
<ul>
<li><a href="protocol-examples-creatething.html">Create a Thing</a></li>
<li><a href="protocol-examples-deletething.html">Delete a Thing</a></li>
<li><a href="protocol-examples-modifything.html">Modify a Thing</a></li>
<li><a href="protocol-examples-retrievething.html">Retrieve a Thing</a></li>
<li><a href="protocol-examples-retrievethings.html">Retrieve multiple Things</a></li>
<li><a href="protocol-examples-modifypolicyid.html">Modify the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-createattributes.html">Create Attributes</a></li>
<li><a href="protocol-examples-deleteattributes.html">Delete Attributes</a></li>
<li><a href="protocol-examples-modifyattributes.html">Modify Attributes</a></li>
<li><a href="protocol-examples-retrieveattributes.html">Retrieve Attributes</a></li>
<li><a href="protocol-examples-createattribute.html">Create a single Attribute</a></li>
<li><a href="protocol-examples-deleteattribute.html">Delete a single Attribute</a></li>
<li><a href="protocol-examples-modifyattribute.html">Modify a single Attribute</a></li>
<li><a href="protocol-examples-retrieveattribute.html">Retrieve a single Attribute</a></li>
<li><a href="protocol-examples-createthingdefinition.html">Create a Definition</a></li>
<li><a href="protocol-examples-deletethingdefinition.html">Delete a Definition</a></li>
<li><a href="protocol-examples-modifythingdefinition.html">Modify a Definition</a></li>
<li><a href="protocol-examples-retrievethingdefinition.html">Retrieve a Definition</a></li>
<li><a href="protocol-examples-createfeatures.html">Create Features</a></li>
<li><a href="protocol-examples-deletefeatures.html">Delete Features</a></li>
<li><a href="protocol-examples-modifyfeatures.html">Modify Features</a></li>
<li><a href="protocol-examples-retrievefeatures.html">Retrieve Features</a></li>
<li><a href="protocol-examples-createfeature.html">Create a single Feature</a></li>
<li><a href="protocol-examples-deletefeature.html">Delete a single Feature</a></li>
<li><a href="protocol-examples-modifyfeature.html">Modify a single Feature</a></li>
<li><a href="protocol-examples-retrievefeature.html">Retrieve a single Feature</a></li>
<li><a href="protocol-examples-createdefinition.html">Create Feature Definition</a></li>
<li><a href="protocol-examples-deletedefinition.html">Delete Feature Definition</a></li>
<li><a href="protocol-examples-modifydefinition.html">Modify Feature Definition</a></li>
<li><a href="protocol-examples-retrievedefinition.html">Retrieve Feature Definition</a></li>
<li><a href="protocol-examples-createproperties.html">Create Feature Properties</a></li>
<li><a href="protocol-examples-deleteproperties.html">Delete Feature Properties</a></li>
<li><a href="protocol-examples-modifyproperties.html">Modify Feature Properties</a></li>
<li><a href="protocol-examples-retrieveproperties.html">Retrieve Feature Properties</a></li>
<li><a href="protocol-examples-createproperty.html">Create a single Property</a></li>
<li><a href="protocol-examples-deleteproperty.html">Delete a single Property</a></li>
<li><a href="protocol-examples-modifyproperty.html">Modify a single Property</a></li>
<li><a href="protocol-examples-retrieveproperty.html">Retrieve a single Property</a></li>
<li><a href="protocol-examples-createdesiredproperties.html">Create desired Feature Properties</a></li>
<li><a href="protocol-examples-deletedesiredproperties.html">Delete desired Feature Properties</a></li>
<li><a href="protocol-examples-modifydesiredproperties.html">Modify desired Feature Properties</a></li>
<li><a href="protocol-examples-retrievedesiredproperties.html">Retrieve desired Feature Properties</a></li>
<li><a href="protocol-examples-createdesiredproperty.html">Create a single desired Property</a></li>
<li><a href="protocol-examples-deletedesiredproperty.html">Delete a single desired Property</a></li>
<li><a href="protocol-examples-modifydesiredproperty.html">Modify a single desired Property</a></li>
<li><a href="protocol-examples-retrievedesiredproperty.html">Retrieve a single desired Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Things merge examples</a>
<ul>
<li><a href="protocol-examples-mergething.html">Merge a Thing</a></li>
<li><a href="protocol-examples-mergepolicyid.html">Merge the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-mergeattributes.html">Merge Attributes</a></li>
<li><a href="protocol-examples-mergeattribute.html">Merge a single Attribute</a></li>
<li><a href="protocol-examples-mergethingdefinition.html">Merge a Definition</a></li>
<li><a href="protocol-examples-mergefeatures.html">Merge Features</a></li>
<li><a href="protocol-examples-mergefeature.html">Merge a single Feature</a></li>
<li><a href="protocol-examples-mergefeaturedefinition.html">Merge Feature Definition</a></li>
<li><a href="protocol-examples-mergeproperties.html">Merge Feature Properties</a></li>
<li><a href="protocol-examples-mergeproperty.html">Merge a single Property</a></li>
<li><a href="protocol-examples-mergedesiredproperties.html">Merge desired Feature Properties</a></li>
<li><a href="protocol-examples-mergedesiredproperty.html">Merge a single desired Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Policies examples</a>
<ul>
<li><a href="protocol-examples-policies-createpolicy.html">Create a Policy</a></li>
<li><a href="protocol-examples-policies-deletepolicy.html">Delete a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicy.html">Modify a Policy</a></li>
<li><a href="protocol-examples-policies-retrievepolicy.html">Retrieve a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicyentries.html">Modify entries</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentries.html">Retrieve entries</a></li>
<li><a href="protocol-examples-policies-createpolicyentry.html">Create a single entry</a></li>
<li><a href="protocol-examples-policies-deletepolicyentry.html">Delete a single entry</a></li>
<li><a href="protocol-examples-policies-modifypolicyentry.html">Modify a single entry</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentry.html">Retrieve a single entry</a></li>
<li><a href="protocol-examples-policies-modifysubjects.html">Modify subjects</a></li>
<li><a href="protocol-examples-policies-retrievesubjects.html">Retrieve subjects</a></li>
<li><a href="protocol-examples-policies-createsubject.html">Create a single subject</a></li>
<li><a href="protocol-examples-policies-deletesubject.html">Delete a single subject</a></li>
<li><a href="protocol-examples-policies-modifysubject.html">Modify a single subject</a></li>
<li><a href="protocol-examples-policies-retrievesubject.html">Retrieve a single subject</a></li>
<li><a href="protocol-examples-policies-modifyresources.html">Modify resources</a></li>
<li><a href="protocol-examples-policies-retrieveresources.html">Retrieve resources</a></li>
<li><a href="protocol-examples-policies-createresource.html">Create a single resource</a></li>
<li><a href="protocol-examples-policies-deleteresource.html">Delete a single resource</a></li>
<li><a href="protocol-examples-policies-modifyresource.html">Modify a single resource</a></li>
<li><a href="protocol-examples-policies-retrieveresource.html">Retrieve a single resource</a></li>
<li><a href="protocol-examples-policies-errorresponses.html">Error responses</a></li>
<li><a href="protocol-examples-policies-announcement-subjectDeletion.html">Announcement for subject deletion</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Connections examples</a>
<ul>
<li><a href="protocol-examples-connections-announcement-opened.html">Announcement for connection opened</a></li>
<li><a href="protocol-examples-connections-announcement-closed.html">Announcement for connection gracefully closed</a></li>
</ul>
</li>
<li><a href="protocol-examples-search.html">→ Search examples</a></li>
</ul>
</li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="presentations.html">Presentations</a></li>
<li><a href="glossary.html">Glossary</a></li>
<li><a href="feedback.html">Feedback</a></li>
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
</ul>
<!-- this highlights the active parent class in the sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");
</script>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<div class="post-header">
<h1 class="post-title-main">Connections</h1>
</div>
<div class="post-content">
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
// Handler for .ready() called.
$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });
/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
var target = $(this.getAttribute('href'))
, scroll_target = target.offset().top
$(window).scrollTop(scroll_target - 10);
return false
})
});
</script>
<div id="toc"></div>
<h2 id="connection-model">Connection model</h2>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> To get started with connections right away, consult the
<a href="connectivity-manage-connections.html">Manage connections</a> page. </div>
<p>You can integrate your Ditto instance with external messaging services such as
<a href="https://eclipse.org/hono/">Eclipse Hono</a>, a <a href="https://www.rabbitmq.com/">RabbitMQ</a> broker or an
<a href="https://kafka.apache.org/">Apache Kafka</a> broker via custom “connections”.</p>
<p>Additionally, you may invoke foreign HTTP endpoints by using the
<a href="connectivity-protocol-bindings-http.html">HTTP connection type</a>.</p>
<p>A connection represents a communication channel for the exchange of messages between any service and Ditto.
It requires a transport protocol, which is used to transmit <a href="protocol-overview.html">Ditto Protocol</a> messages.
Ditto supports one-way and two-way communication over connections. This enables consumer/producer scenarios
as well as fully-fledged command and response use cases. Nevertheless, those options might be limited by
the transport protocol or the other endpoint’s capabilities.</p>
<p>All connections are configured and supervised via Ditto’s
<a href="architecture-services-connectivity.html">Connectivity service</a>. The following model defines the connection itself:</p>
<script src="docson/widget.js" data-schema="../jsonschema/connection.json"></script>
<h3 id="connection-types">Connection types</h3>
<p>The top design priority of this model is to be as generic as possible, while still allowing protocol specific
customizations and tweaks. This enables the implementations of different customizable connection types, and support
for custom payload formats. Currently, the following connection types are supported:</p>
<ul>
<li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1</a></li>
<li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0</a></li>
<li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1</a></li>
<li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5</a></li>
<li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1</a></li>
<li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x</a></li>
</ul>
<p>The <code class="highlighter-rouge">sources</code> and <code class="highlighter-rouge">targets</code> address formats depends on the <code class="highlighter-rouge">connectionType</code> and has therefore <code class="highlighter-rouge">connectionType</code>
specific limitations. Those are documented with the corresponding protocol bindings.</p>
<h3 id="sources">Sources</h3>
<p>Sources are used to connect to message brokers / external systems in order to consume messages <strong>from them</strong>.</p>
<p>Source messages can be of the following type:</p>
<ul>
<li><a href="basic-signals-command.html">commands</a></li>
<li><a href="basic-messages.html">messages</a></li>
<li><a href="protocol-twinlive.html">live commands/responses/events</a></li>
<li><a href="protocol-specification-acks.html">acknowledgements</a></li>
</ul>
<p>Sources contain:</p>
<ul>
<li>several addresses (depending on the <a href="#connection-types">connection type</a> those are interpreted differently,
e.g. as queues, topics, etc.),</li>
<li>a consumer count defining how many consumers should be attached to each source address,</li>
<li>an authorization context (see <a href="#authorization">authorization</a>) specifying which
<a href="basic-policy.html#subjects">authorization subject</a> is used to authorize messages from the source,</li>
<li>enforcement information that allows filtering the messages that are consumed in this source,</li>
<li><a href="basic-acknowledgements.html#requesting-acks">acknowledgement requests</a> this source requires in order
to ensure QoS 1 (“at least once”) processing of consumed messages before technically acknowledging them to the channel,</li>
<li>declared labels of <a href="protocol-specification-acks.html">acknowledgements</a> the source is allowed to send,</li>
<li><a href="connectivity-header-mapping.html">header mapping</a> for mapping headers of source messages to internal headers, and</li>
<li>a reply-target to configure publication of any responses of incoming commands.</li>
</ul>
<h4 id="source-enforcement">Source enforcement</h4>
<p>Messages received from external systems are mapped to Ditto internal format, either by applying some custom mapping or
the default mapping for <a href="protocol-overview.html">Ditto Protocol</a> messages.</p>
<p>During this mapping the digital twin of the device is determined i.e.
which thing is accessed or modified as a result of the message. By default, no sanity check is done if this target
thing corresponds to the device that originally sent the message. In some use cases this might be valid, but
in other scenarios you might want to enforce that a device only sends data to its digital twin.
Note that this could also be achieved by assigning a specific policy to each device and use <a href="#placeholders">placeholders</a>
in the authorization subject, but this can get cumbersome to maintain for a large number of devices.</p>
<p>With an enforcement, you can use a single policy for all devices
and still make sure that a device only modifies its associated digital twin. Enforcement is only feasible if the message
contains the verified identity of the sending device (e.g. in a message header). This verification has to be done by the
external system e.g. by properly authenticating the devices and providing the identity in the messages sent to Ditto.</p>
<p>The enforcement configuration consists of two fields:</p>
<ul>
<li><code class="highlighter-rouge">input</code>: Defines where device identity is extracted.</li>
<li><code class="highlighter-rouge">filters</code>: Defines the filters that are matched against the input. At least one filter must match the input value,
otherwise the message is rejected.</li>
</ul>
<p>The following placeholders are available for the <code class="highlighter-rouge">input</code> field:</p>
<table>
<thead>
<tr>
<th>Placeholder</th>
<th>Description</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">{{ header:&lt;name&gt; }}</code></td>
<td>Any header from the message received via the source (case-insensitive).</td>
<td><code class="highlighter-rouge">{{header:device_id }}</code></td>
</tr>
<tr>
<td><code class="highlighter-rouge">{{ source:address }}</code></td>
<td>The address on which the message was received.</td>
<td>devices/sensors/temperature1</td>
</tr>
</tbody>
</table>
<p>The following placeholders are available for the <code class="highlighter-rouge">filters</code> field:</p>
<table>
<thead>
<tr>
<th>Placeholder</th>
<th>Description</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">{{ thing:id }}</code></td>
<td>Full ID composed of ‘‘namespace’’ + ‘’:’’ as a separator + ‘‘name’’</td>
<td>eclipse.ditto:thing-42</td>
</tr>
<tr>
<td><code class="highlighter-rouge">{{ thing:namespace }}</code></td>
<td>Namespace (i.e. first part of an ID)</td>
<td>eclipse.ditto</td>
</tr>
<tr>
<td><code class="highlighter-rouge">{{ thing:name }}</code></td>
<td>Name (i.e. second part of an ID )</td>
<td>thing-42</td>
</tr>
</tbody>
</table>
<p>Assuming a device <code class="highlighter-rouge">sensor:temperature1</code> pushes its telemetry data to Ditto which is stored in a thing named
<code class="highlighter-rouge">sensor:temperature1</code>. The device identity is provided in a header field <code class="highlighter-rouge">device_id</code>. To enforce that the device can
only send data to the Thing <code class="highlighter-rouge">sensor:temperature1</code> the following enforcement configuration can be used:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"telemetry/hono_tenant"</span><span class="w"> </span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"enforcement"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"input"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:device_id }}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"filters"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"{{ thing:id }}"</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>Note: This example assumes that there is a valid user named <code class="highlighter-rouge">ditto:inbound-auth-subject</code> in Ditto.
If you want to use a user for the basic auth (from the <a href="connectivity-protocol-bindings-http.html">HTTP API</a>) use
the prefix <code class="highlighter-rouge">nginx:</code>, e.g. <code class="highlighter-rouge">nginx:ditto</code>.
See <a href="basic-auth.html#authorization-context-in-devops-commands">Basic Authentication</a> for more information.</p>
<h4 id="source-acknowledgement-requests">Source acknowledgement requests</h4>
<p>A source can configure, that for each incoming message additional
<a href="basic-acknowledgements.html#requesting-acks">acknowledgement requests</a> are added.</p>
<p>That is desirable whenever incoming messages should be processed with a higher “quality of service” than the default,
which is “at most once” (or QoS 0).</p>
<p>In order to process messages from sources with an “at least once” (or QoS 1) semantic, configure the source’s
<code class="highlighter-rouge">"acknowledgementRequests/includes"</code> to add the
<a href="basic-acknowledgements.html#built-in-acknowledgement-labels">“twin-persisted”</a> acknowledgement request, which will
cause that a consumed message over this source will technically be acknowledged, it the twin was
successfully updated/persisted by Ditto.</p>
<p>How the technical acknowledgment is done is specific for the used <a href="#connection-types">connection type</a> and documented
in scope of that connection type.</p>
<p>In addition to the <code class="highlighter-rouge">"includes"</code> defining which acknowledgements to request for each incoming message, the optional
<code class="highlighter-rouge">"filter"</code> holds an <a href="basic-placeholders.html#function-library">fn:filter()</a> function defining when to request
acknowledgements at all for an incoming message. This filter is applied on both acknowledgements: those
<a href="basic-acknowledgements.html#requesting-acks-via-ditto-protocol-message">requested in the message</a> and the ones requested
via the configured <code class="highlighter-rouge">"includes"</code> array.</p>
<p>The JSON for a source with acknowledgement requests could look like this. The <code class="highlighter-rouge">"filter"</code> in the example causes that
acknowledgements are only requested if the “qos” header was either not present or does not equal <code class="highlighter-rouge">0</code>:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"&lt;source&gt;"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"qos"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:qos }}"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"acknowledgementRequests"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"includes"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"twin-persisted"</span><span class="p">,</span><span class="w">
</span><span class="s2">"receiver-connection-id:my-custom-ack"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"filter"</span><span class="p">:</span><span class="w"> </span><span class="s2">"fn:filter(header:qos,'ne','0')"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h4 id="source-declared-acknowledgement-labels">Source declared acknowledgement labels</h4>
<p>The acknowledgements sent via a source must have their labels declared in the field <code class="highlighter-rouge">declardAcks</code> as a JSON array.<br />
If the label of an acknowledgement is not in the <code class="highlighter-rouge">declaredAcks</code> array, then the acknowledgement is rejected with
an error. The declared labels must be prefixed by the connection ID followed by a colon or the
<code class="highlighter-rouge">{{connection:id}}</code> placeholder followed by a colon. For example:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"&lt;source&gt;"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"declaredAcks"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"{{connection:id}}:my-custom-ack"</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h4 id="source-header-mapping">Source header mapping</h4>
<p>For incoming messages, an optional <a href="connectivity-header-mapping.html">header mapping</a> may be applied.
Mapped headers are added to the headers of the Ditto protocol message obtained by payload mapping.
The default <a href="connectivity-mapping.html#ditto-mapper">Ditto payload mapper</a> does not retain any external header;
in this case all Ditto protocol headers come from the header mapping.</p>
<p>The JSON for a source with header mapping could look like this:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"&lt;source&gt;"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"correlation-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:message-id }}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"content-type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:content-type }}"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h4 id="source-reply-target">Source reply target</h4>
<p>A source may define a reply target to publish the responses of incoming commands.
For a reply target, the address and header mapping are defined in itself, whereas its payload mapping is inherited
from the parent source, because a payload mapping definition specifies the transformation for both: incoming and outgoing
messages.</p>
<p>For example, to publish responses at the target address equal to the <code class="highlighter-rouge">reply-to</code> header of incoming commands,
define source header mapping and reply target as follows. If an incoming command does not have the <code class="highlighter-rouge">reply-to</code> header,
then its response is dropped.</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"reply-to"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:reply-to }}"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"replyTarget"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:reply-to }}"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>The reply target may contain its own header mapping (<code class="highlighter-rouge">"headerMapping"</code>) in order to map response headers.</p>
<p>In addition, the reply target contains the expected response types (<code class="highlighter-rouge">"expectedResponseTypes"</code>) which should be
published to the reply target.<br />
The following reply targets are available to choose from:</p>
<ul>
<li><strong>response</strong>: Send back successful responses (e.g. responses after a Thing was successfully modified,
but also responses for <a href="basic-signals-command.html#query-commands">query commands</a>).
Includes positive <a href="protocol-specification-acks.html#acknowledgements-aggregating">acknowledgements</a>.</li>
<li><strong>error</strong>: Send back error responses (e.g. thing not modifiable due to lacking permissions)</li>
<li><strong>nack</strong>: If negative <a href="protocol-specification-acks.html#acknowledgements-aggregating">acknowledgement</a> responses should be delivered.</li>
</ul>
<p>This is an example <code class="highlighter-rouge">"replyTarget"</code> containing both header mapping and expected response types:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"replyTarget"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:reply-to }}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"correlation-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:correlation-id }}"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"expectedResponseTypes"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"response"</span><span class="p">,</span><span class="w">
</span><span class="s2">"error"</span><span class="p">,</span><span class="w">
</span><span class="s2">"nack"</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h3 id="targets">Targets</h3>
<p>Targets are used to connect to messages brokers / external systems in order to publish messages <strong>to them</strong>.</p>
<p>Target messages can be of the following type:</p>
<ul>
<li><a href="basic-messages.html">Thing messages</a></li>
<li><a href="basic-signals-event.html">Thing events</a></li>
<li><a href="protocol-twinlive.html">Thing live commands/responses/events</a></li>
<li><a href="protocol-specification-policies-announcement.html">Policy announcements</a></li>
<li><a href="protocol-specification-connections-announcement.html">Connection announcements</a></li>
</ul>
<p>Targets contain:</p>
<ul>
<li>one address (that is interpreted differently depending on the <a href="#connection-types">connection type</a>, e.g. as queue, topic, etc.),</li>
<li><a href="#target-topics-and-filtering">topics</a> that will be sent to the target,</li>
<li>an authorization context (see <a href="#authorization">authorization</a>) specifying which
<a href="basic-policy.html#subjects">authorization subject</a> is used to authorize messages to the target, and</li>
<li><a href="connectivity-header-mapping.html">header mapping</a> to compute external headers from Ditto protocol headers.</li>
</ul>
<h4 id="target-topics-and-filtering">Target topics and filtering</h4>
<p>Which types of messages should be published to the target address, can be defined via configuration.</p>
<p>In order to only consume specific events like described in <a href="basic-changenotifications.html">change notifications</a>, the
following parameters can additionally be provided when specifying the <code class="highlighter-rouge">topics</code> of a target:</p>
<table>
<thead>
<tr>
<th>Description</th>
<th>Topic</th>
<th><a href="basic-changenotifications.html#by-namespaces">Filter by namespaces</a></th>
<th><a href="basic-changenotifications.html#by-rql-expression">Filter by RQL expression</a></th>
</tr>
</thead>
<tbody>
<tr>
<td>Subscribe for <a href="basic-changenotifications.html">Thing events/change notifications</a></td>
<td><code class="highlighter-rouge">_/_/things/twin/events</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="basic-messages.html">Thing messages</a></td>
<td><code class="highlighter-rouge">_/_/things/live/messages</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">Thing live commands</a></td>
<td><code class="highlighter-rouge">_/_/things/live/commands</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">Thing live events</a></td>
<td><code class="highlighter-rouge">_/_/things/live/events</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-specification-policies-announcement.html">Policy announcements</a></td>
<td><code class="highlighter-rouge">_/_/policies/announcements</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-specification-connections-announcement.html">Connection announcements</a></td>
<td><code class="highlighter-rouge">_/_/connections/announcements</code></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>The parameters are specified similar to HTTP query parameters, the first one separated with a <code class="highlighter-rouge">?</code> and all following ones
with <code class="highlighter-rouge">&amp;</code>. You need to URL-encode the filter values before using them in a configuration.</p>
<p>For example, this way the connection session would register for all events in the namespace <code class="highlighter-rouge">org.eclipse.ditto</code> and which
would match an attribute “counter” to be greater than 42. Additionally, it would subscribe to messages in the namespace
<code class="highlighter-rouge">org.eclipse.ditto</code>:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;target-address&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"_/_/things/twin/events?namespaces=org.eclipse.ditto&amp;filter=gt(attributes/counter,42)"</span><span class="p">,</span><span class="w">
</span><span class="s2">"_/_/things/twin/events?extraFields=attributes/placement&amp;filter=gt(attributes/placement,'Kitchen')"</span><span class="p">,</span><span class="w">
</span><span class="s2">"_/_/things/live/messages?namespaces=org.eclipse.ditto"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:outbound-auth-subject"</span><span class="p">,</span><span class="w"> </span><span class="s2">"..."</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h4 id="target-topics-and-enrichment">Target topics and enrichment</h4>
<p>When extra fields should be added to outgoing messages on a connection, an <code class="highlighter-rouge">extraFields</code> parameter can be added
to the topic. This is supported for all topics:</p>
<table>
<thead>
<tr>
<th>Description</th>
<th>Topic</th>
<th><a href="basic-enrichment.html">Enrich by extra fields</a></th>
</tr>
</thead>
<tbody>
<tr>
<td>Subscribe for <a href="basic-changenotifications.html">Thing events/change notifications</a></td>
<td><code class="highlighter-rouge">_/_/things/twin/events</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="basic-messages.html">Thing messages</a></td>
<td><code class="highlighter-rouge">_/_/things/live/messages</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">Thing live commands</a></td>
<td><code class="highlighter-rouge">_/_/things/live/commands</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">Thing live events</a></td>
<td><code class="highlighter-rouge">_/_/things/live/events</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-specification-policies-announcement.html">Policy announcements</a></td>
<td><code class="highlighter-rouge">_/_/policies/announcements</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-specification-connections-announcement.html">Connection announcements</a></td>
<td><code class="highlighter-rouge">_/_/connections/announcements</code></td>
<td></td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;target-address&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"_/_/things/twin/events?extraFields=attributes/placement"</span><span class="p">,</span><span class="w">
</span><span class="s2">"_/_/things/live/messages?extraFields=features/ConnectionStatus"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:outbound-auth-subject"</span><span class="p">,</span><span class="w"> </span><span class="s2">"..."</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h4 id="target-issued-acknowledgement-label">Target issued acknowledgement label</h4>
<p>A target can be configured to automatically <a href="basic-acknowledgements.html#issuing-acknowledgements">issue acknowledgements</a>
for each published/emitted message, once the underlying channel confirmed
that the message was successfully received.</p>
<p>That is desirable whenever outgoing messages (e.g. <a href="basic-signals-event.html">events</a>) are handled in scope of a command
sent with an “at least once” (QoS 1) semantic in order to only acknowledge that command, if the event was successfully
forwarded into another system.</p>
<p>For more details on that topic, please refer to the <a href="basic-acknowledgements.html">acknowledgements</a> section.</p>
<p>Whether an outgoing message is treated as successfully sent or not is specific for the used
<a href="#connection-types">connection type</a> and documented in scope of that connection type.</p>
<p>The issued acknowledgement label must be prefixed by the connection ID followed by a colon or the
<code class="highlighter-rouge">{{connection:id}}</code> placeholder followed by a colon.<br />
The JSON for a target with issued acknowledgement labels could look like this:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;target&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"_/_/things/twin/events"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"issuedAcknowledgementLabel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{connection:id}}:my-custom-ack"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h4 id="target-header-mapping">Target header mapping</h4>
<p>For outgoing messages, an optional <a href="connectivity-header-mapping.html">header mapping</a> may be applied.
Mapped headers are added to the external headers.
The default <a href="connectivity-mapping.html#ditto-mapper">Ditto payload mapper</a> does not define any external header;
in this case, all external headers come from the header mapping.</p>
<p>The JSON for a target with header mapping could like this:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;target&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"_/_/things/twin/events"</span><span class="p">,</span><span class="w">
</span><span class="s2">"_/_/things/live/messages?namespaces=org.eclipse.ditto"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:inbound-auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"headerMapping"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"message-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:correlation-id }}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"content-type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ header:content-type }}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">"{{ topic:subject }}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"reply-to"</span><span class="p">:</span><span class="w"> </span><span class="s2">"all-replies"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h3 id="authorization">Authorization</h3>
<p>A connection is initiated by the connectivity service. This obviates the need for client authorization, because
Ditto becomes the client in this case. Nevertheless, to access resources within Ditto, the connection must know on
whose behalf it is acting. This is controlled via the configured <code class="highlighter-rouge">authorizationContext</code>, which holds a list of
self-assigned authorization subjects. Before a connection can access a Ditto resource, one of its
<code class="highlighter-rouge">authorizationSubject</code>s must be granted the access rights by the authorization mechanism of a
<a href="basic-policy.html">Policies</a>.</p>
<p>A connection target can only send data for things to which it has READ rights, as data flows from a thing to a target.
A connection source can only receive data for things to which it has WRITE rights, as data flows from a source to a thing.</p>
<h3 id="specific-configuration">Specific configuration</h3>
<p>Some <a href="#connection-types">connection types</a> require specific configuration, which is not supported for other connection types.
Those are put into the <code class="highlighter-rouge">specificConfig</code> field.</p>
<h3 id="payload-mapping">Payload Mapping</h3>
<p>For more information on mapping message payloads see the corresponding <a href="connectivity-mapping.html">Payload Mapping Documentation</a>.</p>
<h2 id="placeholders">Placeholders</h2>
<p>The configuration of a connection allows to use placeholders at certain places. This allows more fine-grained control
over how messages are consumed or where they are published to. The general syntax of a placeholder is
<code class="highlighter-rouge">{{ placeholder }}</code>. Have a look at the <a href="basic-placeholders.html">placeholders concept</a> for
more details on that.</p>
<h3 id="placeholder-for-source-authorization-subjects">Placeholder for source authorization subjects</h3>
<p>Processing the messages received via a source using the <em>same fixed authorization subject</em> may not be
suitable for every scenario. For example, if you want to declare fine-grained write permissions per device, this would
not be possible with a fixed global subject. For this use case, we have introduced placeholder substitution for
authorization subjects of source addresses that are resolved when processing messages from a source.
Of course, this requires the sender of the
message to provide necessary information about the original issuer of the message.</p>
<div class="alert alert-warning" role="alert" style=""><i class="fa fa-warning"></i> <b>Important:</b> Only use this kind of placeholder if you trust the source of the message. The value from the header is used as the <strong>authorized subject</strong>.</div>
<p>You can access any header value of the incoming message by using a placeholder like <code class="highlighter-rouge">{{ header:name }}</code>.</p>
<p>Example:</p>
<p>Assuming the messages received from the source <em>telemetry</em> contain a <code class="highlighter-rouge">device_id</code> header (e.g. <em>sensor-123</em>),
you may configure your source’s authorization subject as follows:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth-subject-placeholder-example"</span><span class="p">,</span><span class="w">
</span><span class="s2">"sources"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"telemetry"</span><span class="w"> </span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"device:{{ header:device_id }}"</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>The placeholder is then replaced by the value from the message headers and the message is forwarded and processed under
the subject <em>device:sensor-123</em>.
In case the header cannot be resolved or the header contains unexpected characters, an exception is thrown, which is sent
back to the sender as an error message, if a valid <em>reply-to</em> header was provided, otherwise the message is dropped.</p>
<h3 id="placeholder-for-target-addresses">Placeholder for target addresses</h3>
<p>Another use case for placeholders may be to publish twin events or live commands and events to a target address
containing thing-specific information e.g. you can distribute things from different namespaces to different target addresses.
You can use the placeholders <code class="highlighter-rouge">{{ thing:id }}</code>, <code class="highlighter-rouge">{{ thing:namespace }}</code>
and <code class="highlighter-rouge">{{ thing:name }}</code> in the target address for this purpose.
For a thing with the ID <em>org.eclipse.ditto:device-123</em> these placeholders would be resolved as follows:</p>
<table>
<thead>
<tr>
<th>Placeholder</th>
<th>Description</th>
<th>Resolved value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">thing:id</code></td>
<td>Full ID composed of <em>namespace</em> <code class="highlighter-rouge">:</code> (as a separator), and <em>name</em></td>
<td><em>org.eclipse.ditto:device-123</em></td>
</tr>
<tr>
<td><code class="highlighter-rouge">thing:namespace</code></td>
<td>Namespace (i.e. first part of an ID)</td>
<td><em>org.eclipse.ditto</em></td>
</tr>
<tr>
<td><code class="highlighter-rouge">thing:name</code></td>
<td>Name (i.e. second part of an ID )</td>
<td><em>device-123</em></td>
</tr>
</tbody>
</table>
<p>Additionally to the placeholders mentioned above, all documented
<a href="basic-placeholders.html#scope-connections">connection placeholders</a> may be
used in target addresses. However, if any placeholder in the target address fails to resolve, then the message will be
dropped.</p>
<p>Example:</p>
<p>Sending live commands and events to a target address that contains the thing’s namespace.</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"target-placeholder-example"</span><span class="p">,</span><span class="w">
</span><span class="s2">"targets"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"addresses"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"live/{{ thing:namespace }}"</span><span class="w"> </span><span class="p">],</span><span class="w">
</span><span class="s2">"authorizationContext"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"ditto:auth-subject"</span><span class="p">],</span><span class="w">
</span><span class="s2">"topics"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"_/_/things/live/events"</span><span class="p">,</span><span class="w"> </span><span class="s2">"_/_/things/live/commands"</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h2 id="ssh-tunneling">SSH tunneling</h2>
<p>Ditto supports tunneling a connection by establishing an SSH tunnel and using it to connect to the actual endpoint.</p>
<p>See <a href="connectivity-ssh-tunneling.html">SSH tunneling</a> on how to setup and configure SSH tunneling with Ditto.</p>
<div class="tags">
<b>Tags: </b>
<a href="tag_connectivity.html" class="btn btn-default navbar-btn cursorNorm" role="button">connectivity</a>
</div>
</div>
<hr class="shaded"/>
<footer>
<div class="row">
<div class="col-lg-12 footer">
<div class="logo">
<a href="https://eclipse.org"><img src="images/eclipse_foundation_logo.svg" alt="Eclipse logo"/></a>
</div>
<p class="notice">
&copy;2021 Eclipse Ditto™.
Site last generated: Jul 23, 2021 <br />
</p>
<div class="quickLinks">
<a href="https://www.eclipse.org/legal/privacy.php" target="_blank">
&gt; Privacy Policy
</a>
<a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank">
&gt; Terms of Use
</a>
<a href="https://www.eclipse.org/legal/copyright.php" target="_blank">
&gt; Copyright Agent
</a>
<a href="https://www.eclipse.org/legal" target="_blank">
&gt; Legal
</a>
<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">
&gt; License
</a>
<a href="https://eclipse.org/security" target="_blank">
&gt; Report a Vulnerability
</a>
</div>
</div>
</div>
</footer>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- /#main -->
</div>
</body>
</html>