From 5441e87d8f7f5a124d0916aa9328ec57e3b9bd89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Thu, 8 Aug 2024 10:57:57 +0200 Subject: [PATCH 1/3] FIX metadata expression evaluation in doc --- doc/api.md | 97 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 47 deletions(-) diff --git a/doc/api.md b/doc/api.md index 59fe58bb2..24368ab25 100644 --- a/doc/api.md +++ b/doc/api.md @@ -30,6 +30,7 @@ - [Measurement transformation](#measurement-transformation) - [Measurement transformation definition](#measurement-transformation-definition) - [Measurement transformation execution](#measurement-transformation-execution) + - [Metadata transformation](#metadata-transformation) - [Measurement transformation order](#measurement-transformation-order) - [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id) - [Command execution](#command-execution) @@ -353,45 +354,6 @@ e.g.: } ``` -Metadata could also has `expression` like attributes in order to expand it: - -e.g.: - -```json -{ - "entity_type": "Lamp", - "resource": "/iot/d", - "protocol": "PDI-IoTA-UltraLight", - "commands": [ - { "name": "on", "type": "command" }, - { "name": "off", "type": "command" } - ], - "attributes": [ - { "object_id": "s", "name": "state", "type": "Text" }, - { - "object_id": "l", - "name": "luminosity", - "type": "Integer", - "metadata": { - "unitCode": { "type": "Text", "value": "CAL" } - } - } - ], - "static_attributes": [ - { "name": "category", "type": "Text", "value": ["actuator", "sensor"] }, - { - "name": "controlledProperty", - "type": "Text", - "value": ["light"], - "metadata": { - "includes": { "type": "Text", "value": ["state", "luminosity"], "expression": "level / 100" }, - "alias": { "type": "Text", "value": "lamp" } - } - } - ] -} -``` - ### NGSI-LD data and metadata considerations When provisioning devices for an NGSI-LD Context Broker, `type` values should typically correspond to one of the @@ -589,7 +551,7 @@ to adapt the information coming from the South Bound APIs to the information rep really useful when you need to adapt measure (for example, to change the units, or to apply a formula to). All the usage of expression in the IoT Agent are: -- [Measurement transformation](#measurement-transformation). +- [Measurement transformation](#measurement-transformation) (attributes and their metadata) - Commands payload transformation (push and pull). - Auto provisioned devices entity name. It is configured at config Group level by setting the `entityNameExp` parameter. It defines an expression to generate the Entity Name for autoprovisioned devices. @@ -607,16 +569,13 @@ expression. In all cases the following data is available to all expressions: - `staticAttributes`: static attributes defined in the device or config group Additionally, for attribute expressions (`expression`, `entity_name`), `entityNameExp` and metadata expressions -(`expression`) measures are available in the **context** used to evaluate them. +(`expression`) the following is available in the **context** used to evalute: -Attribute metadata and Static Attribute metadata are available in the **context** under the following convention: +- measures, as `` +- metadata (both for attribute and static attribute) are available in the **context** under the following convention: `metadata..` or `metadata..` in a similar way of defined for [Context Broker](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#metadata-support) -Moreover, if attribute metadata has an expression metadata attribute value in jexl context it is updated after that -expression is evaluated. Note that there is no order into metadata structure and there is no warranty about which -metadata attribute expression will be evaluated first. - ### Examples of JEXL expressions The following table shows expressions and their expected outcomes taking into account the following measures at @@ -886,9 +845,50 @@ following to CB: [Interactive expression `spaces | trim`][5] +### Metadata transformation + +Metadata could also has `expression` like attributes in order to define a transformation on it: + +e.g.: + +```json +{ + "entity_type": "Lamp", + "resource": "/iot/d", + "protocol": "PDI-IoTA-UltraLight", + "commands": [ + { "name": "on", "type": "command" }, + { "name": "off", "type": "command" } + ], + "attributes": [ + { "object_id": "s", "name": "state", "type": "Text" }, + { + "object_id": "l", + "name": "luminosity", + "type": "Integer", + "metadata": { + "unitCode": { "type": "Text", "value": "CAL" } + } + } + ], + "static_attributes": [ + { "name": "category", "type": "Text", "value": ["actuator", "sensor"] }, + { + "name": "controlledProperty", + "type": "Text", + "value": ["light"], + "metadata": { + "includes": { "type": "Text", "value": ["state", "luminosity"], "expression": "level / 100" }, + "alias": { "type": "Text", "value": "lamp" } + } + } + ] +} +``` + ### Measurement transformation order -The IoTA executes the transformaion looping over the `attributes` provision field. Every time a new expression is +With regards to **attributes**, the IoTA executes the transformaion looping over the `attributes` provision field. Every time a new expression is evaluated, the JEXL context is updated with the expression result. The order defined in the `attributes` array is taken for expression evaluation. This should be considered when using **nested expressions**, that uses values calculated in other attributes. @@ -974,6 +974,9 @@ context was updated with the lastest execution, the value of `b` will be `2000`, "b": {"value": 2000, "type": "Number"} ``` +Which regards to **metadata**, note that there is no order into metadata structure and there is no warranty about which +metadata attribute expression will be evaluated first. + ### Multientity measurement transformation support (`object_id`) To allow support for measurement transformation in combination with multi entity feature, where the same attribute is From f7d781200ce3aac110dc4e67529b3c5b2988b737 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Thu, 8 Aug 2024 11:23:40 +0200 Subject: [PATCH 2/3] FIX refactor doc according to comments in review --- doc/api.md | 96 +++++++++++++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/doc/api.md b/doc/api.md index 24368ab25..c17717005 100644 --- a/doc/api.md +++ b/doc/api.md @@ -27,10 +27,10 @@ - [Examples of JEXL expressions](#examples-of-jexl-expressions) - [Available functions](#available-functions) - [Expressions with multiple transformations](#expressions-with-multiple-transformations) + - [Expression support in metadata](#expression-support-in-metadata) - [Measurement transformation](#measurement-transformation) - [Measurement transformation definition](#measurement-transformation-definition) - [Measurement transformation execution](#measurement-transformation-execution) - - [Metadata transformation](#metadata-transformation) - [Measurement transformation order](#measurement-transformation-order) - [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id) - [Command execution](#command-execution) @@ -551,7 +551,8 @@ to adapt the information coming from the South Bound APIs to the information rep really useful when you need to adapt measure (for example, to change the units, or to apply a formula to). All the usage of expression in the IoT Agent are: -- [Measurement transformation](#measurement-transformation) (attributes and their metadata) +- [Measurement transformation](#measurement-transformation). +- [Metadata](#expression-support-in-metadata) - Commands payload transformation (push and pull). - Auto provisioned devices entity name. It is configured at config Group level by setting the `entityNameExp` parameter. It defines an expression to generate the Entity Name for autoprovisioned devices. @@ -572,7 +573,7 @@ Additionally, for attribute expressions (`expression`, `entity_name`), `entityNa (`expression`) the following is available in the **context** used to evalute: - measures, as `` -- metadata (both for attribute and static attribute) are available in the **context** under the following convention: +- metadata (both for attribute measurement in the case of NGSIv2 measurments and static attribute) are available in the **context** under the following convention: `metadata..` or `metadata..` in a similar way of defined for [Context Broker](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#metadata-support) @@ -694,6 +695,49 @@ Another example using functions that return more than one value is the following For a location value `"40.4165, -3.70256"`, the result of the previous expression will be `-3.70256`. +### Expression support in metadata + +Metadata could also has `expression` like attributes in order to expand it: + +e.g.: + +```json +{ + "entity_type": "Lamp", + "resource": "/iot/d", + "protocol": "PDI-IoTA-UltraLight", + "commands": [ + { "name": "on", "type": "command" }, + { "name": "off", "type": "command" } + ], + "attributes": [ + { "object_id": "s", "name": "state", "type": "Text" }, + { + "object_id": "l", + "name": "luminosity", + "type": "Integer", + "metadata": { + "unitCode": { "type": "Text", "value": "CAL" } + } + } + ], + "static_attributes": [ + { "name": "category", "type": "Text", "value": ["actuator", "sensor"] }, + { + "name": "controlledProperty", + "type": "Text", + "value": ["light"], + "metadata": { + "includes": { "type": "Text", "value": ["state", "luminosity"], "expression": "level / 100" }, + "alias": { "type": "Text", "value": "lamp" } + } + } + ] +} +``` + +Note that there is no order into metadata structure and there is no warranty about which metadata attribute expression will be evaluated first. + ## Measurement transformation The IoTAgent Library provides support for measurement transformation using a @@ -845,50 +889,9 @@ following to CB: [Interactive expression `spaces | trim`][5] -### Metadata transformation - -Metadata could also has `expression` like attributes in order to define a transformation on it: - -e.g.: - -```json -{ - "entity_type": "Lamp", - "resource": "/iot/d", - "protocol": "PDI-IoTA-UltraLight", - "commands": [ - { "name": "on", "type": "command" }, - { "name": "off", "type": "command" } - ], - "attributes": [ - { "object_id": "s", "name": "state", "type": "Text" }, - { - "object_id": "l", - "name": "luminosity", - "type": "Integer", - "metadata": { - "unitCode": { "type": "Text", "value": "CAL" } - } - } - ], - "static_attributes": [ - { "name": "category", "type": "Text", "value": ["actuator", "sensor"] }, - { - "name": "controlledProperty", - "type": "Text", - "value": ["light"], - "metadata": { - "includes": { "type": "Text", "value": ["state", "luminosity"], "expression": "level / 100" }, - "alias": { "type": "Text", "value": "lamp" } - } - } - ] -} -``` - ### Measurement transformation order -With regards to **attributes**, the IoTA executes the transformaion looping over the `attributes` provision field. Every time a new expression is +The IoTA executes the transformaion looping over the `attributes` provision field. Every time a new expression is evaluated, the JEXL context is updated with the expression result. The order defined in the `attributes` array is taken for expression evaluation. This should be considered when using **nested expressions**, that uses values calculated in other attributes. @@ -974,9 +977,6 @@ context was updated with the lastest execution, the value of `b` will be `2000`, "b": {"value": 2000, "type": "Number"} ``` -Which regards to **metadata**, note that there is no order into metadata structure and there is no warranty about which -metadata attribute expression will be evaluated first. - ### Multientity measurement transformation support (`object_id`) To allow support for measurement transformation in combination with multi entity feature, where the same attribute is From 507cb581a927ac24d796267e0513b6dfd7603a08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Thu, 8 Aug 2024 11:27:00 +0200 Subject: [PATCH 3/3] Update doc/api.md --- doc/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api.md b/doc/api.md index c17717005..425e01059 100644 --- a/doc/api.md +++ b/doc/api.md @@ -573,7 +573,7 @@ Additionally, for attribute expressions (`expression`, `entity_name`), `entityNa (`expression`) the following is available in the **context** used to evalute: - measures, as `` -- metadata (both for attribute measurement in the case of NGSIv2 measurments and static attribute) are available in the **context** under the following convention: +- metadata (both for attribute measurement in the case of NGSI-v2 measurements and static attribute) are available in the **context** under the following convention: `metadata..` or `metadata..` in a similar way of defined for [Context Broker](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#metadata-support)