Merge pull request #968 from jason-fox/feature/linked-data

fgalan · web-flow · commit edac17aa5619 · 2021-02-12T12:47:26.000+01:00
Add linked data entities.
diff --git a/CHANGES_NEXT_RELEASE b/CHANGES_NEXT_RELEASE
@@ -12,6 +12,7 @@ Add: basic NGSI-LD support as experimental feature (#842)
 - Lazy Attributes
 - Commands
 - Mixed mode (based in ngsiVersion field in the provisioning API)
+- Support to linked data entities to enable the traversal of the nodes of the knowledge graph
 Update codebase to use ES6
 -  Remove JSHint and jshint overrides
 -  Add esLint using standard tamia presets
diff --git a/doc/advanced-topics.md b/doc/advanced-topics.md
@@ -185,6 +185,58 @@ Other unrecognised `type` attributes will be passed as NGSI-LD data using the fo
     }
 ```
 
+
+### NGSI-LD Linked Data support
+
+`static_attributes` may be supplied with an additional `link` data element when provisioning an IoT Agent to ensure that active attributes from the provisioned IoT Device may be maintained in parallel with a linked data entity . Take for example a temperature gauge placed within a building.
+The **Device** data model literally represents the IoT device itself, but the `temperature` attribute also needs to be shared with the **Building** entity
+
+A `link` between them can be provisioned as shown:
+
+e.g.:
+
+```json
+{
+     "entity_type": "Device",
+     "resource":    "/iot/d",
+     "protocol":    "PDI-IoTA-UltraLight",
+..etc
+     "attributes": [
+        {"object_id": "l", "name": "temperature", "type":"Float",
+          "metadata":{
+              "unitCode":{"type": "Text", "value" :"CEL"}
+          }
+        }
+     ],
+     "static_attributes": [
+        {
+          "name": "controlledAsset",
+          "type": "Relationship",
+          "value": "urn:ngsi-ld:Building:001",
+          "link": {
+             "attributes": ["temperature"],
+             "name": "providedBy",
+             "type": "Building"
+          }
+        }
+     ]
+  }
+```
+
+Whenever a `temperature` measure is received **Device** is updated,  and entity `urn:ngsi-ld:Building:001` is also updated as shown:
+
+```json
+"temperature": {
+    "type": "Property",
+    "value": 27.6,
+    "unitCode": "CEL",
+    "providedBy": {
+        "type": "Relationship",
+        "object": "urn:ngsi-ld:Device:thermometer1"
+    }
+}
+```
+
 ### Data mapping plugins
 
 The IoT Agent Library provides a plugin mechanism in order to facilitate reusing code that makes small transformations
diff --git a/lib/services/devices/registrationUtils.js b/lib/services/devices/registrationUtils.js
@@ -464,7 +464,11 @@ function sendRegistrationsNgsiLD(unregister, deviceData, callback) {
     }
 
     let id = String(deviceData.name);
-    id = id.startsWith(NGSI_LD_URN) ? id : NGSI_LD_URN + deviceData.type + ':' + id;
+    if (!id.startsWith(NGSI_LD_URN)) {
+        id = NGSI_LD_URN + deviceData.type + ':' + id;
+        logger.debug(context, 'Amending id to a valid URN: %s', id);
+    }
+
 
     const options = {
         url: cbHost + '/ngsi-ld/v1/csourceRegistrations/',
diff --git a/lib/services/ngsi/entities-NGSI-LD.js b/lib/services/ngsi/entities-NGSI-LD.js
@@ -200,7 +200,11 @@ function formatAsNGSILD(json) {
         switch (key) {
             case 'id':
                 id = json[key];
-                obj[key] = id.startsWith(NGSI_LD_URN) ? id : NGSI_LD_URN + json.type + ':' + id;
+                obj[key] = id;
+                if (!id.startsWith(NGSI_LD_URN)){
+                    obj[key] = NGSI_LD_URN + json.type + ':' + id;
+                    logger.debug(context, 'Amending id to a valid URN: %s', obj[key]);
+                }
                 break;
             case 'type':
                 obj[key] = json[key];
@@ -350,6 +354,57 @@ function sendQueryValueNgsiLD(entityName, attributes, typeInformation, token, ca
     );
 }
 
+/**
+ * Adds any linked data items to the NGSI-LD payload for the context broker.
+ * For example a Building entity linked to a temperature gauge Device will
+ * also be updated as measures are received to update the Device Entity.
+ *
+ * @param {Object} typeInformation  Configuration information for the device.
+ * @param {Object} json             Payload to send to the context broker
+ */
+function addLinkedEntities(typeInformation, json) {
+    // use the supplied type if possible, but fallback to reading the
+    // type from the id of the entity.
+    function getEntityType(id, target) {
+        if (target.type) {
+            return target.type;
+        }
+        let calculatedType = id.replace(NGSI_LD_URN, '');
+        const n = calculatedType.indexOf(':');
+        calculatedType = calculatedType.substring(0, n !== -1 ? n : calculatedType.length);
+        logger.debug(context, 'Guessing linked type from %s as no type attribute found', id);
+        return calculatedType;
+    }
+    const linkedTypeInfo = {};
+    if(typeInformation.staticAttributes){
+        typeInformation.staticAttributes.forEach((item) => {
+            if (item.link) {
+                linkedTypeInfo[item.name] = item.link;
+            }
+        });
+    }
+
+    Object.keys(linkedTypeInfo).forEach((sourceAttr) => {
+        const sourceAttribute = json[0][sourceAttr];
+        if (sourceAttribute) {
+            const linkInfo = linkedTypeInfo[sourceAttr];
+            const linkName = linkInfo.name || 'providedBy';
+            const linkedEntity = {
+                '@context': config.getConfig().contextBroker.jsonLdContext,
+                id: sourceAttribute.object || sourceAttribute.value
+            };
+            linkedEntity.type = getEntityType(linkedEntity.id, linkInfo);
+            linkInfo.attributes.forEach((attr) => {
+                if (json[0][attr]) {
+                    linkedEntity[attr] = json[0][attr];
+                    linkedEntity[attr][linkName] = { type: 'Relationship', object: json[0].id };
+                }
+            });
+            json.push(linkedEntity);
+        }
+    });
+}
+
 /**
  * Makes an update in the Device's entity in the context broker, with the values given in the 'attributes' array.
  * This array should comply to the NGSI-LD's attribute format.
@@ -495,6 +550,10 @@ function sendUpdateValueNgsiLD(entityName, attributes, typeInformation, token, c
                     return callback(new errors.BadGeocoordinates(JSON.stringify(payload)));
                 }
 
+                if (typeInformation.active) {
+                    addLinkedEntities(typeInformation, options.json);
+                }
+
                 logger.debug(context, 'Updating device value in the Context Broker at [%s]', options.url);
                 logger.debug(
                     context,
diff --git a/test/unit/ngsi-ld/examples/contextRequests/updateContextStaticAttributesMetadata.json b/test/unit/ngsi-ld/examples/contextRequests/updateContextStaticAttributesMetadata.json
@@ -9,6 +9,10 @@
             "type": "Property",
             "value": "StaticValue"
         },
+        "controlledAsset": {
+            "type": "Relationship",
+            "object": "urn:ngsi-ld:Building:001"
+        },
         "id": "urn:ngsi-ld:Lamp:lamp1",
         "luminosity": {
             "type": "Property",
diff --git a/test/unit/ngsi-ld/examples/contextRequests/updateContextStaticLinkedAttributes.json b/test/unit/ngsi-ld/examples/contextRequests/updateContextStaticLinkedAttributes.json
@@ -0,0 +1,40 @@
+[
+  {
+    "@context": "http://context.json-ld",
+    "luminosity": {
+      "type": "Property",
+      "value": 87,
+      "providedBy": {
+        "type": "Relationship",
+        "object": "urn:ngsi-ld:Lamp:lamp1"
+      }
+    },
+    "controlledAsset": {
+      "type": "Relationship",
+      "object": "urn:ngsi-ld:Building:001"
+    },
+    "controlledProperty": {
+      "type": "Property",
+      "value": "StaticValue",
+      "includes": {
+        "type": "Property",
+        "value": "bell"
+      }
+    },
+    "id": "urn:ngsi-ld:Lamp:lamp1",
+    "type": "Lamp"
+  },
+  {
+    "@context": "http://context.json-ld",
+    "id": "urn:ngsi-ld:Building:001",
+    "type": "Building",
+    "luminosity": {
+      "type": "Property",
+      "value": 87,
+      "providedBy": {
+        "type": "Relationship",
+        "object": "urn:ngsi-ld:Lamp:lamp1"
+      }
+    }
+  }
+]
diff --git a/test/unit/ngsi-ld/ngsiService/active-devices-test.js b/test/unit/ngsi-ld/ngsiService/active-devices-test.js
@@ -120,6 +120,11 @@ const iotAgentConfig = {
             commands: [],
             lazy: [],
             staticAttributes: [
+                {
+                    name: 'controlledAsset',
+                    type: 'Relationship',
+                    value: 'urn:ngsi-ld:Building:001'
+                },
                 {
                     name: 'controlledProperty',
                     type: 'Property',
@@ -145,6 +150,58 @@ const iotAgentConfig = {
     providerUrl: 'http://smartGondor.com'
 };
 
+describe('NGSI-LD - Linked Data Active attributes test', function () {
+    const values = [
+        {
+            name: 'luminosity',
+            type: 'Number',
+            value: 87
+        }
+    ];
+
+    beforeEach(function () {
+        logger.setLevel('FATAL');
+    });
+
+    afterEach(function (done) {
+        iotAgentLib.deactivate(done);
+    });
+
+    describe('When the IoT Agent receives new information from a device with an active link', function () {
+        beforeEach(function (done) {
+            nock.cleanAll();
+
+            contextBrokerMock = nock('http://192.168.1.1:1026')
+                .matchHeader('fiware-service', 'smartGondor')
+                .post(
+                    '/ngsi-ld/v1/entityOperations/upsert/?options=update',
+                    utils.readExampleFile(
+                        './test/unit/ngsi-ld/examples/contextRequests/updateContextStaticLinkedAttributes.json'
+                    )
+                )
+
+                .reply(204);
+
+            const deepClonedObject = JSON.parse(JSON.stringify(iotAgentConfig));
+            deepClonedObject.types.Lamp.staticAttributes[0].link = {
+                attributes: ['luminosity'],
+                name: 'providedBy',
+                type: 'Building'
+            };
+
+            iotAgentLib.activate(deepClonedObject, done);
+        });
+
+        it('should change the value of the corresponding attribute in the context broker and the linked entity', function (done) {
+            iotAgentLib.update('lamp1', 'Lamp', '', values, function (error) {
+                should.not.exist(error);
+                contextBrokerMock.done();
+                done();
+            });
+        });
+    });
+});
+
 describe('NGSI-LD - Active attributes test', function () {
     const values = [
         {
