document mapToDittoProtocolMsgWrapper and mapFromDittoProtocolMsgWrap…

…per in connectivity-mapping.md;

Signed-off-by: Stefan Maute <stefan.maute@bosch.io>

documentation/src/main/resources/pages/ditto/connectivity-mapping.md

@@ -550,8 +550,32 @@ function mapToDittoProtocolMsg(
 ```
 
 The result of the function has to be a JavaScript object in [Ditto Protocol](protocol-overview.html) or an array of 
-such JavaScript objects. That's where the helper method `Ditto.buildDittoProtocolMsg` is useful: it explicitly 
-defines which parameters are required for the Ditto Protocol message.
+such JavaScript objects. That's where the helper method `Ditto.buildDittoProtocolMsg` is useful: 
+it explicitly defines which parameters are required for the Ditto Protocol message.
+
+There is another JavaScript function which is helpful when you need to access the external message.
+It is possible to use the `mapToDittoProtocolMsgWrapper` in the incoming payload mapping and access the original
+`externalMsg`.
+
+```javascript
+/**
+ * Maps the passed external message to a Ditto Protocol message.
+ * @param {ExternalMessage} externalMsg - The external message to map to a Ditto Protocol message
+ * @returns {(DittoProtocolMessage|Array<DittoProtocolMessage>)} dittoProtocolMessage(s) -
+ *  The mapped Ditto Protocol message,
+ *  an array of Ditto Protocol messages or
+ *  <code>null</code> if the message could/should not be mapped
+ */
+function mapToDittoProtocolMsgWrapper(externalMsg) {
+
+  let headers = externalMsg.headers;
+  let textPayload = externalMsg.textPayload;
+  let bytePayload = externalMsg.bytePayload;
+  let contentType = externalMsg.contentType;
+
+  return mapToDittoProtocolMsg(headers, textPayload, bytePayload, contentType);
+}
+```
 
 ### Mapping outgoing messages
 
@@ -611,10 +635,54 @@ function mapFromDittoProtocolMsg(
 }
 ```
 
-The result of the function has to be a JavaScript object or an array of JavaScript objects with the fields `headers`, 
-`textPayload`, `bytePayload` and `contentType`. That's where the helper method `Ditto.buildExternalMsg` is useful: it
-explicitly defines which parameters are required for the external message.
+The result of the function has to be a JavaScript object or, an array of JavaScript objects with the fields `headers`, 
+`textPayload`, `bytePayload` and `contentType`. That's where the helper method `Ditto.buildExternalMsg` is useful: 
+it explicitly defines which parameters are required for the external message.
+
+There is another JavaScript function which is helpful when you need to access the Ditto protocol message.
+It is possible to use the `mapFromDittoProtocolMsgWrapper` in the outgoing payload mapping and access the
+original `dittoProtocolMsg`.
 
+```javascript
+/**
+ * Maps the passed Ditto Protocol message to an external message.
+ * @param {DittoProtocolMessage} dittoProtocolMsg - The Ditto Protocol message to map
+ * @returns {(ExternalMessage|Array<ExternalMessage>)} externalMessage -
+ *  The mapped external message,
+ *  an array of external messages or
+ *  <code>null</code> if the message could/should not be mapped
+ */
+function mapFromDittoProtocolMsgWrapper(dittoProtocolMsg) {
+
+  let topic = dittoProtocolMsg.topic;
+  let splitTopic = topic.split("/");
+
+  let namespace = splitTopic[0];
+  let name = splitTopic[1];
+  let group = splitTopic[2];
+
+  let channel;
+  let criterion;
+  let action;
+  if (hasChannel(group)) {
+    channel = splitTopic[3];
+    criterion = splitTopic[4];
+    action = splitTopic[5];
+  } else {
+    channel = 'none';
+    criterion = splitTopic[3];
+    action = splitTopic[4];
+  }
+
+  let path = dittoProtocolMsg.path;
+  let dittoHeaders = dittoProtocolMsg.headers;
+  let value = dittoProtocolMsg.value;
+  let status = dittoProtocolMsg.status;
+  let extra = dittoProtocolMsg.extra;
+
+  return mapFromDittoProtocolMsg(namespace, name, group, channel, criterion, action, path, dittoHeaders, value, status, extra);
+}
+```
 
 ## JavaScript payload types
 
@@ -639,7 +707,7 @@ if (contentType === 'application/json') {
 
 ### Byte payloads
 
-Working with byte payloads is also possible but does require a little bit of knowledge about JavaScipt's 
+Working with byte payloads is also possible but does require a little bit of knowledge about JavaScript's 
 [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 
 [TypedArrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) and
 [DataView](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView).
@@ -699,7 +767,7 @@ with that helper.
 ### Text payload example
 
 Let's assume your device sends telemetry data via [Eclipse Hono's](https://www.eclipse.org/hono/) MQTT adapter 
-into the cloud. And that an example payload of your device is:
+into the cloud. And, that an example payload of your device is:
 
 ```json
 {