Merge pull request #1416 from telefonicaid/fgalan-patch-1

Deprecate bidirectional plugin and appendMode
telefonicaid · Aug 24, 2023 · 6401a67 · 6401a67
2 parents f71e738 + 18e31f9
commit 6401a67
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 161 deletions.
diff --git a/CHANGES_NEXT_RELEASE b/CHANGES_NEXT_RELEASE
@@ -9,3 +9,5 @@
 - Fix: do not propagate group config (timestamp and explicitAttrs) to autoprovisioned devices (at database level) (#1377)
 - Fix: appendMode at general level (config.js / env var) changes its default from false to true
 - Fix: remove sensitive MongoDB connection parameters from log traces (remove 'option' object from logs)
+- Deprecate: bidirectional plugin
+- Deprecate: appendMode
diff --git a/config.js b/config.js
@@ -76,8 +76,7 @@ var config = {
     subservice: '/gardens',
     providerUrl: 'http://192.168.56.1:4041',
     deviceRegistrationDuration: 'P1M',
-    defaultType: 'Thing',
-    appendMode: true
+    defaultType: 'Thing'
 };
 
 module.exports = config;
diff --git a/doc/api.md b/doc/api.md
@@ -19,8 +19,7 @@
     -   [Measurement persistence options](#measurement-persistence-options)
         -   [Autoprovision configuration (autoprovision)](#autoprovision-configuration-autoprovision)
         -   [Explicitly defined attributes (explicitAttrs)](#explicitly-defined-attributes-explicitattrs)
-        -   [Configuring operation to persist the data in Context Broker (appendMode)](#configuring-operation-to-persist-the-data-in-context-broker-appendmode)
-        -   [Differences between `autoprovision`, `explicitAttrs` and `appendMode`](#differences-between-autoprovision-explicitattrs-and-appendmode)
+        -   [Differences between `autoprovision`, `explicitAttrs`](#differences-between-autoprovision-explicitattrs)
     -   [Expression language support](#expression-language-support)
         -   [Examples of JEXL expressions](#examples-of-jexl-expressions)
         -   [Available functions](#available-functions)
@@ -31,7 +30,6 @@
         -   [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id)
     -   [Timestamp Compression](#timestamp-compression)
     -   [Timestamp Processing](#timestamp-processing)
-    -   [Bidirectionality plugin (bidirectional)](#bidirectionality-plugin-bidirectional)
     -   [Overriding global Context Broker host](#overriding-global-context-broker-host)
     -   [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath)
     -   [Secured access to the Context Broker](#secured-access-to-the-context-broker)
@@ -143,9 +141,9 @@ described in the [Device datamodel](#device-datamodel) section.
 
 If devices are not pre-registered, they will be automatically created when a measure arrives to the IoT Agent - this
 process is known as autoprovisioning. The IoT Agent will create an empty device with the group `apiKey` and `type` - the
-associated document created in database doesn't include config group parameters (in particular, `timestamp`, `explicitAttrs`,
-`active` or `attributes`, `static` and `lazy` attributes and commands). The IoT Agent will also create the entity in the
-Context Broker if it does not exist yet.
+associated document created in database doesn't include config group parameters (in particular, `timestamp`,
+`explicitAttrs`, `active` or `attributes`, `static` and `lazy` attributes and commands). The IoT Agent will also create
+the entity in the Context Broker if it does not exist yet.
 
 This behavior allows that autoprovisioned parameters can freely established modifying the device information after
 creation using the provisioning API. However, note that if a device (autoprovisioned or not) doesn't have these
@@ -200,8 +198,6 @@ Some transformation plugins also allow the use of the following optional fields:
     with the `entity_type` attribute. If no type is configured, the device entity type is used instead. Entity names can
     be defined as expressions, using the [Expression Language definition](#expression-language-support).
 -   **entity_type**: configures the type of an alternative entity.
--   **reverse**: add bidirectionality expressions to the attribute. See the **bidirectionality** transformation plugin
-    in the [Data Mapping Plugins section](development.md#bidirectionality-plugin-bidirectional) for details.
 
 Additionally for commands (which are attributes of type `command`) the following fields are optional:
 
@@ -371,15 +367,13 @@ used should be taken from those defined by
 
 ## Measurement persistence options
 
-There are 3 different options to configure how the IoTAgent stores the measures received from the devices, depending on
+There are 2 different options to configure how the IoTAgent stores the measures received from the devices, depending on
 the following parameters:
 
 -   `autoprovision`: If the device is not provisioned, the IoTAgent will create a new device and entity for it.
 -   `explicitAttrs`: If the measure element (object_id) is not defined in the mappings of the device or config group
     provision, the measure is stored in the Context Broker by adding a new attribute to the entity with the same name of
     the undefined measure element.
--   `appendMode`: It configures the request to the Context Broker to update the entity every time a new measure arrives.
-    It have implications depending if the entity is already created or not in the Context Broker.
 
 ### Autoprovision configuration (autoprovision)
 
@@ -452,29 +446,7 @@ depending on the JEXL expression evaluation:
 -   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)
 
-### Configuring operation to persist the data in Context Broker (appendMode)
-
-This is a flag that can be enabled by activating the parameter `appendMode` in the configuration file or by using the
-`IOTA_APPEND_MODE` environment variable (more info
-[here](https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/installationguide.md)). If this flag is
-activated (its default behaviour), the update requests to the Context Broker will be performed always with APPEND type,
-instead of the default UPDATE. This have implications in the use of attributes with Context Providers, so this flag
-should be used with care.
-
-When running the agent using `appendMode=false`, if sending measures that are not included in the config group (as
-active measures), the IoT Agent returns a `422 Unprocessable Entity` code with the following message:
-
-```json
-{
-    "name": "ENTITY_GENERIC_ERROR",
-    "message": "Error accesing entity data for device: deviceType:dev of type: deviceType"
-}
-```
-
-Additionally, the agent creates the device and the corresponding entity in the broker if `autoprovision==true` (default
-behaviour).
-
-### Differences between `autoprovision`, `explicitAttrs` and `appendMode`
+### Differences between `autoprovision`, `explicitAttrs`
 
 Since those configuration parameters are quite similar, this section is intended to clarify the relation between them.
 
@@ -486,16 +458,6 @@ related to the **southbound**.
 What `explicitAttrs` does is to filter from the southbound the parameters that are not explicitly defined in the device
 provision or config group. That also would avoid propagating the measures to the Context Broker.
 
-The default way the agent updates the information into the Context Broker is by using an update request. If
-`appendMode=true` (the default behaviour), the IoTA will use an append request instead of an update one. This means it
-will store the attributes even if they are not present in the entity. This seems the same functionality that the one
-provided by `autoprovision`, but it is a different concept since the scope of this config is to setup how the IoT
-interacts with the context broker, this is something related to the **northbound**.
-
-Note that, even creating a config group with `autoprovision=true` and `explicitAttrs=true`, if you do not provision
-previously the entity in the Context Broker (having all attributes to be updated), it would fail if `appendMode=false`.
-For further information check the issue [#1301](https://github.com/telefonicaid/iotagent-node-lib/issues/1301).
-
 ## Expression language support
 
 The IoTAgent Library provides an expression language for measurement transformation and other purposes. This expression
@@ -887,54 +849,6 @@ The IOTA processes the entity attributes looking for a `TimeInstant` attribute.
 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.
 
-## Bidirectionality plugin (bidirectional)
-
-This plugin allows the devices with composite values an expression to update the original values in the devices when the
-composite expressions are updated in the Context Broker. This behavior is achieved through the use of subscriptions.
-
-IoTAs using this plugins should also define a notification handler to handle incoming values. This handler will be
-intercepted by the plugin, so the mapped values are included in the updated notification.
-
-When a device is provisioned with bidirectional attributes, the IoTAgent subscribes to changes in that attribute. When a
-change notification for that attribute arrives to the IoTA, it applies the transformation defined in the device
-provisioning payload to the notification, and calls the underlying notification handler with the transformed entity
-including the `value` along with any `metadata`, and in the case of an NGSI-LD bidirectional attribute a `datasetId` if
-provided.
-
-The following `attributes` section shows an example of the plugin configuration (using `IOTA_AUTOCAST=false` to avoid
-translation from geo:point to geo:json)
-
-```json
-      "attributes": [
-        {
-          "name":"location",
-          "type":"geo:point",
-          "expression": "latitude, longitude",
-          "reverse": [
-            {
-              "object_id":"longitude",
-              "type": "Number",
-              "expression": "location | split(', ')[0] | parsefloat()"
-            },
-            {
-              "object_id":"latitude",
-              "type": "Number",
-              "expression": "location | split(', ')[1] | parsefloat()"
-            }
-          ]
-        }
-      ],
-```
-
-For each attribute that would have bidirectionality, a new field `reverse` must be configured. This field will contain
-an array of fields that will be created based on the notifications content. The expression notification can contain any
-attribute of the same entity as the bidirectional attribute; declaring them in the expressions will add them to the
-subscription payload.
-
-For each attribute in the `reverse` array, an expression must be defined to calculate its value based on the
-notification attributes. This value will be passed to the underlying protocol with the `object_id` name. Details about
-how the value is then progressed to the device are protocol-specific.
-
 ## Overriding global Context Broker host
 
 **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types

diff --git a/doc/deprecated.md b/doc/deprecated.md
@@ -22,6 +22,8 @@ A list of deprecated features and the version in which they were deprecated foll
 -   Support groups (provision) statically defined by configuration
 -   Support to in-memory registry (i.e.`deviceRegistry.type=memory`)
 -   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)
 
 The use of Node.js v14 is highly recommended.
 
@@ -51,3 +53,5 @@ The following table provides information about the last iotagent-node-lib versio
 | 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                                                  | To be defined                 |
+| appendMode | 3.3.0                                                             | To be defined                 |