ADD docu and CNR for #4594

telefonicaid · Aug 2, 2024 · 2256824 · 2256824
1 parent 316ddfb
commit 2256824
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 0 deletions.
diff --git a/CHANGES_NEXT_RELEASE b/CHANGES_NEXT_RELEASE
@@ -1,4 +1,5 @@
 - Add: custom notification ngsi patching evaluation priority based in evalPriority builtin metadata (#4556)
+- Add: attribute metadata to JEXL context (#4594)
 - Fix: $max and $min operators were not supported with DateTime attributes (#4585)
 - Fix: wrong date values should not allowed in subscription's expires field (#4541)
 - Fix: do not raise DB alarm in case of wrong GeoJSON in client request

diff --git a/doc/manuals/orion-api.md b/doc/manuals/orion-api.md
@@ -75,6 +75,7 @@
       - [Additional considerations](#additional-considerations)
     - [JEXL Support](#jexl-support)
       - [JEXL usage example](#jexl-usage-example)
+      - [Metadata support](#metadata-support)
       - [Evaluation priority](#evaluation-priority)
       - [Available Transformations](#available-transformations)
         - [`uppercase`](#uppercase)
@@ -2514,6 +2515,19 @@ will trigger a notification like this:
 ]
 ```
 
+### Metadata support
+
+Attribute metadata is also included in the JEXL evaluation context, along with the actual attributes. This is done using a special context key named `metadata` which value is an object with the following structure:
+
+* keys are the name of the attributes
+* values are object with a key-map of the metadata values of the given attribute
+
+For instance, the expression `${metadata.A.MD1}` will result in the value of the metadata `MD1` belonging to the attribute `A`.
+
+Note that [builtin metadata](#builtin-metadata) are automatically added to the `metadata` context key. For instance, the `${A-metadata.A.previousValue}` expression will provide the difference between the current value of `A` (in the update request) and the previous one (before the update request).
+
+Finally, note that in the rare case an attribute named `metadata` is used (which is an anti-pattern strongly discouraged) it will not be added to the context, as the `metadata` with metadata values will take precedence.
+
 ### Evaluation priority
 
 Each time an expression is evaluated, it is added to the expression context, so it can be reused by other expressions. However, by default Orion does not guarantee a given evaluation other.