ADD documentation

CHANGES_NEXT_RELEASE

@@ -1,7 +1,6 @@
-<<<<<<< HEAD
-- Add: expression context build and evaluation counter in timing section in GET /statistics (#4004)
-- Fix: lighter operation to get databases list from MongoDB (#4517)
-=======
+- Add: JEXL expression support in custom notification macro replacement (using cjexl 0.1.0) (#4004)
+- Add: expression context build and evaluation counters in timing section in GET /statistics (#4004)
+- Fix: use null for non existing attributes in custom covered notifications macro substitution (instead of empty string) to make behaviur more consistent
 - Fix: simplified GET /version operation, without including "libversions" field (add ?options=libVersions to get it)
 - Fix: lighter operation to get databases list from MongoDB (#4517)
->>>>>>> master
+

doc/manuals/admin/build_source.md

@@ -4,6 +4,8 @@ Orion Context Broker reference distribution is Debian 12. This doesn't mean that
 
 You can also have a look to [3.1 Building in not official distributions](../../../docker/README.md#31-building-in-not-official-distributions) section in the Docker documentation to check how to build Docker containers images in distributions other than the official one.
 
+*NOTE:* the build process described in this document does not include the cjexl library, as it is considered optional from the point of view of the basic building process.
+
 ## Debian 12 (officially supported)
 
 The Orion Context Broker uses the following libraries as build dependencies:

doc/manuals/admin/statistics.md

@@ -129,28 +129,22 @@ Provides timing information, i.e. the time that CB passes executing in different
   "timing": {
     "accumulated": {
       "jsonV1Parse": 7.860908311,
-      "mongoBackend": 416.796091597,
-      "mongoReadWait": 4656.924425628,
-      "mongoWriteWait": 259.347915990,
-      "mongoCommandWait": 0.514811318,
-      "exprBasicCtxBld": FIXME PR,
-      "exprBasicEval": FIXME PR,
-      "exprJexlCtxBld": FIXME PR,
-      "exprJexlEval": FIXME PR,
-      "render": 108.162782114,
-      "total": 6476.593504743
-     },
+      "jsonV2Parse": 120.680244446,
+      "mongoBackend": 12778.52734375,
+      "mongoReadWait": 7532.301757812,
+      "mongoWriteWait": 3619.282226562,
+      "mongoCommandWait": 0.120559767,
+      "exprJexlCtxBld": 27.092681885,
+      "exprJexlEval": 124.217208862,
+      "render": 44.540554047,
+      "total": 25051.384765625
+    },
     "last": {
-      "mongoBackend": 0.014752309,
-      "mongoReadWait": 0.012018445,
-      "mongoWriteWait": 0.000574611,
-      "exprBasicCtxBld": FIXME PR,
-      "exprBasicEval": FIXME PR,
-      "exprJexlCtxBld": FIXME PR,
-      "exprJexlEval": FIXME PR,
-      "render": 0.000019136,
-      "total": 0.015148915
-     }
+      "mongoBackend": 0.003775352,
+      "mongoReadWait": 0.0013743,
+      "render": 0.000286864,
+      "total": 0.00440685
+    }
   }
   ...
 }
@@ -164,8 +158,6 @@ The block includes two main sections:
 
 The particular counters are as follows:
 
-FIXME PR: explain expr* fields
-
 * `total`: processing time for the whole request, excluding the time that the HTTP library
   takes for request/response dispatching (pseudo end-to-end time)
 * `jsonV1Parse`: time passed in NGSIv1 JSON parsing module (pseudo self-time)
@@ -177,10 +169,15 @@ FIXME PR: explain expr* fields
   `last` includes the accumulation for all of them. In the case of mongoReadWait, only the time used
   to get the results cursor is taken into account, but not the time to process cursors results (which
   is time that belongs to mongoBackend counters).
+* `exprJexlCtxBld`: time passed building context for custom notification expression evaluation (see [macro substitution](../orion-api.md#macro-substitution) and [JEXL support](../orion-api.md#jexl-support))
+* `exprJexlEval`: time passed evaluating custom notification expressions (see [macro substitution](../orion-api.md#macro-substitution) and [JEXL support](../orion-api.md#jexl-support))
+
+*NOTE*: if Orion binary is build without using cjexl and only basic replacement is available, then `exprBasicCtxtBld` and `exprBasicEval`
+fields appear instead of `exprJexlCtxBld` and `exprJexlEval`.
 
 Times are measured from the point in time in which a particular thread request starts using a module until it finishes using it.
 Thus, if the thread is stopped for some reason (e.g. the kernel decides to give priority to another thread based on its
-scheculing policy) the time that the thread was sleeping, waiting to execute again is included in the measurement and thus, the measurement is not accurate. That is why we say *pseudo* selt/end-to-end time. However,
+scheculing policy) the time that the thread was sleeping, waiting to execute again is included in the measurement and thus, the measurement is not accurate. That is why we say *pseudo* self/end-to-end time. However,
 under low load conditions this situation is not expected to have a significant impact.
 
 ### NotifQueue block

doc/manuals/devel/sourceCode.md

@@ -24,6 +24,7 @@
 * [src/lib/cache/](#srclibcache) (Subscription cache implementation)
 * [src/lib/logSummary/](#srcliblogsummary) (Log Summary implementation)
 * [src/lib/metricsMgr/](#srclibmetricsmgr) (Metrics Manager implementation)
+* [src/lib/expressions/](#seribexpressions) (Custom notification expressions support)
 
 ## src/app/contextBroker/
 The main program is found in `contextBroker.cpp` and its purpose it to:
@@ -551,3 +552,8 @@ This Metrics Manager resides in the library **metricsMgr**.
 For information about the metrics, please refer to [this document](../admin/metrics_api.md).
 
 [Top](#top)
+
+## src/lib/expressions/
+Provides support to the [macro substition logic used by custom notifications](../orion-api.md#macro-substitution). This library provides an abstraction for expression evaluation, providing two implementations: JEXL based and basic replacement based (the implementation to use is choosen at building time, based on the availability of the cjex library).
+
+[Top](#top)