allow receive commands by CB notifications

CHANGES_NEXT_RELEASE

@@ -1,4 +1,5 @@
+- Add: notification-based commands (#1455)
 - Add: allow define headers in device commands (iotagent-json#873)
 - Add: index for Device model based on {service: 1, subservice: 1, id: 1, apikey: 1} (#1576)
 - Fix: Duplicated Devices when burst measures to non provisioned Device (iotagent-json#865)
-- Fix: modified JEXL transformations (toisostring, gettime, parseint, etc.) to return null instead of NaN when some unexpected situation occurs (#1701)
+- Fix: modified JEXL transformations (toisostring, gettime, parseint, etc.) to return null instead of NaN when some unexpected situation occurs (#1701)

doc/devel/northboundinteractions.md

@@ -775,6 +775,8 @@ The registration of the commands is performed once in the lifetime of the Device
 
 #### Command Execution
 
+##### Based in update (classic way)
+
 Scenario 3 begins with the request for a command from the User to the Context Broker (P1):
 
 ```bash
@@ -825,21 +827,7 @@ Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
 }
 ```
 
-The IoT Agent detects the selected attribute is a command, and replies to the Context Broker with the following payload
-(200 OK):
-
-```json
-[
-    {
-        "type": "device",
-        "id": "Dev0001",
-        "switch": {
-            "type": "command",
-            "value": ""
-        }
-    }
-]
-```
+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.
@@ -862,6 +850,99 @@ The Context Broker, forwards the same response to the user, thus replying the or
 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)
+
+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:
+
+```bash
+POST /notify HTTP/1.1
+Host: <target-host>:<northbound_port>
+fiware-service: workshop
+Fiware-ServicePath: /iota2ngsi
+Accept: application/json
+Content-length: 290
+Content-type: application/json; charset=utf-8
+Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
+
+{
+    "subscriptionId": "60b0cedd497e8b681d40b58e",
+    "data": [{
+     "id": "123456abcdefg",
+     "type": "switchOnOffExecution",
+     "targetEntityId": {
+         "type": "Text",
+         "value": "Dev0001",
+         "metadata": {}
+     },
+     "targetEntityType": {
+         "type": "Text",
+         "value": "device",
+         "metadata": {}
+     },
+     "execTs": {
+         "type": "DateTime",
+         "value": "2020-05-27T00:00:00.000Z",
+         "metadata": {}
+     },
+     "cmd": {
+         "type": "Text",
+         "value": "switch",
+         "metadata": {}
+     },
+     "params": {
+         "type": "Text",
+         "value": "54, 12",
+         "metadata": {}
+     },
+     "status": {
+         "type": "Text",
+         "value": "FORWARDED",
+         "metadata": {}
+     },
+     "info": {
+         "type": "Text",
+         "value": null,
+         "metadata": {}
+     },
+     "onDelivered": {
+         "type": "Request",
+         "value": {
+         }
+     },
+     "onOk": {
+         "type": "Request",
+         "value": {
+         }
+     },
+     "onError": {
+         "type": "Request",
+         "value": {
+         }
+     },
+     "onInfo": {
+         "type": "Request",
+         "value": {
+         }
+     },
+     "cmdExecution": {
+         "type": "value",
+         "value": true,
+         "metadata": {}
+     },
+     "dateExpiration": {
+         "type": "DateTime",
+         "value": "2020-05-27T20:00:00.000Z",
+         "metadata": {}
+     }
+    }]
+}
+```
+
+In this case relevant fields are just `targetEntityId`, `targetEntityType`, `cmd` and `params`.
+
+The IoT Agent detects the selected attribute is a command, and replies to the Context Broker with a 204 OK (without payload).
+
 #### Result reporting
 
 Once the IoT Agent has executed the command or retrieved the information from the device, it reports the results to the
@@ -955,6 +1036,27 @@ 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

doc/models/models.md

@@ -201,6 +201,15 @@ Fields:
 -   **value** _object_: value of the command
 -   **service** _string_: service which the device command belongs to
 -   **subservice** _string_: subservice which the device command belongs to
+-   **execTs** _date_: related with new commands functionality (stored but not yet in use)
+-   **status** _string_: related with new commands functionality (stored but not yet in use)
+-   **info** _string_: related with new commands functionality (stored but not yet in use)
+-   **onDelivered** _Object_: related with new commands functionality (stored but not yet in use)
+-   **onOk**: _Object_: related with new commands functionality (stored but not yet in use)
+-   **onError** _Object_: related with new commands functionality (stored but not yet in use)
+-   **onInfo** _Object_: related with new commands functionality (stored but not yet in use)
+-   **cmdExecution** _Boolean__: related with new commands functionality (stored but not yet in use)
+-   **dateExpiration**: { type: Date }: related with new commands functionality (stored but not yet in use)
 -   **creationDate** _date_: creation date of command
 
 Example:

lib/fiware-iotagent-lib.js

@@ -314,6 +314,7 @@ exports.setDataUpdateHandler = contextServer.setUpdateHandler;
 exports.setCommandHandler = contextServer.setCommandHandler;
 exports.setMergePatchHandler = contextServer.setMergePatchHandler;
 exports.setDataQueryHandler = contextServer.setQueryHandler;
+exports.executeUpdateSideEffects = contextServer.executeUpdateSideEffects;
 exports.setConfigurationHandler = contextServer.setConfigurationHandler;
 exports.setRemoveConfigurationHandler = contextServer.setRemoveConfigurationHandler;
 exports.setProvisioningHandler = contextServer.setProvisioningHandler;

lib/model/Command.js

@@ -31,6 +31,15 @@ const Command = new Schema({
     value: Object,
     service: { type: String, lowercase: true },
     subservice: String,
+    execTs: { type: Date },
+    status: String,
+    info: String,
+    onDelivered: Object,
+    onOk: Object,
+    onError: Object,
+    onInfo: Object,
+    cmdExecution: Boolean,
+    dateExpiration: { type: Date },
     creationDate: { type: Date, default: Date.now }
 });
 

lib/services/commands/commandRegistryMongoDB.js

@@ -89,7 +89,21 @@ function updateCommand(service, subservice, deviceId, command, callback) {
 function createCommand(service, subservice, deviceId, command, callback) {
     /* eslint-disable-next-line new-cap */
     const commandObj = new Command.model();
-    const attributeList = ['name', 'type', 'value'];
+    const attributeList = [
+        'name',
+        'type',
+        'value',
+        // new Command fields
+        'execTs',
+        'status',
+        'info',
+        'onDelivered',
+        'onOk',
+        'onError',
+        'onInfo',
+        'cmdExecution',
+        'dateExpiration'
+    ];
 
     for (let i = 0; i < attributeList.length; i++) {
         commandObj[attributeList[i]] = command[attributeList[i]];

lib/services/commands/commandService.js

@@ -43,7 +43,7 @@ function listCommands(service, subservice, deviceId, callback) {
 }
 
 function addCommand(service, subservice, deviceId, command, callback) {
-    logger.debug(context, 'Adding command [%j] to the queue for device [%s]', command, deviceId);
+    logger.debug(context, 'Adding command [%j] to the queue for deviceId [%s]', command, deviceId);
     config.getCommandRegistry().add(service, subservice, deviceId, command, callback);
 }
 
@@ -73,13 +73,13 @@ function addCommandDevice(service, subservice, device, command, callback) {
 }
 
 function updateCommand(service, subservice, deviceId, name, value, callback) {
-    logger.debug(context, 'Updating command [%s] for device [%s] with value [%s]', name, deviceId, value);
+    logger.debug(context, 'Updating command [%s] for deviceId [%s] with value [%s]', name, deviceId, value);
 
     config.getCommandRegistry().update(service, subservice, deviceId, value, callback);
 }
 
 function removeCommand(service, subservice, deviceId, name, callback) {
-    logger.debug(context, 'Removing command [%s] from device [%s]', name, deviceId);
+    logger.debug(context, 'Removing command [%s] from deviceId [%s]', name, deviceId);
 
     config.getCommandRegistry().remove(service, subservice, deviceId, name, callback);
 }

lib/services/northBound/contextServer-NGSI-v2.js

@@ -292,9 +292,18 @@ function handleNotificationNgsi2(req, res, next) {
                 }
             }
         }
+        logger.debug(context, 'extracted atts %j from dataElement %j', atts, dataElement);
+        var id = null;
+        var type = null;
+        if (dataElement.targetEntityId && dataElement.targetEntityId.value) {
+            id = dataElement.targetEntityId.value;
+        }
+        if (dataElement.targetEntityType && dataElement.targetEntityType.value) {
+            type = dataElement.targetEntityType.value;
+        }
         deviceService.getDeviceByNameAndType(
-            dataElement.id,
-            dataElement.type,
+            id,
+            type,
             req.headers['fiware-service'],
             req.headers['fiware-servicepath'],
             function (error, device) {
@@ -336,7 +345,7 @@ function handleNotificationNgsi2(req, res, next) {
             logger.error(context, 'Error found when processing notification: %j', error);
             next(error);
         } else {
-            res.status(200).json({});
+            res.status(204).json();
         }
     }
 

lib/services/northBound/contextServer.js

@@ -30,7 +30,7 @@ const context = {
     op: 'IoTAgentNGSI.ContextServer'
 };
 const contextServerUtils = require('./contextServerUtils');
-
+const executeUpdateSideEffects = contextServerUtils.executeUpdateSideEffects;
 let contextServerHandler;
 
 /**
@@ -157,4 +157,5 @@ exports.setCommandHandler = intoTrans(context, setCommandHandler);
 exports.setNotificationHandler = intoTrans(context, setNotificationHandler);
 exports.addNotificationMiddleware = intoTrans(context, addNotificationMiddleware);
 exports.setQueryHandler = intoTrans(context, setQueryHandler);
+exports.executeUpdateSideEffects = intoTrans(context, executeUpdateSideEffects);
 exports.init = init;

lib/services/northBound/northboundServer.js

@@ -125,6 +125,7 @@ exports.setRemoveDeviceHandler = intoTrans(context, deviceProvisioning.setRemove
 exports.addDeviceProvisionMiddleware = deviceProvisioning.addDeviceProvisionMiddleware;
 exports.addConfigurationProvisionMiddleware = groupProvisioning.addConfigurationProvisionMiddleware;
 exports.addNotificationMiddleware = contextServer.addNotificationMiddleware;
+exports.executeUpdateSideEffects = contextServer.executeUpdateSideEffects;
 exports.clear = clear;
 exports.start = intoTrans(context, start);
 exports.stop = intoTrans(context, stop);