Merge pull request #305 from Ficodes/feature/supportNGSIv2

feature/support for NGSIv2
telefonicaid · Jan 31, 2019 · 9c6ae19 · 9c6ae19
2 parents 5f4372e + ab40223
commit 9c6ae19
Show file tree

Hide file tree

Showing 19 changed files with 2,346 additions and 62 deletions.
diff --git a/CHANGES_NEXT_RELEASE b/CHANGES_NEXT_RELEASE
@@ -5,8 +5,13 @@
 - Upgrade dev dependency istanbul from ~0.1.34 to ~0.4.5
 - Upgrade dev dependency mocha from 2.4.5 to to 5.2.0
 - Remove: old unused development dependencies
-  * chai
-  * sinon
-  * sinon-chai
   * grunt and grunt related module
   * closure-linter-wrapper
+- Change on the PERSEO_ORION_URL env var behaviour. Now it represents Context Broker base URL instead of the
+  updateContext endpoint
+- Add: new ngsijs ~1.2.0 dependency
+- Add: new rewire ~4.0.1 dev dependency
+- Add: NGSIv2 support in both notification reception and CB update action
+- Upgrade dev dependency chai from ~1.8.0 to ~4.1.2
+- Upgrade dev dependency sinon from ~1.7.3 to ~6.1.0
+- Upgrade dev dependency sinon-chai from 2.4.0 to ~3.2.0
diff --git a/bin/perseo b/bin/perseo
@@ -29,7 +29,8 @@ var app = require('../lib/perseo'),
     logger = require('logops'),
     constants = require('../lib/constants'),
     config = require('../config'),
-    context = {op: 'perseo', comp: constants.COMPONENT_NAME};
+    context = {op: 'perseo', comp: constants.COMPONENT_NAME},
+    URL = require('url').URL;
 
 logger.format = logger.formatters.pipe;
 
@@ -105,7 +106,7 @@ function loadConfiguration() {
         config.nextCore.noticesURL = process.env.PERSEO_NEXT_URL + '/perseo-core/events';
     }
     if (process.env.PERSEO_ORION_URL) {
-        config.orion.URL = process.env.PERSEO_ORION_URL;
+        config.orion.URL = new URL(process.env.PERSEO_ORION_URL);
     }
     if (process.env.PERSEO_LOG_LEVEL) {
         config.logLevel = process.env.PERSEO_LOG_LEVEL;

diff --git a/documentation/configuration.md b/documentation/configuration.md
@@ -60,7 +60,7 @@ In order to have perseo running, there are several basic pieces of information t
 * `config.smpp.password`: Password for the user of the SMPP server
 * `config.smpp.from`: Number from SMS are sending by SMPP server
 * `config.smpp.enabled`: SMPP is default method for SMS instead of use SMS gateway.
-* `config.orion.URL`: URL for updating contexts at Orion (Context Broker).
+* `config.orion.URL`: Context Broker base URL, e.g. https://orion.example.com:1026
 * `config.mongo.URL`: URL for connecting mongoDB.
 * `config.executionsTTL`: Time-To-Live for documents of action executions (seconds).
 * `config.checkDB.delay`:  Number of milliseconds to check DB connection (see [database aspects](admin.md#database-aspects) documentation for mode detail).

diff --git a/documentation/plain_rules.md b/documentation/plain_rules.md
@@ -157,15 +157,16 @@ The `parameters` map includes the following fields:
 
 * id: optional, the id of the entity which attribute is to be updated (by default the id of the entity that triggers the rule is used, i.e. `${id}`)
 * type: optional, the type of the entity which attribute is to be updated (by default the type of the entity that triggers the rule is usedi.e. `${type}`)
-* isPattern: optional, `false` by default
+* version: optional, The NGSI version for the update action. Set this attribute to `2` or `"2"` if you want to use NGSv2 format. `1` by default
+* isPattern: optional, `false` by default. (Only for NGSIv1. If `version` is set to 2, this attribute will be ignored)
 * attributes: *mandatory*, array of target attributes to update. Each element of the array must contain the fields
     * **name**: *mandatory*, attribute name to set
     * **value**: *mandatory*, attribute value to set
     * type: optional, type of the attribute to set. By default, not set (in which case, only the attribute value is changed).
 * actionType: optional, type of CB action: APPEND or UPDATE. By default is APPEND.
 * trust: optional, trust token for getting an access token from Auth Server which can be used to get to a Context Broker behind a PEP.
 
-
+NGSIv1 example:
 ```json
 "action":{
         "type":"update",
@@ -190,6 +191,197 @@ First time an update action using trust token is triggered, Perseo interacts wit
 
 It could happen (in theory) that a just got auth token also produce a 401 Not authorized, however this would be an abnormal situation: Perseo logs the problem with the update but doesn't try to get a new one from Keystone. Next time Perseo triggers the action, the process may repeat, i.e. first update attemp fails with 401, Perseo requests a fresh auth token to Keystone, the second update attemp fails with 401, Perseo logs the problem and doesn't retry again.
 
+NGSIv2 example:
+```json
+"action":{
+        "type":"update",
+        "parameters":{
+            "id":"${id}_mirror",
+            "version": 2,
+            "attributes": [
+                {
+                    "name":"abnormal",
+                    "type":"Number",
+                    "value": 7
+                }
+            ]
+        }
+    }
+```
+
+**Note:** NGSIv2 update actions ignore the trust token for now.
+
+When using NGSIv2 in the update actions, the value field perform [string substitution](#string-substitution-syntax). If `value` is a String, Perseo will parse the value taking into account the `type` field, this only applies to *`Number`*, *`Boolean`* and *`None`* types. 
+
+**Data Types for NGSIv2:**
+
+With `Number` type attributes, Perseo can be able to manage a int/float number or a String to parse in value field.
+- Number from variable:
+```json
+{
+    "name":"numberFromValue",
+    "type": "Number",
+    "value": "${NumberValue}"
+}
+```
+If `NumberValue` value is for example `32.12`, this attribute will take `32.12` as value.
+
+- Literal Number:
+```json
+{
+    "name":"numberLiteral",
+    "type": "Number",
+    "value": 12
+}
+```
+This attribute will take `12` as value.
+
+- Number as String from variable:
+```json
+{
+    "name":"numberFromStringValue",
+    "type": "Number",
+    "value": "${NumberValueAsString}"
+}
+```
+If `NumberValueAsString` value is for example `"4.67"`, this attribute will take `4.67` as value.
+
+- Number as String:
+```json
+{
+    "name":"numberStringLiteral",
+    "type": "Number",
+    "value": "67.8"
+}
+```
+This attribute will take `67.8` as value.
+
+
+
+With `Text` type attributes, Perseo will put the value field parsed as string.
+
+- Text as variable:
+```json
+{
+    "name":"textFromValue",
+    "type": "Text",
+    "value": "${varValue}"
+}
+```
+If `varValue` value is for example `"Good morning"`, this attribute will take `"Good morning"` as value.
+
+If `varValue` value is for example `1234`, this attribute will take `"1234"` as value.
+
+- Literal Text:
+```json
+{
+    "name":"textLiteral",
+    "type": "Text",
+    "value": "Hello world"
+}
+```
+This attribute will take `"Hello world"` as value.
+
+- Literal Number:
+```json
+{
+    "name":"textNumberLiteral",
+    "type": "Text",
+    "value": 67.8
+}
+```
+This attribute will take `"67.8"` as value.
+
+- Literal Boolean:
+```json
+{
+    "name":"textBoolLiteral",
+    "type": "Text",
+    "value": true
+}
+```
+This attribute will take `"true"` as value.
+
+With `DateTime` type attributes, Perseo will try to parse the value to DateTime format.
+
+Date as String:
+```json
+{
+    "name":"dateString",
+    "type": "DateTime",
+    "value": "2018-12-05T11:31:39.00Z"
+}
+```
+This attribute will take `"2018-12-05T11:31:39.000Z"` as value.
+
+Date as Number in milliseconds:
+```json
+{
+    "name":"dateString",
+    "type": "DateTime",
+    "value": 1548843229832
+}
+```
+This attribute will take `"2019-01-30T10:13:49.832Z"` as value.
+
+Date from variable.
+```json
+{
+    "name":"dateString",
+    "type": "DateTime",
+    "value": "${dateVar}"
+}
+```
+If `dateVar` value is for example `1548843229832` (as Number or String), this attribute will take `"2019-01-30T10:13:49.832Z"` as value.
+
+You can use the `__ts` field of a Perseo DateTime attribute to fill a DateTime attribute value without using any `cast()`. For example, if the var are defined as follow in the rule text, `ev.timestamp__ts? as dateVar`, `dateVar` will be a String with the Date in milliseconds, for example `"1548843060657"` and Perseo will parse this String with to a valid DateTime as `2019-01-30T10:11:00.657Z`.
+
+With `None` type attributes, Perseo will set the value to `null` in all cases.
+
+None Attribute:
+```json
+{
+    "name":"nullAttribute",
+    "type": "None",
+    "value": "It does not matter what you put here"
+}
+```
+This attribute will take `null` as value.
+
+```json
+{
+    "name":"nullAttribute2",
+    "type": "None",
+    "value": null
+}
+```
+This attribute will take `null` as value.
+
+
+**Complete example using NGSv2 update action in a rule:**
+
+```json
+{
+   "name":"blood_rule_update",
+   "text":"select *,\"blood_rule_update\" as ruleName, *, ev.BloodPressure? as Pressure from pattern [every ev=iotEvent(BloodPressure? > 1.5 and type=\"BloodMeter\")]",
+   "action":{
+      "type":"update",
+      "parameters":{
+         "id":"${id}_example",
+         "version": 2,
+         "attributes": [
+             {
+                 "name":"pressure",
+                 "type":"Number",
+                 "value": "${Pressure}"
+             }
+         ]
+      }
+   }
+}
+```
+
+Note that using NGSIv2 the BloodPressure attribute is a Number and therefore it is not necessary to use `cast()`.
 
 ### HTTP request action
 Makes an HTTP request to an URL specified in `url` inside `parameters`, sending a body built from `template`.