Merge pull request #1437 from telefonicaid/task/doc-rework-removed-de…

…precated

Review the whole documentation in order to remove deprecated / removed features

README.md

@@ -46,8 +46,6 @@ functions.
     communications are left to the library.
 -   Standardized OAuth2-based security is available to enable each IoT Agent to connect to several common Identity
     Managers (e.g. Keystone and Keyrock) so that communications can be restricted to trusted components.
--   A series of additional plugins are offered where necessary to allow for expression parsing, attribute aliasing and
-    the processing of timestamp metadata.
 
 Each individual IoT Agent offers is driven by a `config.js` configuration file contains explicit custom settings based
 on the protocol and payload the IoT Agent is translating. It will also contain some common flags for common

doc/admin.md

@@ -11,12 +11,10 @@
         -   [mongodb](#mongodb)
         -   [iotManager](#iotmanager)
         -   [types](#types)
-        -   [eventType](#eventtype)
         -   [service](#service)
         -   [subservice](#subservice)
         -   [providerUrl](#providerurl)
         -   [iotaVersion](#iotaversion)
-        -   [appendMode](#appendmode)
         -   [dieOnUnexpectedError](#dieonunexpectederror)
         -   [singleConfigurationMode](#singleconfigurationmode)
         -   [timestamp](#timestamp)
@@ -324,10 +322,6 @@ added `agentPath`:
 
 See **Type Configuration** in the [Configuration API](#configurationapi) section below.
 
-#### `eventType`
-
-Default type for the Events (useful only with the `addEvents` plugin).
-
 #### `service`
 
 Default service for the IoT Agent. If a device is being registered, and no service information comes with the device
@@ -350,12 +344,6 @@ URL to send in the Context Provider registration requests. Should represent the
 indicates the version of the IoTA that will be displayed in the about method (it should be filled automatically by each
 IoTA).
 
-#### `appendMode`
-
-if this flag is activated, 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. This flag is overwritten by `autoprovision` flag in group or device provision.
-
 #### `dieOnUnexpectedError`
 
 if this flag is activated, the IoTAgent will not capture global exception, thus dying upon any unexpected error.
@@ -496,7 +484,6 @@ overrides.
 | IOTA_MONGO_SSL                       | `mongodb.ssl`                   |
 | IOTA_MONGO_EXTRAARGS                 | `mongodb.extraArgs`             |
 | IOTA_SINGLE_MODE                     | `singleConfigurationMode`       |
-| IOTA_APPEND_MODE                     | `appendMode`                    |
 | IOTA_POLLING_EXPIRATION              | `pollingExpiration`             |
 | IOTA_POLLING_DAEMON_FREQ             | `pollingDaemonFrequency`        |
 | IOTA_AUTOCAST                        | `autocast`                      |

doc/api.md

@@ -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
@@ -751,7 +751,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 +845,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.
 

doc/devel/development.md

@@ -26,9 +26,6 @@
 -   [DB Models from API document](#db-models-from-api-document)
     -   [Service group model](#service-group-model)
     -   [Device model](#device-model)
--   [Data mapping plugins](#data-mapping-plugins)
-    -   [Plugins usage](#plugins-usage)
-    -   [Provided plugins](#provided-plugins)
 -   [Developing a new IoT Agent](#developing-a-new-iot-agent)
     -   [Protocol](#protocol)
     -   [Requirements](#requirements)
@@ -1160,7 +1157,7 @@ Stores the information about the IoTAgent for further use in the `retrieveVersio
 ## DB Models (from API document)
 
 > **WARNING** This section is outdated. DB fields described here may be outdated and not reflect the current
-> implementation of the IoT Agent Library. 
+> implementation of the IoT Agent Library.
 
 The following sections describe the models used in the database to store the information about the devices and the
 config groups.
@@ -1188,7 +1185,6 @@ You can find the description of the fields in the config group datamodel of the
 | `attributes`                   | `attributes`                   |                                                                                                                                                   |
 | `static_attributes`            | `staticAttributes`             |                                                                                                                                                   |
 | `internal_attributes`          | `internalAttributes`           |                                                                                                                                                   |
-| `expressionLanguage`           | `expresionLanguage`            | _Removed_                                                                                                                                         |
 | `explicitAttrs`                | `explicitAttrs`                |                                                                                                                                                   |
 | `entityNameExp`                | `entityNameExp`                |                                                                                                                                                   |
 | `ngsiVersion`                  | `ngsiVersion`                  |                                                                                                                                                   |
@@ -1221,71 +1217,9 @@ You can find the description of the fields in the config group datamodel of the
 | `commands`            | `commands`           |                                                                                                                                      |
 | `internal_attributes` | `internalAttributes` | List of internal attributes with free format for specific IoT Agent configuration. I.E:LWM2M mappings from object URIs to attributes |
 | `static_attributes`   | `staticAttributes`   |                                                                                                                                      |
-| `expressionLanguage`  | `expresionLanguage`  | _Removed_                                                                                                                            |
 | `explicitAttrs`       | `explicitAttrs`      |                                                                                                                                      |
 | `ngsiVersion`         | `ngsiVersion`        |                                                                                                                                      |
 
-## Data mapping plugins
-
-The IoT Agent Library provides a plugin mechanism in order to facilitate reusing code that makes small transformations
-on incoming data (both from the device and from the context consumers). This mechanism is based in the use of
-middlewares, i.e.: small pieces of code that receive and return an `entity`, making as many changes as they need, but
-taking care of returning a valid entity, that can be used as the input for other middlewares; this way, all those pieces
-of code can be chained together in order to make all the needed transformations in the target entity.
-
-There are two kinds of middlewares: updateContext middlewares and queryContext middlewares. The updateContext
-middlewares are applied before the information is sent to the Context Broker, modifiying the entity before it is sent to
-Orion. The queryContext middlewares are applied on the received data, whenever the IoT Agent queries the Context Broker
-for information. I.e.: both middlewares will be automatically applied whenever the `update()` or `query()` functions are
-called in the library.
-
-All the middlewares have the opportunity to break the chain of middleware applications by calling the `callback()` with
-an error object (the usual convention). If any of the updateContext middlewares raise an error, no request will be sent
-to the Context Broker. On the other hand, the queryContext request is always performed, but the call to the `query()`
-function will end up in an error if any of the queryContext middlewares report an error.
-
-### Plugins usage
-
-All the middlewares have the same signature:
-
-```javascript
-function middlewareName(entity, typeInformation, callback) {}
-```
-
-The arguments for any middleware are the NGSI data over which it can operate:
-
--   An updateContext payload in the case of an updateContext middleware and a queryContext payload otherwise;
--   a typeInformation object containing all the information about the device stored during registration.
--   and the customary `callback` parameter, with the usual meaning. It's really important for the library user to call
-    this callback, as failing to do so may hang the IoT Agent completely. The callback must be called with the an
-    optional error in the first argument and the same arguments received (potentially modified) as the following.
-
-In order to manage the middlewares to the system, the following functions can be used:
-
--   `addUpdateMiddleware`: adds an updateContext middleware to the stack of middlewares. All the middlewares will be
-    applied to every call to the `update()` function. The final payload of the updateContext request will be the result
-    of applying all this middlewares in the order they have been defined.
-
--   `addQueryMiddleware`: adds a queryContext middleware to the stack of middlewares. All the middlewares will be
-    applied to every call to the `query()` function.
-
--   `resetMiddlewares`: remove all the middlewares from the system.
-
-Usually, the full list of middlewares an IoT Agent will use would be added in the IoTAgent start sequence, so they
-should not change a lot during the IoT lifetime.
-
-### Provided plugins
-
-The library provides some plugins out of the box, in the `dataPlugins` collection. In order to load any of them, just
-use the `addQueryMiddleware` and `addUpdateMiddleware` functions with the selected plugin, as in the example:
-
-```javascript
-var iotaLib = require('iotagent-node-lib');
-
-iotaLib.addUpdateMiddleware(iotaLib.dataPlugins.compressTimestamp.update);
-iotaLib.addQueryMiddleware(iotaLib.dataPlugins.compressTimestamp.query);
-```
-
 ## Developing a new IoT Agent
 
 > **WARNING** This section is outdated. Methods and steps described here may be outdated and not reflect the current
@@ -1848,10 +1782,6 @@ request/seconds that can be manage by the server. It's important to remark that
 included in the IoT Agent Node Lib but it is not mandatory that you activate this functionality. In this example, we
 will see how to use this functionality to deploy an IoT Agent in multi-thread environment.
 
-**WARNING:** it has been observed in Orion-IOTA integration tests some fails in bidirectional plugin usage scenarios in
-multi-thread mode. The fail has not been confirmed yet (it could be a glitch of the testing environment). However, take
-this into account if you use multi-thread in combination with bidirectional plugin.
-
 In order to activate the functionality, you have two options, configure the `config.js` file to add the following line:
 
 ```javascript

doc/devel/northboundinteractions.md

@@ -145,7 +145,7 @@ This **NGSI-v2** payload is associated to an update operation (POST `/v2/op/upda
             }
         }
     ],
-    "actionType": "update"
+    "actionType": "append"
 }
 ```
 
@@ -155,9 +155,8 @@ As it can be seen in the example, the payload is a JSON Object with the followin
     with the information needed to identify the target entity `id` and `type` attributes. The `entities` attribute is an
     array, so a single update context batch operation can be used to update multiple devices
 
--   An `actionType` indicating the type of update: if this attribute has the value `"append"` the appropriate entity and
-    attributes will be created if the don't exist; if the value is `"update"`, an error will be thrown if the target
-    resources don't exist.
+-   An `actionType` indicating the type of update. It has the value `"append"` the appropriate entity and attributes
+    will be created if the don't exist.
 
 The equivalent **NGSI-LD** payload is associated to an update operation (PATCH `/ngsi-ld/v1/entities/<entity>/attrs/`).
 
@@ -507,8 +506,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "actionType": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "actionType": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 If the request is correct, the Context Broker will reply with the following R1 response (200 OK):
@@ -554,7 +553,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "attrs": ["temperature","pressure"]
-}' "https://<platform-ip>:10027/v2/op/query"
+}' "https://<platform-ip>:1026/v2/op/query"
 ```
 
 The Context Broker will reply with the updated data values in R2 format (200 OK):
@@ -600,20 +599,6 @@ It is worth mentioning that the Context Broker will reply with a 200 OK status c
 refer to transport protocol level errors, while the status codes inside of a payload give information about the
 application level protocol.
 
-The example shows an error updating an non-existent attribute (due to the use of UPDATE instead of APPEND).
-
-The following error payload is also valid in standard NGSI:
-
-```json
-{
-    "error": "NotFound",
-    "description": "The requested entity has not been found. Check type and id"
-}
-```
-
-Different kinds of errors can return their information in different formats, so NGSI implementations should check for
-the existence of both.
-
 ### Scenario 2: lazy attributes (happy path)
 
 Scenario 2 relies on the Context Provider mechanism of the Context Broker. For this scenario to work, the IoTAgent must
@@ -639,7 +624,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     }
 }
-' "https://<platform-ip>:10027/v2/registrations"
+' "https://<platform-ip>:1026/v2/registrations"
 ```
 
 If everything has gone OK, the Context Broker will return the following payload:
@@ -669,7 +654,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "attrs": ["batteryLevel"]
-}' "https://<platform-ip>:10027/v2/op/query"
+}' "https://<platform-ip>:1026/v2/op/query"
 ```
 
 The Context Broker receives this request and detects that it can be served by a Context Provider (the IoT Agent), so it
@@ -772,7 +757,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "duration": "P1M"
-}' "https://<platform-ip>:10027/v2/registrations"
+}' "https://<platform-ip>:1026/v2/registrations"
 ```
 
 If everything has gone OK, the Context Broker will return the following payload:
@@ -806,8 +791,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "updateAction": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "updateAction": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 The Context Broker receives this command and detects that it can be served by a Context Provider (the IoT Agent), so it
@@ -836,7 +821,7 @@ Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
       }
     }
   ],
-  "updateAction" : "update"
+  "updateAction" : "append"
 }
 ```
 
@@ -900,8 +885,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "actionType": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "actionType": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 This update does not modify the original command attribute, but two auxiliary attributes, that are not provided by the
@@ -948,7 +933,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         "switch_info",
         "switch_status"
     ]
-}' "https://<platform-ip>:10027/v2/op/query"
+}' "https://<platform-ip>:1026/v2/op/query"
 ```
 
 The Context Broker replies with all the desired data, in R2 format (200 OK):
@@ -994,8 +979,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "actionType": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "actionType": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 In this case, the Context Broker reply with the following response (200 OK):

doc/index.md

@@ -26,8 +26,6 @@ functions.
     communications are left to the library.
 -   Standardized OAuth2-based security is available to enable each IoT Agent to connect to several common Identity
     Managers (e.g. Keystone and Keyrock) so that communications can be restricted to trusted components.
--   A series of additional plugins are offered where necessary to allow for expression parsing, attribute aliasing and
-    the processing of timestamp metadata.
 
 Each individual IoT Agent offers is driven by a `config.js` configuration file contains explicit custom settings based
 on the protocol and payload the IoT Agent is translating. It will also contain some common flags for common