iotagent-node-lib 4.9.0 → 4.11.0

package/doc/devel/northboundinteractions.md

@@ -346,6 +346,9 @@ queries (and thus P2 and R2 payloads).
 
 ![General ](./img/scenario3.png 'Scenario 3: commands')
 
+**FIXME:** this scenario describes the registration-based commanding mechanism, which is currently deprecated. It should
+be reworked
+
 This scenario requires that the attributes that are going to be requested are marked as provided by the IoT Agent,
 through a registration process (NGSIv9). Examples of this registration process will be provided in the practical section
 of this document. It's worth mentioning that Orion Context Broker **will not** store locally any data about attributes
@@ -729,55 +732,62 @@ error, that error must follow the NGSI payloads described in the Scenario 1 erro
 
 ### Scenario 3: commands (happy path)
 
-#### Context Provider Registration
+The interactions depend on the command mode (`cmdMode`):
+
+-   `legacy`
+-   `notification`
+-   `advancedNotification`
+
+The way of setting up Context Broker to IotAgent communication and the interaction between Context Broker and IoTAgent
+when the command is executed depends on the mode (thus specific subsections about it are provided next for the three
+modes). However, the way in which the command result is provided is the same to all modes (so it is described in a
+[common section](#result-reporting)).
 
-Scenario 3 relies on the Context Provider mechanism of the Context Broker. For this scenario to work, the IoTAgent must
+#### `legacy` mode
+
+##### Set up Context Broker to IotAgent comunication mechanism
+
+This mode relies on the Context Provider mechanism of the Context Broker. For this scenario to work, the IoTAgent must
 register its commands for each device, with a request like the following:
 
 ```bash
 curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Fiware-service: workshop" \
   -H "fiware-servicepath:  /iota2ngsi " -H "x-auth-token: <token>" -d '{
-    "contextRegistrations": [
-        {
-            "entities": [
-                {
-                    "type": "device",
-                    "isPattern": "false",
-                    "id": "Dev0001"
-                }
-            ],
-            "attributes": [
-                {
-                    "name": "switch",
-                    "type": "command",
-                    "isDomain": "false"
-                }
-            ],
-            "providingApplication": "http://<target-host>:1026/v1"
-        }
-    ],
-    "duration": "P1M"
+   "dataProvided": {
+     "entities": [
+       {
+         "id": "Dev0001",
+         "type": "Device"
+       }
+     ],
+     "attrs": [ "switch" ]
+   },
+   "provider": {
+     "http": {
+       "url": "<value of the IOTA_PROVIDER_URL>"
+     }
+   }
 }' "https://<platform-ip>:1026/v2/registrations"
 ```
 
-If everything has gone OK, the Context Broker will return the following payload:
+If everything has gone OK, the Context Broker will return 201 Created with the ID of the registration in the `Location`
+header:
 
-```json
-{
-    "duration": "P1M",
-    "registrationId": "41adf79dc5a0bba830a6f3824"
-}
+```
+HTTP/1.1 201 Created
+Date: ...
+Fiware-Correlator: ...
+Location: /v2/registrations/41adf79dc5a0bba830a6f3824
+Content-Length: 0
 ```
 
 This ID can be used to update the registration in the future.
 
 The registration of the commands is performed once in the lifetime of the Device.
 
-#### Command Execution
+##### Command Execution
 
-##### Based in update (classic way)
-
-Scenario 3 begins with the request for a command from the User to the Context Broker (P1):
+Execution begins with the request for a command from the User to the Context Broker (P1):
 
 ```bash
 curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Fiware-Service: workshop" \
@@ -785,7 +795,6 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
     "entities": [
         {
             "type": "device",
-            "isPattern": "false",
             "id": "Dev0001",
             "switch": {
                 "type": "command",
@@ -793,7 +802,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "updateAction": "append"
+    "updateAction": "update"
 } ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
@@ -823,38 +832,160 @@ Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
       }
     }
   ],
-  "updateAction" : "append"
+  "updateAction" : "update"
 }
 ```
 
-The IoT Agent detects the selected attribute is a command, and replies to the Context Broker with a 204 OK (without
-payload).
+The IoT Agent detects the selected attribute is a command, and replies to the Context Broker with a 204 No Content
+(without payload).
 
 This response just indicates that the IoT Agent has received the command successfully, and gives no information about
 the requested information or command execution.
 
-The Context Broker, forwards the same response to the user, thus replying the original request (200 OK):
+The Context Broker, forwards the same response to the user, thus replying the original request with 204 No Content.
 
-```json
-[
-    {
-        "type": "device",
-        "id": "Dev0001",
-        "switch": {
-            "type": "command",
-            "value": ""
+At this point, the command has been issued to the IoTAgent and the User doesn't still know what the result of its
+request will be.
+
+#### `notification` mode
+
+##### Set up Context Broker to IoTAgent comunication mechanism
+
+This mode relies on the notification mechanism of the Context Broker. For this scenario to work, the IoTAgent must
+subscribe its commands for each device, with a request like the following:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Fiware-service: workshop" \
+  -H "fiware-servicepath:  /iota2ngsi " -H "x-auth-token: <token>" -d '{
+    "subject": {
+        "entities": [
+            {
+              "type": "device",
+              "id": "Dev0001",
+            }
+        ],
+        "condition": {
+            "attrs": [ "switch" ]
         }
+    },
+    "notification": {
+        "http": {
+            "url": "<value of the IOTA_PROVIDER_URL>/notify"
+        },
+        "attrsFormat": "normalized",
+        "attrs": [ "switch" ]
     }
-]
+}' "https://<platform-ip>:1026/v2/subscriptions"
 ```
 
+If everything has gone OK, the Context Broker will return 201 Created with the ID of the subscription in the `Location`
+header:
+
+```
+HTTP/1.1 201 Created
+Date: ...
+Fiware-Correlator: ...
+Location: /v2/subscription/60b0cedd497e8b681d40b58e
+Content-Length: 0
+```
+
+This ID can be used to update the subscription in the future.
+
+The subscription of the commands is performed once in the lifetime of the Device.
+
+##### Command Execution
+
+As in the legacy mode, execution begins with the request for a command from the User to the Context Broker (P1):
+
+```bash
+curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Fiware-Service: workshop" \
+  -H "Fiware-ServicePath:  /iota2ngsi " -H "X-Auth-Token: <token>" -d '{
+    "entities": [
+        {
+            "type": "device",
+            "id": "Dev0001",
+            "switch": {
+                "type": "command",
+                "value": "54, 12"
+            }
+        }
+    ],
+    "updateAction": "update"
+} ' "https://<platform-ip>:1026/v2/op/update"
+```
+
+The Context Broker receives this update and detects that it triggers the subscription, so it notifies to the IoT Agent,
+as follows:
+
+```bash
+POST /notify HTTP/1.1
+Host: <target-host>:<northbound_port>
+Fiware-service: workshop
+Fiware-ServicePath: /iota2ngsi
+Accept: application/json
+Content-length: ...
+Content-type: application/json; charset=utf-8
+Ngsiv2-Attrsformat: normalized
+Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
+
+{
+    "subscriptionId": "60b0cedd497e8b681d40b58e",
+    "data": [{
+      "id": "Dev0001",
+      "type": "device",
+      "switch": {
+          "type": "command",
+          "value": "54, 12",
+          "metadata": {}
+      }
+    }]
+}
+```
+
+The IoT Agent detects the selected attribute is a command, and replies to the Context Broker with a 204 OK (without
+payload).
+
+This response just indicates that the IoT Agent has received the command successfully, and gives no information about
+the requested information or command execution.
+
 At this point, the command has been issued to the IoTAgent and the User doesn't still know what the result of its
 request will be.
 
-##### Based in notification (new way)
+#### `advancedNotification` mode
+
+##### Set up ContextBroker to IOTA comunication mechanism
 
-A new way to ContextBroker provides a command to a IoTAgent is through notifications. In this case CB notify the command
-to the IotAgent with a request like the following:
+The communication mechanism will be based on subscriptions, although a different one than the one used in `notification`
+mode. Note this mode has not been implemented yet, so following should be taken as a draft:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Fiware-Service: workshop" \
+  -H "Fiware-ServicePath:  /iota2ngsi " -H "X-Auth-Token: <token>" -d '{
+    "subject": {
+        "entities": [
+            {
+                "idPattern": ".*",
+                "type": "switchExecution"
+            }
+        ],
+        "condition": {
+            "expression": {
+                "q": "status:FORWARDED;targetEntityType:StreetLight"
+            }
+        }
+    },
+    "notification": {
+        "http": {
+            "url": "<value of the IOTA_PROVIDER_URL>/notify"
+        }
+    }
+}' "https://<platform-ip>:1026/v2/subscriptions"
+```
+
+##### Command Execution
+
+Command execution involves to create a _command execution entity_ (details are yet to be implemented), which in sequence
+triggers a notification to IoTAgent as this one (draft)
 
 ```bash
 POST /notify HTTP/1.1
@@ -864,6 +995,7 @@ Fiware-ServicePath: /iota2ngsi
 Accept: application/json
 Content-length: 290
 Content-type: application/json; charset=utf-8
+Ngsiv2-Attrsformat: normalized
 Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
 
 {
@@ -945,8 +1077,37 @@ In this case relevant fields are just `targetEntityId`, `targetEntityType`, `cmd
 The IoT Agent detects the selected attribute is a command, and replies to the Context Broker with a 204 OK (without
 payload).
 
+This response just indicates that the IoT Agent has received the command successfully, and gives no information about
+the requested information or command execution.
+
+At this point, the command has been issued to the IoTAgent and the User doesn't still know what the result of its
+request will be.
+
+As mentioned before, advanced notification mode has not been yet implemented. The following considerations are gap in
+the current implementation at IoT Agent side that should be addressed:
+
+-   Fields others than `targetEntityId`, `targetEntityType`, `cmd` and `params` (i.e. `execTs`, `status`, `info`,
+    `onDelivered`, `onOk`, `onError`, `onInfo`, `cmdExecution` and `dataExpiration`), are not actually used. By the
+    moment they are stored in the commands model (commands collection) but nothing is done with them appart from
+    storing.
+-   The "Result reporting" should not be a "hardwired" behaviour updating the entity associated to the device, but using
+    the corresponding `on*` attribute in the notificaiton (e.g. `onOk` in the case of success). That attribute would
+    typically be a [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) object like this
+    `"onOk": { "href": "/v2/entities/123456abcdefg/attrs/status?type=switchExecution", "method": "PUT" }`. Moreover, the
+    entity to be updated in that HATEOAS would be the transient entity corresponding to command execuion, not the entity
+    associated to the device.
+
+```
+PUT /v2/entities/123456abcdefg/attrs/status?type=switchExecution
+content-type: text/plain
+
+OK
+```
+
 #### Result reporting
 
+No matter the command mode (legacy or notification based), the result reporting is the same in all cases.
+
 Once the IoT Agent has executed the command or retrieved the information from the device, it reports the results to the
 Context Broker, with an updateContext (P1):
 
@@ -956,7 +1117,6 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
     "entities": [
         {
             "type": "device",
-            "isPattern": "false",
             "id": "Dev0001",
             "switch_info": {
                 "type": "commandResult",
@@ -975,24 +1135,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
 This update does not modify the original command attribute, but two auxiliary attributes, that are not provided by the
 IoT Agent (usually, those attributes has the same name as the command, with an added suffix).
 
-The Context Broker replies to the IoT Agent with a R1 payload (200 OK):
-
-```json
-[
-    {
-        "type": "device",
-        "id": "Dev0001",
-        "switch_info": {
-            "type": "commandResult",
-            "value": ""
-        },
-        "switch_status": {
-            "type": "commandStatus",
-            "value": ""
-        }
-    }
-]
-```
+The Context Broker replies to the IoT Agent with 204 No Content response (no payload).
 
 This operation stores the retrieved values locally in the Context Broker, so it can be retrieved with standard NGSI
 mechanisms.
@@ -1007,7 +1150,6 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
   -H "Fiware-ServicePath:  /iota2ngsi " -H "X-Auth-Token: <token>" -d '{
     "entities": [
         {
-            "isPattern": "false",
             "id": "Dev0001",
             "type": "device"
         }
@@ -1038,30 +1180,6 @@ The Context Broker replies with all the desired data, in R2 format (200 OK):
 ]
 ```
 
-#### Differences regarding the new commands mode
-
-A new commands flow has been defined (involving also modifications at ContextBroker). As part of that design, commands
-are not sent to IOTAs using NGSIv2 notifications, but the current implementation has some differences regarding the
-desired behaviour, which are described next:
-
--   Fields others than `targetEntityId`, `targetEntityType`, `cmd` and `params` (i.e. `execTs`, `status`, `info`,
-    `onDelivered`, `onOk`, `onError`, `onInfo`, `cmdExecution` and `dataExpiration`), are not actually used. By the
-    moment they are stored in the commands model (commands collection) but nothing is done with them appart from
-    storing.
--   The "Result reporting" should not be a "hardwired" behaviour updating the entity associated to the device, but using
-    the corresponding `on*` attribute in the notificaiton (e.g. `onOk` in the case of success). That attribute would
-    typically be a [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) object like this
-    `"onOk": { "href": "/v2/entities/123456abcdefg/attrs/status?type=switchExecution", "method": "PUT" }`. Moreover, the
-    entity to be updated in that HATEOAS would be the transient entity corresponding to command execuion, not the entity
-    associated to the device.
-
-```
-PUT /v2/entities/123456abcdefg/attrs/status?type=switchExecution
-content-type: text/plain
-
-OK
-```
-
 ### Scenario 3: commands (error)
 
 In Scenario 3, errors can happen asynchronously, out of the main interactions. When the IoTAgent detects an error
@@ -1074,7 +1192,6 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
     "entities": [
         {
             "type": "device",
-            "isPattern": "false",
             "id": "Dev0001",
             "switch_info":{
                 "type": "commandResult",
@@ -1090,23 +1207,6 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
 } ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
-In this case, the Context Broker reply with the following response (200 OK):
-
-```json
-[
-    {
-        "type": "device",
-        "id": "Dev0001",
-        "switch_info": {
-            "type": "commandResult",
-            "value": ""
-        },
-        "switch_status": {
-            "type": "commandStatus",
-            "value": ""
-        }
-    }
-]
-```
+In this case, the Context Broker reply with the a 204 No Content response (no payload).
 
 The User will acknowledge the error the next time he queries the Context Broker for information about the command.

package/lib/commonConfig.js

@@ -160,7 +160,8 @@ function processEnvironmentVariables() {
         'IOTA_LD_SUPPORT_DATA_TYPE',
         'IOTA_EXPRESS_LIMIT',
         'IOTA_USE_CB_FLOW_CONTROL',
-        'IOTA_STORE_LAST_MEASURE'
+        'IOTA_STORE_LAST_MEASURE',
+        'IOTA_CMD_MODE'
     ];
     const iotamVariables = [
         'IOTA_IOTAM_URL',
@@ -172,6 +173,9 @@ function processEnvironmentVariables() {
         'IOTA_IOTAM_AGENTPATH'
     ];
     const mongoVariables = [
+        'IOTA_MONGO_URI',
+        // FIXME: the following IOTA_MONGO_ env vars are deprecated and will
+        // be eventually removed (use IOTA_MONGO_URI)
         'IOTA_MONGO_HOST',
         'IOTA_MONGO_PORT',
         'IOTA_MONGO_DB',
@@ -408,6 +412,10 @@ function processEnvironmentVariables() {
         config.mongodb = {};
     }
 
+    if (process.env.IOTA_MONGO_URI) {
+        config.mongodb.uri = process.env.IOTA_MONGO_URI;
+    }
+
     if (process.env.IOTA_MONGO_HOST) {
         config.mongodb.host = process.env.IOTA_MONGO_HOST;
     }
@@ -500,6 +508,9 @@ function processEnvironmentVariables() {
     } else {
         config.storeLastMeasure = config.storeLastMeasure === true;
     }
+    if (process.env.IOTA_CMD_MODE) {
+        config.cmdMode = process.env.IOTA_CMD_MODE;
+    }
 }
 
 function setConfig(newConfig) {

package/lib/jexlTranformsMap.js

@@ -204,6 +204,21 @@ const map = {
             options
         );
     },
+    localestringnumber: (n, locale, options) => {
+        const safeOperation =
+            (fn) =>
+            (...args) => {
+                try {
+                    return fn(...args);
+                } catch (e) {
+                    return null;
+                }
+            };
+        return safeOperation((n, locale, options) => {
+            if (typeof n !== 'number' || isNaN(n)) return null;
+            return n.toLocaleString(locale, options);
+        })(n, locale, options);
+    },
     now: Date.now,
     hextostring: (val) => {
         const safeOperation =

package/lib/model/Device.js

@@ -57,7 +57,9 @@ const Device = new Schema({
     useCBflowControl: Boolean,
     storeLastMeasure: Boolean,
     lastMeasure: Object,
-    oldCtxt: Object
+    oldCtxt: Object,
+    cmdMode: String,
+    subscriptionId: String
 });
 
 function load() {

package/lib/model/Group.js

@@ -67,7 +67,8 @@ const Group = new Schema({
     entityNameExp: String,
     payloadType: String,
     useCBflowControl: Boolean,
-    storeLastMeasure: Boolean
+    storeLastMeasure: Boolean,
+    cmdMode: String
 });
 
 function load() {