add edgex sink docs

docs/en_US/edgex/edgex_rule_engine_tutorial.md

@@ -45,7 +45,7 @@ EdgeX uses [message bus](https://github.com/edgexfoundry/go-mod-messaging) to ex
 It's **STRONGLY** recommended to use Docker, since related dependency libraries (such ZeroMQ lib) are already installed in Docker images.
 
 ```shell
-docker pull emqx/kuiper:0.2.1
+docker pull emqx/kuiper:0.3
 ```
 
 <u>TODO: After offcially releasing of EdgeX Geneva, the Kuiper docker image will be pulled automatically by EdgeX docker composer files. The command will be updated by then.</u>  
@@ -53,7 +53,7 @@ docker pull emqx/kuiper:0.2.1
 **Run Docker**
 
 ```
-docker run -d --name kuiper emqx/kuiper:0.2.1
+docker run -d --name kuiper emqx/kuiper:0.3
 ```
 
 If the docker instance is failed to start, please use ``docker logs kuiper`` to see the log files.
@@ -61,7 +61,7 @@ If the docker instance is failed to start, please use ``docker logs kuiper`` to
 Notice 1: The default EdgeX message bus configuration could be updated when bring-up the Docker instance.  As listed in below, override the default configurations for message bus server, port and service server address for getting value descriptors in Kuiper instance.
 
 ```shell
-docker run -d --name kuiper -e EDGEX_SERVER=10.211.55.2 -e EDGEX_PORT=5563 -e EDGEX_SERVICE_SERVER=http://10.211.55.2:48080 emqx/kuiper:0.2.1
+docker run -d --name kuiper -e EDGEX_SERVER=10.211.55.2 -e EDGEX_PORT=5563 -e EDGEX_SERVICE_SERVER=http://10.211.55.2:48080 emqx/kuiper:0.3
 ```
 
 For more detailed supported Docer environment varialbles, please refer to [this link](https://hub.docker.com/r/emqx/kuiper).

docs/en_US/rules/sinks/edgex.md

@@ -7,19 +7,117 @@ The action is used for publish output message into EdgeX message bus.
 | protocol      | true     | If it's not specified, then use default value ``tcp``.       |
 | host          | true     | The host of message bus. If not specified, then use default value ``*``. |
 | port          | true     | The port of message bus. If not specified, then use default value ``5563``. |
-| topic         | false    | The topic to be published. The property must be specified.   |
+| topic         | true     | The topic to be published. If not specified, then use default value ``events``. |
 | contentType   | true     | The content type of message to be published. If not specified, then use the default value ``application/json``. |
+| metadata      | true     | The property is a field name that allows user to specify a field name of SQL  select clause,  the field name should use ``meta(*) AS xxx``  to select all of EdgeX metadata from message. |
+| deviceName    | true     | Allows user to specify the device name in the event structure that are sent from Kuiper. |
+
+## Examples
+
+### Publish result to EdgeX message bus without keeping original metadata
+In this case, the original metadata value (such as ``id, pushed, created, modified, origin`` in ``Events`` structure, and ``id, created, modified, origin, pushed, device`` in ``Reading`` structure will not be kept). Kuiper acts as another EdgeX micro service here, and it has own ``device name``. A ``deviceName`` property is provided, and allows user to specify the device name of Kuiper. Below is one example,
+
+1) Data received from EdgeX message bus ``events`` topic,
+```
+{
+  "Device": "demo", "Created": 000, …
+  "readings": 
+  [
+     {"Name": "Temperature", value: "30", "Created":123 …},
+     {"Name": "Humidity", value: "20", "Created":456 …}
+  ]
+}
+```
+2) Use following rule,  and specify ``deviceName`` with ``kuiper`` in ``edgex`` action.
 
-Below is sample configuration for publish result message to ``applicaton`` topic of EdgeX Message Bus.
 ```json
-	{
+{
+  "id": "rule1",
+  "sql": "SELECT temperature * 3 AS t1, humidity FROM events",
+  "actions": [
+    {
       "edgex": {
         "protocol": "tcp",
         "host": "*",
-        "port": 5563,
+        "port": 5571,
         "topic": "application",
+        "deviceName": "kuiper",
         "contentType": "application/json"
       }
-  }
+    }
+  ]
+}
+```
+3) The data sent to EdgeX message bus.
+```
+{
+  "Device": "kuiper", "Created": 1000, …
+  "readings": 
+  [
+     {"Name": "t1", value: "90" , "Created": 1000 …},
+     {"Name": "humidity", value: "20" , "Created": 1000 …}
+  ]
+}
+```
+Please notice that, 
+- The device name is changed to ``kuiper``
+- All of metadata for ``Events and Readings`` structure will be updated with new value. ``Created`` field is updated to another value generated by Kuiper (here is ``1000``).
+
+### Publish result to EdgeX message bus with keeping original metadata
+But for some scenarios, you may want to keep some of original metadata. Such as keep the device name as original value that published to Kuiper (``demo`` in the sample), and also other metadata of readings arrays. In such case, Kuiper is acting as a filter - to filter NOT concerned messages, but still keep original data.
+
+Below is an example,
+
+1) Data received from EdgeX message bus ``events`` topic,
+```
+{
+  "Device": "demo", "Created": 000, …
+  "readings": 
+  [
+     {"Name": "Temperature", value: "30", "Created":123 …},
+     {"Name": "Humidity", value: "20", "Created":456 …}
+  ]
+}
 ```
+2) Use following rule,  and specify ``metadata`` with ``edgex_meta``  in ``edgex`` action.
 
+```json
+{
+  "id": "rule1",
+  "sql": "SELECT meta(*) AS edgex_meta, temperature * 3 AS t1, humidity FROM events WHERE temperature > 30",
+  "actions": [
+    {
+      "edgex": {
+        "protocol": "tcp",
+        "host": "*",
+        "port": 5571,
+        "topic": "application",
+        "metadata": "edgex_meta",
+        "contentType": "application/json"
+      }
+    }
+  ]
+}
+```
+Please notice that,
+- User need to add ``meta(*) AS edgex_meta`` in the SQL statement, the ``meta(*)`` returns all of metadata.
+- In ``edgex`` action, value ``edgex_meta``  is specified for ``metadata`` property. This property specifies which field contains metadata of message.
+
+3) The data sent to EdgeX message bus.
+```
+{
+  "Device": "demo", "Created": 000, …
+  "readings": 
+  [
+     {"Name": "t1", value: "90" , "Created": 2000 …},
+     {"Name": "humidity", value: "20", "Created":456 …}
+  ]
+}
+```
+Please notice that,
+- The metadata of ``Events`` structure is still kept, such as ``Device`` & ``Created``.
+- For the reading that can be found in original message, the metadata will be kept. Such as ``humidity`` metadata will be the ``old values`` received from EdgeX message bus.
+- For the reading that can NOT be found in original message,  the metadata will be updated with new value.  Such as metadata of ``t1`` in the sample will fill with default value that generated by Kuiper. 
+- If your SQL has aggregated function, then it does not make sense to keep these metadata, but Kuiper will still fill with metadata from a particular message in the time window. For example, with following SQL, 
+```SELECT avg(temperature) AS temperature, meta(*) AS edgex_meta FROM ... GROUP BY TUMBLINGWINDOW(ss, 10)```. 
+In this case, there are possibly several messages in the window, the metadata value for ``temperature`` will be filled with value from 1st message that received from bus.