From a1701ac73c6a38fc0eda3cf7bb2d52c470523d6c Mon Sep 17 00:00:00 2001
From: David Schwilk <david.schwilk@bosch.io>
Date: Mon, 24 Aug 2020 08:36:14 +0200
Subject: [PATCH] Issue #760 Add ImplicitThingCreation mapper and
 mapping-conditions to documentation

Signed-off-by: David Schwilk <david.schwilk@bosch.io>
---
 .../pages/ditto/connectivity-mapping.md       | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/documentation/src/main/resources/pages/ditto/connectivity-mapping.md b/documentation/src/main/resources/pages/ditto/connectivity-mapping.md
index 925983c552..a9eedc2477 100644
--- a/documentation/src/main/resources/pages/ditto/connectivity-mapping.md
+++ b/documentation/src/main/resources/pages/ditto/connectivity-mapping.md
@@ -64,6 +64,7 @@ The following message mappers are included in the Ditto codebase:
 | [JavaScript](#javascript-mapper) | Converts arbitrary messages from and to the [Ditto Protocol](protocol-overview.html) format using **custom** JavaScript code executed by Ditto. | ✓ | ✓ |
 | [Normalized](#normalized-mapper) | Transforms the payload of events to a normalized view. |  | ✓ |
 | [ConnectionStatus](#connectionstatus-mapper) | This mapper handles messages containing `creation-time` and `ttd` headers by updating a feature of the targeted thing with [definition](basic-feature.html#feature-definition) [ConnectionStatus](https://vorto.eclipse.org/#/details/org.eclipse.ditto:ConnectionStatus:1.0.0). | ✓ |  |
+| [ImplicitThingCreation](#implicitthingcreation-mapper) | This mapper handles messages for which a Thing should be created automatically based on a defined template| ✓ |  |
 
 ### Ditto mapper
 
@@ -172,6 +173,30 @@ Example of a resulting `ConnectionStatus` feature:
  fixed value or resolved from a message header (e.g. `{%raw%}{{ header:feature_id }}{%endraw%}`).
 
 
+### ImplicitThingCreation Mapper
+This mapper implicitly creates a new thing for an incoming message. 
+ 
+The created thing contains the values defined in the template, configured in the `mappingDefinitions` `options`.<br/>
+ 
+#### Configuration options
+
+* `thing` (required): The values of the thing that is created implicitly. It can either contain fixed values
+ or header placeholders (e.g. `{%raw%}{{ header:device_id }}{%endraw%}`).
+ 
+ Example of a template defined in  `options`:
+ ```json
+ {
+   "thing": {
+   "thingId": "{{header:device_id}}",
+   "policyId": "{{header:entity.id}}",
+   "attributes": {
+     "CreatedBy": "ImplicitThingCreation"
+   }
+  }
+ }
+ ```
+
+
 
 ## Example connection with multiple mappers
 
@@ -206,6 +231,39 @@ The following example connection defines a `ConnectionStatus` mapping with the I
 
 
 
+## Example connection with mapping conditions
+
+The following example connection defines `conditions` for the ConnectionStatus mapping engine.<br/>
+ Optional conditions are validated before the mapping.<br/> 
+ Conditional Mapping can be achieved by using [function expressions](basic-placeholder.html#function-expressions).
+ When multiple conditions are defined for one `mappingEngine`, all have to equal true for the mapping to be executed.  
+
+```json
+{ 
+  ...  
+  "name": "exampleConnection",
+  "sources": [{
+      "addresses": ["<source>"],
+      "authorizationContext": ["ditto:inbound"],
+      "payloadMapping": ["status"]
+    }
+  ],
+  "mappingDefinitions": {
+    "status": {
+      "mappingEngine": "ConnectionStatus",
+      "conditions": [
+      "fn:filter(header:mapping-required,'eq','true')"
+      ],
+      "options": {
+        "thingId": "{%raw%}{{ header:device_id }}{%endraw%}"
+      }
+    }
+  }
+}
+```
+
+
+
 ## JavaScript mapping engine
 
 Ditto utilizes the [Rhino](https://github.com/mozilla/rhino) JavaScript engine for Java for evaluating the JavaScript