ADD historical context custom node

.gitignore

@@ -2,5 +2,6 @@ node_modules/
 .nyc_output/
 coverage/
 .vscode/
+images/
 :wq
 *.swp

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## node-red-contrib-letsfiware-NGSI v0.6.0-next
 
+-  ADD Historical context custom node (#42)
 -  ADD FIWARE GE type option (#40)
 -  UPDATE Node.js dependencies (#39)
 -  Add entity node to dateModified option (#38)

README.md

@@ -21,6 +21,7 @@ Node-RED implementation for FIWARE Open APIs
 -   [NGSI Source](docs/custom_nodes/ngsi_source.md)
 -   [NGSI Batch update](docs/custom_nodes/ngsi_batch_update.md)
 -   [NGSI Subscription](docs/custom_nodes/ngsi_subscription.md)
+-   [Historical context](docs/custom_nodes/historical_context.md)
 -   [NGSI to Worldmap](docs/custom_nodes/ngsi_to_worldmap.md)
 -   [NGSI GTFS realtime](docs/custom_nodes/ngsi_gtfs_realtime.md)
 -   [FIWARE version](docs/custom_nodes/fiware_version.md)

docs/custom_nodes/historical_context.md

@@ -0,0 +1,207 @@
+# Historical Context
+
+This custom node is a simple node that allows to obtain historical context from STH-Comet.
+
+![](https://raw.githubusercontent.com/lets-fiware/node-red-contrib-letsfiware-NGSI/gh-pages/images/historical-context-01.png)
+
+## Properties
+
+This node allows to obtain raw context information or historical aggregate time series context information from STH-Comet.
+
+![](https://raw.githubusercontent.com/lets-fiware/node-red-contrib-letsfiware-NGSI/gh-pages/images/historical-context-02.png)
+
+-   Raw context information
+-   Historical aggregate time series context information
+    -   Average of all the samples
+    -   Maximum value
+    -   Sum of all the samples
+    -   Sum of the square value of all the samples
+    -   Occur for attributes values of type string
+
+You can specify the start and end of the target period.
+
+-   ISO 8601
+-   years
+-   months
+-   days
+-   hours
+-   minutes
+-   seconds
+
+For example, if you want to get historical context from 3 days ago to 2 days ago, specify as follows.
+
+![](https://raw.githubusercontent.com/lets-fiware/node-red-contrib-letsfiware-NGSI/gh-pages/images/historical-context-03.png)
+
+### Raw context information
+
+![](https://raw.githubusercontent.com/lets-fiware/node-red-contrib-letsfiware-NGSI/gh-pages/images/historical-context-04.png)
+
+-   `name`: a name for a node instance
+-   `Generic Enabler`: an endpoint of a STH-Comet
+-   `ServicePath`: FIWARE Service Path
+-   `Entity id`: an entity id to retrieve
+-   `Entity type`: an entity type to retrieve
+-   `Attribute`: an attribute to retrieve
+-   `Date type`: an data type to retrieve
+-   `LastN`: only the requested last entries will be returned. It is a mandatory parameter if no Limit and Offset are provided
+-   `Limit`: in case of pagination, the number of entries per page. It is a mandatory parameter if no lastN is provided
+-   `Offset`: in case of pagination, the offset to apply to the requested search of raw context information. It is a mandatory parameter if no lastN is provided
+-   `Date from`: the starting date and time from which the raw context information is desired. It is an optional parameter
+-   `Unit for data from`: unit for starting date
+-   `Date to`: the final date and time until which the raw context information is desired. It is an optional parameter.
+-   `Unit for data to`: unit for  the final date
+-   `Output type`: `raw`, `value` or `dashboard`
+-   `Count`: the total count of elements
+
+### Historical Aggregated Time Series Context Information
+
+![](https://raw.githubusercontent.com/lets-fiware/node-red-contrib-letsfiware-NGSI/gh-pages/images/historical-context-05.png)
+
+-   `name`: a name for a node instance
+-   `Generic Enabler`: an endpoint of a STH-Comet
+-   `ServicePath`: FIWARE Service Path
+-   `Entity id`: an entity id to retrieve
+-   `Entity type`: an entity type to retrieve
+-   `Attribute`: an attribute to retrieve
+-   `Date type`: an data type to retrieve
+-   `Offset`: in case of pagination, the offset to apply to the requested search of raw context information. It is a mandatory parameter if no lastN is provided
+-   `AggrPeriod`: Aggregation period or resolution
+-   `Date from`: the starting date and time from which the raw context information is desired. It is an optional parameter
+-   `Unit for data from`: unit for starting date
+-   `Date to`: the final date and time until which the raw context information is desired. It is an optional parameter.
+-   `Unit for data to`: unit for  the final date
+-   `Output type`: `raw`, `value` or `dashboard`
+
+## Inputs
+
+### Payload  *JSON Object*
+
+A `msg.payload` may contain attributes as shown:
+
+```
+{
+  "entityId": 
+  "attrName": 
+  "entityType":
+  "dataType": "raw", "ave", "max", "sum", "sum2" or "occur"
+  "lastN:
+  "hLimit":
+  "hOffset":
+  "aggrPeriod": "month", "day", "hour", "minute" or "second"
+  "dateFrom:"
+  "fromUnit": "ISO8601", "years", "months", "days", "hours", "minutes" or "seconds"
+  "dateTo: 
+  "toUnit: 
+  "outputType: "raw", "value", "dashboard"
+  "count": "true" or "false"
+}
+```
+
+These attribute are optional. If properties have appropriate values, you can retrieve historical context by sending
+a empty JSON object to this node. If an attribute has a value, it overwrites the value of its corresponding property.
+
+## Outputs
+
+### Payload *JSON Object*
+
+A `msg.payload` contains .
+
+## Examples
+
+### Output (raw)
+
+```
+{
+  "type": "StructuredValue",
+  "value": [
+    {
+      "_id": {
+        "attrName": "temperature",
+        "origin": "2023-01-01T00:00:00.000Z",
+        "resolution": "month"
+      },
+      "points": [
+        {
+          "offset": 1,
+          "samples": 20,
+          "sum": 100
+        },
+        {
+          "offset": 1,
+          "samples": 0,
+          "sum": 0
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Output (value)
+
+```
+[
+  {
+    "_id": "63d115bb5f63eb554d85a13b",
+    "attrName": "temperature",
+    "attrType": "Number",
+    "attrValue": 20.6,
+    "recvTime": "2023-01-25T11:42:51.143Z"
+  },
+  {
+    "_id": "63d115bd5f63eb554d85a141",
+    "attrName": "temperature",
+    "attrType": "Number",
+    "attrValue": 20.6,
+    "recvTime": "2023-01-25T11:42:53.143Z"
+  },
+  {
+    "_id": "63d115bf5f63eb554d85a147",
+    "attrName": "temperature",
+    "attrType": "Number",
+    "attrValue": 20.6,
+    "recvTime": "2023-01-25T11:42:55.145Z"
+  }
+]
+```
+
+### Output (dashboard)
+
+This output is for the NGSI-to-dashboard custom node.
+
+```
+{
+  "type": "StructuredValue",
+  "value": [
+    {
+      "_id": "63d115bb5f63eb554d85a13b",
+      "attrName": "temperature",
+      "attrType": "Number",
+      "attrValue": 20.6,
+      "recvTime": "2023-01-25T11:42:51.143Z"
+    },
+    {
+      "_id": "63d115bd5f63eb554d85a141",
+      "attrName": "temperature",
+      "attrType": "Number",
+      "attrValue": 20.6,
+      "recvTime": "2023-01-25T11:42:53.143Z"
+    },
+    {
+      "_id": "63d115bf5f63eb554d85a147",
+      "attrName": "temperature",
+      "attrType": "Number",
+      "attrValue": 20.6,
+      "recvTime": "2023-01-25T11:42:55.145Z"
+    }
+  ],
+  "entityId": "E",
+  "attrName": "A1",
+  "entityType": "T1",
+  "dataType": "raw"
+}
+```
+
+## Examples
+
+![](https://raw.githubusercontent.com/lets-fiware/node-red-contrib-letsfiware-NGSI/gh-pages/images/historical-context-06.png)

docs/index.md

@@ -13,6 +13,7 @@ Node-RED NGSI integration
 -   [NGSI Source](custom_nodes/ngsi_source.md)
 -   [NGSI Batch update](custom_nodes/ngsi_batch_update.md)
 -   [NGSI Subscription](custom_nodes/ngsi_subscription.md)
+-   [Historical context](custom_nodes/historical_context.md)
 -   [NGSI to Worldmap](custom_nodes/ngsi_to_worldmap.md)
 -   [NGSI GTFS realtime](custom_nodes/ngsi_gtfs_realtime.md)
 -   [FIWARE version](custom_nodes/fiware_version.md)

package.json

@@ -17,6 +17,7 @@
       "NGSI-GTFS-Realtime": "src/nodes/NGSI/gtfs-realtime/gtfs-realtime.js",
       "NGSI-to-worldmap": "src/nodes/NGSI/to-worldmap/to-worldmap.js",
       "FIWARE-version": "src/nodes/NGSI/version/version.js",
+      "Historical-Context": "src/nodes/NGSI/historical-context/historical-context.js",
       "Open-APIs": "src/nodes/NGSI/open-apis/open-apis.js"
     }
   },
@@ -58,4 +59,4 @@
   "engines": {
     "node": ">=12"
   }
-}
+}

src/lib.js

@@ -138,9 +138,41 @@ function buildSearchParams(config) {
   return searchParams;
 }
 
+function updateContext(msg, service, path, count) {
+  if (!Object.prototype.hasOwnProperty.call(msg, 'context')) {
+    msg.context = {};
+  }
+  msg.context.fiwareService = service;
+  msg.context.fiwareServicePath = path;
+  msg.context.fiwareTotalCount = count;
+
+  return msg;
+}
+
+function getServiceAndServicePath(msg, service, path) {
+  if (!Object.prototype.hasOwnProperty.call(msg, 'context')) {
+    msg.context = {};
+  }
+  if (!Object.prototype.hasOwnProperty.call(msg.context, 'fiwareService')) {
+    msg.context.fiwareService = null;
+  }
+  if (!Object.prototype.hasOwnProperty.call(msg.context, 'fiwareServicePath')) {
+    msg.context.fiwareServicePath = null;
+  }
+  if (msg.context.fiwareService === null) {
+    msg.context.fiwareService = service;
+  }
+  if (msg.context.fiwareServicePath === null) {
+    msg.context.fiwareServicePath = path;
+  }
+  return [msg.context.fiwareService, msg.context.fiwareServicePath];
+}
+
 module.exports = {
   http,
   buildHTTPHeader,
   buildSearchParams,
   buildParams,
+  updateContext,
+  getServiceAndServicePath,
 };