iotagent-node-lib 3.3.0 → 3.4.0

package/doc/api.md

@@ -56,7 +56,7 @@
     -   [Miscellaneous API](#miscellaneous-api)
         -   [Log operations](#log-operations)
             -   [Modify Loglevel `PUT /admin/log`](#modify-loglevel-put-adminlog)
-            -   [Retrieve log level `PUT /admin/log`](#retrieve-log-level-put-adminlog)
+            -   [Retrieve log level `GET /admin/log`](#retrieve-log-level-get-adminlog)
         -   [About operations](#about-operations)
             -   [List IoTA Information `GET /iot/about`](#list-iota-information-get-iotabout)
 
@@ -183,7 +183,7 @@ All of them have the same syntax, a list of objects with the following attribute
 -   **type** (mandatory): name of the type of the attribute in the target entity.
 -   **metadata** (optional): additional static metadata for the attribute in the target entity. (e.g. `unitCode`)
 
-Some transformation plugins also allow the use of the following optional fields:
+Some advanced features also allow the use of the following optional fields:
 
 -   **expression**: indicates that the value of the target attribute will not be the plain value or the measurement, but
     an expression based on a combination of the reported values. See the
@@ -674,6 +674,10 @@ will check which ones contain expressions whose variables are present in the rec
 whose variables are covered, their expressions will be executed with the received values, and their values updated in
 the Context Broker.
 
+If as a result of apply expression `undefined` or `null` value is obtained then any of them will not progress to entity
+attribute. Have into acount that some numeric operations results (like nonexistent \* 2) are a kind of null with a
+number type but NaN value, which will also not progress to entity attribute.
+
 E.g.: if a device with the following provisioning information is created in the IoT Agent:
 
 ```json
@@ -751,7 +755,7 @@ following to CB:
 
 ### Multientity measurement transformation support (`object_id`)
 
-To allow support for measurement transformation in combination with multi entity plugin, where the same attribute is
+To allow support for measurement transformation in combination with multi entity feature, where the same attribute is
 generated for different entities out of different incoming attribute values (i.e. `object_id`), we introduced support
 for `object_id` in the expression context.
 
@@ -845,7 +849,7 @@ it in queries (and viceversa, receive the extended one in queries and return it
 
 ## Timestamp Processing
 
-The IOTA processes the entity attributes looking for a `TimeInstant` attribute. If one is found, for NGSI v2, the plugin
+The IOTA processes the entity attributes looking for a `TimeInstant` attribute. If one is found, for NGSI v2, then it
 adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the Standard
 `observedAt` property-of-a-property is used instead.
 
@@ -1609,7 +1613,7 @@ _**Response code**_
 -   `200` `OK` if successful.
 -   `500` `SERVER ERROR` if there was any error not contemplated above.
 
-#### Retrieve log level `PUT /admin/log`
+#### Retrieve log level `GET /admin/log`
 
 _**Response code**_
 

package/doc/deprecated.md

@@ -21,9 +21,10 @@ A list of deprecated features and the version in which they were deprecated foll
 -   Support to NGSI-LD v1.3 in iotagent-node-lib 2.25.0 (finally removed in 2.26.0)
 -   Support groups (provision) statically defined by configuration
 -   Support to in-memory registry (i.e.`deviceRegistry.type=memory`)
+-   eventType configuration (finally removed in 3.0.0)
 -   Support to legacy expressions (finally removed in 3.2.0)
--   Bidirectinal pluging (to be removed in 3.4.0)
--   appendMode (to be removed in 3.4.0)
+-   Bidirectinal pluging (finally removed in 3.4.0)
+-   appendMode configuration (`IOTA_APPEND_MODE` env var) (finally removed in 3.4.0)
 
 The use of Node.js v14 is highly recommended.
 
@@ -43,15 +44,16 @@ information in the case you want to use old versions:
 
 The following table provides information about the last iotagent-node-lib version supporting currently removed features:
 
-| **Removed feature**    | **Last iotagent-node-lib version supporting feature** | **That version release date** |
-| ---------------------- | ----------------------------------------------------- | ----------------------------- |
-| NGSI v1 API            | 2.17.0                                                | August 30th, 2021             |
-| Support to Node.js v4  | 2.8.1                                                 | December 19th, 2018           |
-| Support to Node.js v6  | 2.9.0                                                 | May 22nd, 2019                |
-| Support to Node.js v8  | 2.12.0                                                | April 7th, 2020               |
-| Support to Node.js v10 | 2.15.0                                                | February 18th, 2021           |
-| Support to Node.js v12 | 2.24.0                                                | September 2nd, 2022           |
-| Support to NGSI-LD 1.3 | 2.25.0                                                | January 24th, 2023            |
-| Support to Legacy Expressions | 3.1.0                                          | April 25th, 2023              |
-| bidirrectional plugin | 3.3.0                                                  | August 24th, 2023             |
-| appendMode | 3.3.0                                                             | August 24th, 2023             |
+| **Removed feature**                                   | **Last iotagent-node-lib version supporting feature** | **That version release date** |
+| ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------- |
+| NGSI v1 API                                           | 2.17.0                                                | August 30th, 2021             |
+| Support to Node.js v4                                 | 2.8.1                                                 | December 19th, 2018           |
+| Support to Node.js v6                                 | 2.9.0                                                 | May 22nd, 2019                |
+| Support to Node.js v8                                 | 2.12.0                                                | April 7th, 2020               |
+| Support to Node.js v10                                | 2.15.0                                                | February 18th, 2021           |
+| Support to Node.js v12                                | 2.24.0                                                | September 2nd, 2022           |
+| Support to NGSI-LD 1.3                                | 2.25.0                                                | January 24th, 2023            |
+| eventType configuration                               | 2.26.0                                                | March 15th, 2023              |
+| Support to Legacy Expressions                         | 3.1.0                                                 | April 25th, 2023              |
+| bidirectional plugin                                  | 3.3.0                                                 | August 24th, 2023             |
+| appendMode configuration (`IOTA_APPEND_MODE` env var) | 3.3.0                                                 | August 24th, 2023             |

package/doc/{architecture.md → devel/architecture.md}

@@ -1,6 +1,6 @@
 ## Architecture
 
-The following section defines the archtecture and message flow which is common to all IoT Agents which use the library.
+The following section defines the architecture and message flow which is common to all IoT Agents which use the library.
 
 ### Device to NGSI Mapping
 
@@ -32,7 +32,7 @@ basis preprovisioning the devices). Device measures can have three different beh
 The following sequence diagram shows the different NGSI interactions an IoT Agent makes with the Context Broker,
 explained in the following subsections (using the example of a OMA Lightweight M2M device).
 
-![General ](./img/ngsiInteractions.png "NGSI Interactions")
+![General ](../img/ngsiInteractions.png 'NGSI Interactions')
 
 Be aware that the IoT Agents are only required to support NGSI10 operations `updateContext` and `queryContext` in their
 standard formats (currently in JSON format; XML deprecated) but will not answer to NGSI9 operations (or NGSI convenience
@@ -254,7 +254,7 @@ the concrete IoT Agent implementations will be to map between the native device
 The following figure offers a graphical example of how a COAP IoT Agent work, ordered from the registration of the
 device to a command update to the device.
 
-![General ](./img/iotAgentLib.png "Architecture Overview")
+![General ](../img/iotAgentLib.png 'Architecture Overview')
 
 ### The `TimeInstant` element
 

package/doc/{Contribution.md → devel/contribution-guidelines.md}

@@ -4,21 +4,22 @@
 
 Before we get started, here are a few things we expect from you (and that you should expect from others):
 
-* Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and
-  projects, which means we likely have different perspectives on "how open source is done." Try to listen to others
-  rather than convince them that your way is correct.
-* Please ensure that your contribution passes all tests. If there are test failures, you will need to address them
-  before we can merge your contribution.
-* When adding content, please consider if it is widely valuable. Please don't add references or links to things you or
-  your employer have created as others will do so if they appreciate it.
-* When reporting a vulnerability on the software, please, put in contact with IoT Agent Node Lib repository maintainers in order to discuss it 
-  in a private way.
+-   Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and
+    projects, which means we likely have different perspectives on "how open source is done." Try to listen to others
+    rather than convince them that your way is correct.
+-   Please ensure that your contribution passes all tests. If there are test failures, you will need to address them
+    before we can merge your contribution.
+-   When adding content, please consider if it is widely valuable. Please don't add references or links to things you or
+    your employer have created as others will do so if they appreciate it.
+-   When reporting a vulnerability on the software, please, put in contact with IoT Agent Node Lib repository
+    maintainers in order to discuss it in a private way.
 
 ## How to contribute
 
-If you'd like to contribute, start by searching through the [issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and
-[pull requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) to see whether someone else has raised a similar idea or
-question.
+If you'd like to contribute, start by searching through the
+[issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and
+[pull requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) to see whether someone else has raised a
+similar idea or question.
 
 If you don't see your idea listed, and you think it fits into the goals of this guide, do one of the following:
 
@@ -28,36 +29,43 @@ If you don't see your idea listed, and you think it fits into the goals of this
 
 ### Pull Request protocol
 
-As explained in ([FIWARE Contribution Requirements](https://fiware-requirements.readthedocs.io/en/latest)) 
-contributions are done using a pull request (PR). The detailed "protocol" used in such PR is described below:
-
-* Direct commits to master branch (even single-line modifications) are not allowed. Every modification has to come as a PR
-* In case the PR is implementing/fixing a numbered issue, the issue number has to be referenced in the body of the PR at creation time
-* Anybody is welcome to provide comments to the PR (either direct comments or using the review feature offered by GitHub)
-* Use *code line comments* instead of *general comments*, for traceability reasons (see comments lifecycle below)
-* Comments lifecycle
-  * Comment is created, initiating a *comment thread*
-  * New comments can be added as responses to the original one, starting a discussion
-  * After discussion, the comment thread ends in one of the following ways:
-    * `Fixed in <commit hash>` in case the discussion involves a fix in the PR branch (which commit hash is 
-       included as reference)
-    * `NTC`, if finally nothing needs to be done (NTC = Nothing To Change)
- * PR can be merged when the following conditions are met:
-    * All comment threads are closed
-    * All the participants in the discussion have provided a `LGTM` general comment (LGTM = Looks good to me)
- * Self-merging is not allowed (except in rare and justified circumstances)
+As explained in ([FIWARE Contribution Requirements](https://fiware-requirements.readthedocs.io/en/latest)) contributions
+are done using a pull request (PR). The detailed "protocol" used in such PR is described below:
+
+-   Direct commits to master branch (even single-line modifications) are not allowed. Every modification has to come as
+    a PR
+-   In case the PR is implementing/fixing a numbered issue, the issue number has to be referenced in the body of the PR
+    at creation time
+-   Anybody is welcome to provide comments to the PR (either direct comments or using the review feature offered by
+    GitHub)
+-   Use _code line comments_ instead of _general comments_, for traceability reasons (see comments lifecycle below)
+-   Comments lifecycle
+    -   Comment is created, initiating a _comment thread_
+    -   New comments can be added as responses to the original one, starting a discussion
+    -   After discussion, the comment thread ends in one of the following ways:
+        -   `Fixed in <commit hash>` in case the discussion involves a fix in the PR branch (which commit hash is
+            included as reference)
+        -   `NTC`, if finally nothing needs to be done (NTC = Nothing To Change)
+-   PR can be merged when the following conditions are met:
+    -   All comment threads are closed
+    -   All the participants in the discussion have provided a `LGTM` general comment (LGTM = Looks good to me)
+-   Self-merging is not allowed (except in rare and justified circumstances)
 
 Some additional remarks to take into account when contributing with new PRs:
 
-* PR must include not only code contributions, but their corresponding pieces of documentation (new or modifications to existing one) and tests
-* PR modifications must pass full regression based on existing test (unit, functional, memory, e2e) in addition to whichever new test added due to the new functionality
-* PR should be of an appropriated size that makes review achievable. Too large PRs could be closed with a "please, redo the work in smaller pieces" without any further discussing
+-   PR must include not only code contributions, but their corresponding pieces of documentation (new or modifications
+    to existing one) and tests
+-   PR modifications must pass full regression based on existing test (unit, functional, memory, e2e) in addition to
+    whichever new test added due to the new functionality
+-   PR should be of an appropriated size that makes review achievable. Too large PRs could be closed with a "please,
+    redo the work in smaller pieces" without any further discussing
 
 ## Community
 
 Discussions about the Open Source Guides take place on this repository's
-[Issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and [Pull Requests](https://github.com/telefonicaid/iotagent-node-lib/pulls)
-sections. Anybody is welcome to join these conversations.
+[Issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and
+[Pull Requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) sections. Anybody is welcome to join these
+conversations.
 
 Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly.