Merge pull request #1641 from telefonicaid/metadata-doc-improvement

FIX metadata expression evaluation in doc
telefonicaid · Aug 8, 2024 · 3b80414 · 3b80414
2 parents f766c11 + 507cb58
commit 3b80414
Showing 1 changed file with 48 additions and 45 deletions.
diff --git a/doc/api.md b/doc/api.md
@@ -27,6 +27,7 @@
         -   [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)
@@ -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
@@ -590,6 +552,7 @@ really useful when you need to adapt measure (for example, to change the units,
 of expression in the IoT Agent are:
 
 -   [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.
@@ -607,16 +570,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 `<AttributeName>`
+- 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.<AttributeName>.<MetadataName>` or `metadata.<StaticAttributeName>.<MetadataName>` 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
@@ -735,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