iotagent-node-lib 4.7.0 → 4.8.0

package/.github/workflows/ci.yml

@@ -45,7 +45,7 @@ jobs:
     runs-on: ubuntu-latest
     services:
       mongodb:
-        image: mongo:6.0
+        image: mongo:8.0
         ports:
         - 27017:27017
     strategy:
@@ -71,7 +71,7 @@ jobs:
     needs: unit-test
     services:
       mongodb:
-        image: mongo:6.0
+        image: mongo:8.0
         ports:
         - 27017:27017
     steps:

package/CHANGES_NEXT_RELEASE

@@ -0,0 +1 @@
+

package/Changelog

@@ -1,3 +1,11 @@
+4.8.0 (May 23rd, 2025)
+
+- 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)
+
 4.7.0 (February 3rd, 2025)
 
 - Add: store (and recover) previous jexlctxt and make available in current jexlctxt (#1690)

package/doc/README.md

@@ -7,6 +7,7 @@
 -   [Administration manual](admin.md)
 -   [Deprecated features](deprecated.md)
 -   [Roadmap](roadmap.md)
+-   [Data models](models/models.md)
 
 ## Development documentation
 

package/doc/api.md

@@ -165,7 +165,8 @@ parameters defined at device level in database, the parameters are inherit from
 
 ### Uniqueness of groups and devices
 
-Group uniqueness is defined by the combination of: resource and apikey. This is so because given a measure (identified by an apikey) there is no way to identify group related if apikey is not unique for all services and subservices.
+Group uniqueness is defined by the combination of: resource and apikey. This is so because given a measure (identified
+by an apikey) there is no way to identify group related if apikey is not unique for all services and subservices.
 
 Device uniqueness is defined by the combination of: service, subservice, device_id and apikey. Note that several devices
 with the same device_id are allowed in the same service and subservice as long as their apikeys are different.
@@ -256,6 +257,9 @@ Additionally for commands (which are attributes of type `command`) the following
     particular IOTAs documentation for allowed values of this field in each case.
 -   **contentType**: `content-type` header used when send command by HTTP transport (ignored in other kinds of
     transports)
+-   **headers**: extra customer headers used when send command by HTTP transport (ignored in other kinds of
+    transports)
+Check full detail of these fields in [comand-transformations](https://github.com/telefonicaid/iotagent-json/blob/master/docs/usermanual.md#commands-transformations)
 
 Note that, when information coming from devices, this means measures, are not defined neither in the group, nor in the
 device, the IoT agent will store that information into the destination entity using the same attribute name than the
@@ -579,8 +583,8 @@ Case 5:
 
 depending on the JEXL expression evaluation:
 
--   If it evaluates to `true` every measure will be propagated to NGSI interface (as in case 1)
--   If it evaluates to `false` just measures defined in active, static (plus conditionally TimeInstant) will be
+-   If it evaluates to `false` every measure will be propagated to NGSI interface (as in case 1)
+-   If it evaluates to `true` just measures defined in active, static (plus conditionally TimeInstant) will be
     propagated to NGSI interface (as in case 2)
 -   If it evaluates to an array just measures defined in the array (identified by their attribute names, not by their
     object_id) will be will be propagated to NGSI interface (as in case 3)
@@ -2459,4 +2463,4 @@ updateEntityRequestsError 5
 [18]:
     https://czosel.github.io/jexl-playground/#/?context=%7B%0A%20%20%22value%22%20%3A%206%2C%0A%20%20%22ts%22%3A%201637245214901%2C%0A%20%22name%22%3A%20%22DevId629%22%2C%0A%20%22object%22%3A%7Bname%3A%20%22John%22%2C%20surname%3A%20%22Doe%22%7D%2C%0A%20%20%22array%22%3A%5B1%2C3%5D%0A%7D&input=name%7Csubstr(0%2Cname%7CindexOf(%22e%22)%2B1)&transforms=%7B%0A%20%20%20%20jsonparse%3A%20(str)%20%3D%3E%20JSON.parse(str)%2C%0A%20%20%20%20jsonstringify%3A%20(obj)%20%3D%3E%20JSON.stringify(obj)%2C%0A%20%20%20%20indexOf%3A%20(val%2C%20char)%20%3D%3E%20String(val).indexOf(char)%2C%0A%20%20%20%20length%3A%20(val)%20%3D%3E%20String(val).length%2C%0A%20%20%20%20trim%3A%20(val)%20%3D%3E%20String(val).trim()%2C%0A%20%20%20%20substr%3A%20(val%2C%20int1%2C%20int2)%20%3D%3E%20String(val).substr(int1%2C%20int2)%2C%0A%20%20%20%20addreduce%3A%20(arr)%20%3D%3E%20arr.reduce((i%2C%20v)%20%3D%3E%20i%20%2B%20v)%2C%0A%20%20%20%20lengtharray%3A%20(arr)%20%3D%3E%20arr.length%2C%0A%20%20%20%20typeof%3A%20(val)%20%3D%3E%20typeof%20val%2C%0A%20%20%20%20isarray%3A%20(arr)%20%3D%3E%20Array.isArray(arr)%2C%0A%20%20%20%20isnan%3A%20(val)%20%3D%3E%20isNaN(val)%2C%0A%20%20%20%20parseint%3A%20(val)%20%3D%3E%20parseInt(val)%2C%0A%20%20%20%20parsefloat%3A%20(val)%20%3D%3E%20parseFloat(val)%2C%0A%20%20%20%20toisodate%3A%20(val)%20%3D%3E%20new%20Date(val).toISOString()%2C%0A%20%20%20%20timeoffset%3A%20(isostr)%20%3D%3E%20new%20Date(isostr).getTimezoneOffset()%2C%0A%20%20%20%20tostring%3A%20(val)%20%3D%3E%20val.toString()%2C%0A%20%20%20%20urlencode%3A%20(val)%20%3D%3E%20encodeURI(val)%2C%0A%20%20%20%20urldecode%3A%20(val)%20%3D%3E%20decodeURI(val)%2C%0A%20%20%20%20replacestr%3A%20(str%2C%20from%2C%20to)%20%3D%3E%20str.replace(from%2C%20to)%2C%0A%20%20%20%20replaceregexp%3A%20(str%2C%20reg%2C%20to)%20%3D%3E%20str.replace(new%20RegExp(reg)%2C%20to)%2C%0A%20%20%20%20replaceallstr%3A%20(str%2C%20from%2C%20to)%20%3D%3E%20str.replaceAll(from%2C%20to)%2C%0A%20%20%20%20replaceallregexp%3A%20(str%2C%20reg%2C%20to)%20%3D%3E%20str.replaceAll(new%20RegExp(reg%2C%20'g')%2C%20to)%2C%0A%20%20%20%20split%3A%20(str%2C%20ch)%20%3D%3E%20str.split(ch)%2C%0A%20%20%20%20mapper%3A%20(val%2C%20values%2C%20choices)%20%3D%3E%20choices%5Bvalues.findIndex((target)%20%3D%3E%20target%20%3D%3D%3D%20val)%5D%2C%0A%20%20%20%20thmapper%3A%20(val%2C%20values%2C%20choices)%20%3D%3E%0A%20%20%20%20%20%20%20%20choices%5B%0A%20%20%20%20%20%20%20%20%20%20%20%20values.reduce((acc%2C%20curr%2C%20i)%20%3D%3E%20(acc%20%3D%3D%3D%200%20%7C%7C%20acc%20%3F%20acc%20%3A%20val%20%3C%3D%20curr%20%3F%20(acc%20%3D%20i)%20%3A%20(acc%20%3D%20null))%2C%20null)%0A%20%20%20%20%20%20%20%20%5D%2C%0A%20%20%20%20bitwisemask%3A%20(i%2C%20mask%2C%20op%2C%20shf)%20%3D%3E%0A%20%20%20%20%20%20%20%20(op%20%3D%3D%3D%20'%26'%20%3F%20parseInt(i)%20%26%20mask%20%3A%20op%20%3D%3D%3D%20'%7C'%20%3F%20parseInt(i)%20%7C%20mask%20%3A%20op%20%3D%3D%3D%20'%5E'%20%3F%20parseInt(i)%20%5E%20mask%20%3A%20i)%20%3E%3E%0A%20%20%20%20%20%20%20%20shf%2C%0A%20%20%20%20slice%3A%20(arr%2C%20init%2C%20end)%20%3D%3E%20arr.slice(init%2C%20end)%0A%7D
 [99]:
-    https://czosel.github.io/jexl-playground/#/?context=%7B%0A%20%20%22text%22%20%3A%20%22%20%20foobar%7B%7D%20%20%22%0A%7D&input=text%20%7C%20replacestr(%22foo%22%2C%22FOO%22)%7Ctrim%7Curlencode&transforms=%7B%0A%20%20%20%20jsonparse%3A%20(str)%20%3D%3E%20JSON.parse(str)%2C%0A%20%20%20%20jsonstringify%3A%20(obj)%20%3D%3E%20JSON.stringify(obj)%2C%0A%20%20%20%20indexOf%3A%20(val%2C%20char)%20%3D%3E%20String(val).indexOf(char)%2C%0A%20%20%20%20length%3A%20(val)%20%3D%3E%20String(val).length%2C%0A%20%20%20%20trim%3A%20(val)%20%3D%3E%20String(val).trim()%2C%0A%20%20%20%20substr%3A%20(val%2C%20int1%2C%20int2)%20%3D%3E%20String(val).substr(int1%2C%20int2)%2C%0A%20%20%20%20addreduce%3A%20(arr)%20%3D%3E%20arr.reduce((i%2C%20v)%20%3D%3E%20i%20%2B%20v)%2C%0A%20%20%20%20lengtharray%3A%20(arr)%20%3D%3E%20arr.length%2C%0A%20%20%20%20typeof%3A%20(val)%20%3D%3E%20typeof%20val%2C%0A%20%20%20%20isarray%3A%20(arr)%20%3D%3E%20Array.isArray(arr)%2C%0A%20%20%20%20isnan%3A%20(val)%20%3D%3E%20isNaN(val)%2C%0A%20%20%20%20parseint%3A%20(val)%20%3D%3E%20parseInt(val)%2C%0A%20%20%20%20parsefloat%3A%20(val)%20%3D%3E%20parseFloat(val)%2C%0A%20%20%20%20toisodate%3A%20(val)%20%3D%3E%20new%20Date(val).toISOString()%2C%0A%20%20%20%20timeoffset%3A%20(isostr)%20%3D%3E%20new%20Date(isostr).getTimezoneOffset()%2C%0A%20%20%20%20tostring%3A%20(val)%20%3D%3E%20val.toString()%2C%0A%20%20%20%20urlencode%3A%20(val)%20%3D%3E%20encodeURI(val)%2C%0A%20%20%20%20urldecode%3A%20(val)%20%3D%3E%20decodeURI(val)%2C%0A%20%20%20%20replacestr%3A%20(str%2C%20from%2C%20to)%20%3D%3E%20str.replace(from%2C%20to)%2C%0A%20%20%20%20replaceregexp%3A%20(str%2C%20reg%2C%20to)%20%3D%3E%20str.replace(new%20RegExp(reg)%2C%20to)%2C%0A%20%20%20%20replaceallstr%3A%20(str%2C%20from%2C%20to)%20%3D%3E%20str.replaceAll(from%2C%20to)%2C%0A%20%20%20%20replaceallregexp%3A%20(str%2C%20reg%2C%20to)%20%3D%3E%20str.replaceAll(new%20RegExp(reg%2C%20'g')%2C%20to)%2C%0A%20%20%20%20split%3A%20(str%2C%20ch)%20%3D%3E%20str.split(ch)%2C%0A%20%20%20%20mapper%3A%20(val%2C%20values%2C%20choices)%20%3D%3E%20choices%5Bvalues.findIndex((target)%20%3D%3E%20target%20%3D%3D%3D%20val)%5D%2C%0A%20%20%20%20thmapper%3A%20(val%2C%20values%2C%20choices)%20%3D%3E%0A%20%20%20%20%20%20%20%20choices%5B%0A%20%20%20%20%20%20%20%20%20%20%20%20values.reduce((acc%2C%20curr%2C%20i)%20%3D%3E%20(acc%20%3D%3D%3D%200%20%7C%7C%20acc%20%3F%20acc%20%3A%20val%20%3C%3D%20curr%20%3F%20(acc%20%3D%20i)%20%3A%20(acc%20%3D%20null))%2C%20null)%0A%20%20%20%20%20%20%20%20%5D%2C%0A%20%20%20%20bitwisemask%3A%20(i%2C%20mask%2C%20op%2C%20shf)%20%3D%3E%0A%20%20%20%20%20%20%20%20(op%20%3D%3D%3D%20'%26'%20%3F%20parseInt(i)%20%26%20mask%20%3A%20op%20%3D%3D%3D%20'%7C'%20%3F%20parseInt(i)%20%7C%20mask%20%3A%20op%20%3D%3D%3D%20'%5E'%20%3F%20parseInt(i)%20%5E%20mask%20%3A%20i)%20%3E%3E%0A%20%20%20%20%20%20%20%20shf%2C%0A%20%20%20%20slice%3A%20(arr%2C%20init%2C%20end)%20%3D%3E%20arr.slice(init%2C%20end)%0A%7D
+    https://czosel.github.io/jexl-playground/#/?context=%7B%0A%20%20%22text%22%20%3A%20%22%20%20foobar%7B%7D%20%20%22%0A%7D&input=text%20%7C%20replacestr(%22foo%22%2C%22FOO%22)%7Ctrim%7Curlencode&transforms=%7B%0A%20%20%20%20jsonparse%3A%20(str)%20%3D%3E%20JSON.parse(str)%2C%0A%20%20%20%20jsonstringify%3A%20(obj)%20%3D%3E%20JSON.stringify(obj)%2C%0A%20%20%20%20indexOf%3A%20(val%2C%20char)%20%3D%3E%20String(val).indexOf(char)%2C%0A%20%20%20%20length%3A%20(val)%20%3D%3E%20String(val).length%2C%0A%20%20%20%20trim%3A%20(val)%20%3D%3E%20String(val).trim()%2C%0A%20%20%20%20substr%3A%20(val%2C%20int1%2C%20int2)%20%3D%3E%20String(val).substr(int1%2C%20int2)%2C%0A%20%20%20%20addreduce%3A%20(arr)%20%3D%3E%20arr.reduce((i%2C%20v)%20%3D%3E%20i%20%2B%20v)%2C%0A%20%20%20%20lengtharray%3A%20(arr)%20%3D%3E%20arr.length%2C%0A%20%20%20%20typeof%3A%20(val)%20%3D%3E%20typeof%20val%2C%0A%20%20%20%20isarray%3A%20(arr)%20%3D%3E%20Array.isArray(arr)%2C%0A%20%20%20%20isnan%3A%20(val)%20%3D%3E%20isNaN(val)%2C%0A%20%20%20%20parseint%3A%20(val)%20%3D%3E%20parseInt(val)%2C%0A%20%20%20%20parsefloat%3A%20(val)%20%3D%3E%20parseFloat(val)%2C%0A%20%20%20%20toisodate%3A%20(val)%20%3D%3E%20new%20Date(val).toISOString()%2C%0A%20%20%20%20timeoffset%3A%20(isostr)%20%3D%3E%20new%20Date(isostr).getTimezoneOffset()%2C%0A%20%20%20%20tostring%3A%20(val)%20%3D%3E%20val.toString()%2C%0A%20%20%20%20urlencode%3A%20(val)%20%3D%3E%20encodeURI(val)%2C%0A%20%20%20%20urldecode%3A%20(val)%20%3D%3E%20decodeURI(val)%2C%0A%20%20%20%20replacestr%3A%20(str%2C%20from%2C%20to)%20%3D%3E%20str.replace(from%2C%20to)%2C%0A%20%20%20%20replaceregexp%3A%20(str%2C%20reg%2C%20to)%20%3D%3E%20str.replace(new%20RegExp(reg)%2C%20to)%2C%0A%20%20%20%20replaceallstr%3A%20(str%2C%20from%2C%20to)%20%3D%3E%20str.replaceAll(from%2C%20to)%2C%0A%20%20%20%20replaceallregexp%3A%20(str%2C%20reg%2C%20to)%20%3D%3E%20str.replaceAll(new%20RegExp(reg%2C%20'g')%2C%20to)%2C%0A%20%20%20%20split%3A%20(str%2C%20ch)%20%3D%3E%20str.split(ch)%2C%0A%20%20%20%20joinarrtostr%3A%20(arr%2C%20ch)%20%3D%3E%20arr.join(ch)%2C%0A%20%20%20%20concatarr%3A%20(arr%2C%20arr2)%20%3D%3E%20arr.concat(arr2)%2C%0A%20%20%20%20mapper%3A%20(val%2C%20values%2C%20choices)%20%3D%3E%20choices%5Bvalues.findIndex((target)%20%3D%3E%20target%20%3D%3D%3D%20val)%5D%2C%0A%20%20%20%20thmapper%3A%20(val%2C%20values%2C%20choices)%20%3D%3E%0A%20%20%20%20%20%20%20%20choices%5B%0A%20%20%20%20%20%20%20%20%20%20%20%20values.reduce((acc%2C%20curr%2C%20i)%20%3D%3E%20(acc%20%3D%3D%3D%200%20%7C%7C%20acc%20%3F%20acc%20%3A%20val%20%3C%3D%20curr%20%3F%20(acc%20%3D%20i)%20%3A%20(acc%20%3D%20null))%2C%20null)%0A%20%20%20%20%20%20%20%20%5D%2C%0A%20%20%20%20bitwisemask%3A%20(i%2C%20mask%2C%20op%2C%20shf)%20%3D%3E%0A%20%20%20%20%20%20%20%20(op%20%3D%3D%3D%20'%26'%20%3F%20parseInt(i)%20%26%20mask%20%3A%20op%20%3D%3D%3D%20'%7C'%20%3F%20parseInt(i)%20%7C%20mask%20%3A%20op%20%3D%3D%3D%20'%5E'%20%3F%20parseInt(i)%20%5E%20mask%20%3A%20i)%20%3E%3E%0A%20%20%20%20%20%20%20%20shf%2C%0A%20%20%20%20slice%3A%20(arr%2C%20init%2C%20end)%20%3D%3E%20arr.slice(init%2C%20end)%2C%0A%20%20%20%20addset%3A%20(arr%2C%20x)%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20return%20Array.from(new%20Set(arr).add(x))%3B%0A%20%20%20%20%7D%2C%0A%20%20%20%20removeset%3A%20(arr%2C%20x)%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20let%20s%20%3D%20new%20Set(arr)%3B%0A%20%20%20%20%20%20%20%20s.delete(x)%3B%0A%20%20%20%20%20%20%20%20return%20Array.from(s)%3B%0A%20%20%20%20%7D%2C%0A%20%20%20%20touppercase%3A%20(val)%20%3D%3E%20String(val).toUpperCase()%2C%0A%20%20%20%20tolowercase%3A%20(val)%20%3D%3E%20String(val).toLowerCase()%2C%0A%20%20%20%20floor%3A%20(val)%20%3D%3E%20Math.floor(val)%2C%0A%20%20%20%20ceil%3A%20(val)%20%3D%3E%20Math.ceil(val)%2C%0A%20%20%20%20round%3A%20(val)%20%3D%3E%20Math.round(val)%2C%0A%20%20%20%20tofixed%3A%20(val%2C%20decimals)%20%3D%3E%20Number.parseFloat(val).toFixed(decimals)%2C%0A%20%20%20%20gettime%3A%20(d)%20%3D%3E%20new%20Date(d).getTime()%2C%0A%20%20%20%20toisostring%3A%20(d)%20%3D%3E%20new%20Date(d).toISOString()%2C%0A%20%20%20%20%2F%2F%20https%3A%2F%2Fdeveloper.mozilla.org%2Fes%2Fdocs%2FWeb%2FJavaScript%2FReference%2FGlobal_Objects%2FDate%2FtoLocaleString%0A%20%20%20%20localestring%3A%20(d%2C%20timezone%2C%20options)%20%3D%3E%20new%20Date(d).toLocaleString(timezone%2C%20options)%2C%0A%20%20%20%20now%3A%20()%20%3D%3E%20Date.now()%2C%0A%20%20%20%20hextostring%3A%20(val)%20%3D%3E%0A%20%20%20%20%20%20%20%20new%20TextDecoder().decode(new%20Uint8Array(val.match(%2F.%7B1%2C2%7D%2Fg).map((byte)%20%3D%3E%20parseInt(byte%2C%2016))))%2C%0A%20%20%20%20valuePicker%3A%20(val%2Cpick)%20%3D%3E%20Object.entries(val).filter((%5B%2C%20v%5D)%20%3D%3E%20v%20%3D%3D%3D%20pick).map((%5Bk%2C%5D)%20%3D%3E%20k)%2C%0A%20%20%20%20valuePickerMulti%3A%20(val%2Cpick)%20%3D%3E%20Object.entries(val).filter((%5B%2C%20v%5D)%20%3D%3E%20pick.includes(v)).map((%5Bk%2C%5D)%20%3D%3E%20k)%0A%7D

package/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,8 @@ 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 +851,100 @@ 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 +1038,30 @@ 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

package/doc/models/models.md

@@ -0,0 +1,260 @@
+# MongoDB Datamodel
+
+This file displays IoT Agent datamodel stored in the MongoDB database.
+
+## Collections
+
+### Devices
+
+The collection 'devices' sotres information about the iotagent devices
+
+Fields:
+
+-   **\_ID** _ObjectId_: unique object ID used by mongoDB
+-   **id** _string_: id of device
+-   **type** _string_: entity type used
+-   **name** _string_: entity name used
+-   **lazy** _array_: array of lazy attributes of device
+-   **active** _array_: array of active attributes of device
+-   **commands** _array_: array of commands of device
+-   **apikey** _string_: apikey of device
+-   **endpoint** _string_: endpoint used by push commands when http
+-   **resource** _string_: iotagent resource
+-   **protocol** _string_: device protocol (JSON)
+-   **transport** _string_: device transport (http, mqtt, amqp)
+-   **staticAttributes** _array_: array of static attributes of device
+-   **subscriptions** _array_: subscriptions of device
+-   **service** _string_: service which the device belongs to
+-   **subservice** _string_: subservice which the rule belongs to.
+-   **polling** _boolean_: if device uses polling for commands
+-   **timezone** _string_: timezone of device
+-   **timestamp** _boolean_ timestamp of device
+-   **registrationId** _string_: registrationId of device
+-   **internalId** _string_: internalId of device
+-   **creationDate** _date_: creationDate of device
+-   **internalAttributes** _object_: internalAttributes of device
+-   **autoprovision** _boolean_: if device support autoprovision
+-   **explicitAttrs** _enum_:
+-   **ngsiVersion** _string_: ngsi version used by device
+-   **payloadType** _string_: payloadType used by device
+-   **useCBflowControl** _boolean_: if CBFlow will be used by device when updates in CB
+-   **storeLastMeasure** _boolean_: if device store last measure received
+-   **lastMeasure** _object_: last measure received by device
+-   **oldCtxt** _object_: jexl Ctxt used at last measure
+
+Example:
+
+```json
+{
+    "_id": {
+        "$oid": "680b4b338d0e60f98718a8b2"
+    },
+    "lazy": [],
+    "commands": [
+        {
+            "name": "reset",
+            "type": "command",
+            "value": "",
+            "expression": "{ set: brand + '_' + reset }",
+            "object_id": "reset"
+        },
+        {
+            "name": "cmd1",
+            "type": "command",
+            "value": "",
+            "expression": "brand",
+            "object_id": "cmd1"
+        },
+        {
+            "name": "cmd2",
+            "type": "command",
+            "value": "",
+            "expression": "reset",
+            "object_id": "cmd2"
+        }
+    ],
+    "staticAttributes": [],
+    "creationDate": {
+        "$date": {
+            "$numberLong": "1745570611491"
+        }
+    },
+    "id": "disp",
+    "type": "thing",
+    "name": "thing:disp",
+    "service": "smartcity",
+    "subservice": "/",
+    "registrationId": "680b4b33956cc1ed0205840a",
+    "apikey": "APIKEY",
+    "protocol": "IoTA-JSON",
+    "transport": "HTTP",
+    "polling": false,
+    "active": [],
+    "oldCtxt": {
+        "level": "33",
+        "brand": "o1",
+        "id": "disp",
+        "type": "thing",
+        "service": "smartcity",
+        "subservice": "/",
+        "entity_name": "thing:disp",
+        "TimeInstant": "2025-04-25T08:43:31.496Z"
+    },
+    "subscriptions": []
+}
+```
+
+### Groups
+
+The collection groups' stores information about the iotagent groups of devices
+
+Fields:
+
+-   **\_ID** _ObjectId_: unique object ID used by mongoDB
+-   **url** _string_: url used by group of devices
+-   **resource** _string_: iotagent resource
+-   **apikey** _string_: apikey used by group of devices
+-   **endpoint** _string_: endpoint used by push commands when http
+-   **transport** _string_: group transport (http, mqtt, amqp)
+-   **type** _string_: entity type used
+-   **service** _string_: service which the group of device belongs to
+-   **subservice** _string_: subservice which the group of devices belongs to
+-   **description** _string_: description of group of devices
+-   **trust** _string_: keystone trust id used when devices of this group request to CB
+-   **cbHost** _string_: CB endpoint used by devices of this group
+-   **timezone** _string_: timezone used by group of devices
+-   **timestamp** _boolean_: timestamp of group
+-   **commands** _array_: array of commands of device group
+-   **staticAttributes** _array_: array of static attributes of device group
+-   **lazy** _array_: array of lazy attributes of device group
+-   **attributes** _array_: array of active attributes of device group
+-   **internalAttributes** _array_: array of internal attributes used by devices of group
+-   **autoprovision** _boolean_: if devices of group supports autoprovision
+-   **explicitAttrs** _enum_: explicit attributes configuration used by devices of group
+-   **defaultEntityNameConjunction** _string_:
+-   **ngsiVersion** _string_: ngsi version used by devices of group
+-   **entityNameExp** _string_: entity name expression used by devics of group
+-   **payloadType** _string_: payloadType used by devices of group
+-   **useCBflowControl** _boolean_: payloadType used by device group
+-   **storeLastMeasure** _boolean_: if devices of group store last measure received
+
+Example:
+
+```json
+{
+    "_id": {
+        "$oid": "67a1e6447ae8b4ba4478f019"
+    },
+    "commands": [
+        {
+            "name": "reset",
+            "type": "command",
+            "value": "",
+            "expression": "{ set: brand + '_' + reset }"
+        },
+        {
+            "name": "cmd1",
+            "type": "command",
+            "value": "",
+            "expression": "brand"
+        },
+        {
+            "name": "cmd2",
+            "type": "command",
+            "value": "",
+            "expression": "reset"
+        }
+    ],
+    "staticAttributes": [
+        {
+            "name": "brand",
+            "type": "Text",
+            "value": "o1",
+            "metadata": {}
+        }
+    ],
+    "attributes": [],
+    "resource": "/iot/json",
+    "apikey": "APIKEY",
+    "type": "thing",
+    "service": "smartcity",
+    "subservice": "/",
+    "description": "miJSON",
+    "timestamp": true,
+    "internalAttributes": [],
+    "lazy": [],
+    "transport": "HTTP",
+    "endpoint": "'https://eoykcmmm.m.pipedream.net' + '/' + service + '/' + subservice + '/' + id + '/' + type"
+}
+```
+
+### Commands
+
+The collection 'commands' stores information about the commands
+
+Fields:
+
+-   **\_ID** _ObjectId_: unique object ID used by mongoDB
+-   **deviceId** _string_: device ID of the device
+-   **type** _string_: type of the command
+-   **name** _string_: name of the command
+-   **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:
+
+```json
+{
+    "_id": {
+        "$oid": "680b4b538d0e60f98718a8eb"
+    },
+    "creationDate": {
+        "$date": {
+            "$numberLong": "1745570643252"
+        }
+    },
+    "name": "cmd1",
+    "type": "command",
+    "value": "on",
+    "deviceId": "disp3",
+    "service": "smartcity",
+    "subservice": "/"
+}
+```
+
+## Indexes
+
+### Devices
+
+An index guarantees that every device is identified by the tuple (service, subservice, apikey, id)
+
+The index is created/ensured when iotagent starts, but it can be created from a mongoDB shell with
+
+```javascript
+db.devices.ensureIndex({ service: 1, subservice: 1, apikey: 1, id: 1 }, { unique: true });
+```
+
+### Groups
+
+An index guarantees that every group is identified by the tuple (apikey, resource)
+
+The index is created/ensured when iotagent starts, but it can be created from a mongoDB shell with
+
+```javascript
+db.groups.ensureIndex({ apikey: 1, resource: 1 }, { unique: true });
+```
+
+### Commands
+
+None index is defined

package/doc/requirements.txt

@@ -1,4 +1,4 @@
 mkdocs==1.2.4
 Pygments==2.15.0
 Markdown==3.3.4
-jinja2==3.1.5
+jinja2==3.1.6

package/docker/Mosquitto/Dockerfile

@@ -1,4 +1,4 @@
-ARG  IMAGE_TAG=12.6-slim
+ARG  IMAGE_TAG=12.10-slim
 FROM debian:${IMAGE_TAG}
 
 ARG CLEAN_DEV_TOOLS

package/lib/fiware-iotagent-lib.js

@@ -47,17 +47,20 @@ const context = {
 
 /* eslint-disable-next-line  no-unused-vars */
 function activateStatLogs(newConfig, callback) {
-    async.series([
-        apply(statsRegistry.globalLoad, {
-            deviceCreationRequests: 0,
-            deviceRemovalRequests: 0,
-            measureRequests: 0,
-            raiseAlarm: 0,
-            releaseAlarm: 0,
-            updateEntityRequestsOk: 0,
-            updateEntityRequestsError: 0
-        })
-    ], callback);
+    async.series(
+        [
+            apply(statsRegistry.globalLoad, {
+                deviceCreationRequests: 0,
+                deviceRemovalRequests: 0,
+                measureRequests: 0,
+                raiseAlarm: 0,
+                releaseAlarm: 0,
+                updateEntityRequestsOk: 0,
+                updateEntityRequestsError: 0
+            })
+        ],
+        callback
+    );
 }
 
 /**
@@ -314,6 +317,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;