Update save&restore doc

Author: georgweiss

services/save-and-restore/doc/index.rst

@@ -265,6 +265,8 @@ The a list of all the children nodes of the node with id `{uniqueNodeId}`
         }
     ]
 
+.. _Get a configuration:
+
 Get a configuration
 """""""""""""""""""
 
@@ -295,7 +297,11 @@ Return: object describing the configuration data, essentially a list of PVs.
                     "pvName": "13SIM1:{SimDetector-Cam:1}cam1:BinX"
                 },
                 {
-                    "pvName": "13SIM1:{SimDetector-Cam:1}cam1:BinY"
+                    "pvName": "13SIM1:{SimDetector-Cam:1}cam1:BinY",
+                    "comparison":{
+                        "comparisonMode":"ABSOLUTE",
+                        "tolerance":2.7
+                    }
                 },
                 {
                     "pvName": "13SIM1:{SimDetector-Cam:2}cam2:BinX",
@@ -313,6 +319,8 @@ Return: object describing the configuration data, essentially a list of PVs.
 
 Here the ``uniqueId`` field matches the ``unqiueId`` field of the configuration node.
 
+The ``comparison`` field is optional and can be set individually on each element in the list.
+
 Create a configuration
 """"""""""""""""""""""
 
@@ -347,8 +355,10 @@ Body:
                         "pvName": "13SIM1:{SimDetector-Cam:2}cam2:BinX",
                         "readbackPvName": null,
                         "readOnly": false,
-                        "pvCompareMode": "ABSOLUTE",
-                        "tolerance": 2.5
+                        "comparison": {
+                            "comparisonMode":"ABSOLUTE",
+                            "tolerance": 2.7
+                        }
                     },
                     {
                         "pvName": "13SIM1:{SimDetector-Cam:2}cam2:BinY",
@@ -363,6 +373,9 @@ Body:
 The request parameter ``parentNodeId`` is mandatory and must identify an existing folder node. The client
 needs to specify a name for the new configuration node, as well as a user identity.
 
+The ``comparison`` field is optional and can be set individually on each element in the list. If specified,
+the ``comparisonMode`` must be either "ABSOLUTE" or "RELATIVE", and the ``tolerance`` must be >=0.
+
 Update a configuration
 """"""""""""""""""""""
 
@@ -382,6 +395,8 @@ body will be removed.
 Snapshot Endpoints
 ------------------
 
+.. _Get a snapshot:
+
 Get a snapshot
 """"""""""""""
 
@@ -642,7 +657,7 @@ body will be removed.
 Get restorable items of a composite snapshot
 """"""""""""""""""""""""""""""""""""""""""""
 
-***.../composite-snapshot/{uniqueId}/items**
+**.../composite-snapshot/{uniqueId}/items**
 
 Method: GET
 
@@ -761,6 +776,54 @@ Body:
       }
     ]
 
+Server Take Snapshot Endpoints
+------------------------------
+
+**.../take-snapshot/{configNodeId}**
+
+Method: GET
+
+This will read PV values for all items listed in the configuration identified by ``configNodeId``. Upon successful
+completion, the response will hold an array of objects where each element is on the form:
+
+.. code-block:: JSON
+
+    {
+        "configPv": {
+          "pvName": "RFQ-010:RFS-EVR-101:RFSyncWdt-SP",
+          "readbackPvName": null,
+          "readOnly": false
+        },
+        "value": {
+          "type": {
+            "name": "VDouble",
+            "version": 1
+          },
+          "value": 100.0,
+          "alarm": {
+            "severity": "NONE",
+            "status": "NONE",
+            "name": "NONE"
+          },
+          "time": {
+            "unixSec": 1639063122,
+            "nanoSec": 320431469
+          },
+          "display": {
+            "units": ""
+          }
+    }
+
+**.../take-snapshot/{configNodeId}<?name=snapshotName&comment=snapshotComment>**
+
+Method: PUT
+
+This will read PV values for all items listed in the configuration identified by ``configNodeId``. Upon successful
+completion the data is persisted into the database. ``name`` and ``comment`` are optional query parameters and will
+default to the current date/time on the format ``yyyy-MM-dd HH:mm:ss.SSS``.
+
+The response is a snapshot object representing the persisted data, see :ref:`Get a snapshot`
+
 Server Restore Endpoints
 ------------------------
 
@@ -885,15 +948,14 @@ Comparisons are performed like so:
 * Table PVs are compared element wise, always using zero tolerance. Tables must be of same dimensions, and data types must match between columns.
 * Enum PVs are compared using zero tolerance.
 
-In addition, the ``compareMode`` and ``skipReadback`` together with the presence of a read-back PV value is used to
-determine which value to compare to the stored value:
+The ``compareMode`` and ``tolerance`` are applied to all comparison operations, but can be overridden on each individual
+item in a configuration, see :ref:`Get a configuration`.
+
+Equality between a stored value and the live value is determined on each PV like so:
 
-* If a read-back PV name has been specified it's live value is compare to the stored value.
-* If a read-back PV name has not been specified, or if ``skipReadback`` is ``true``, then the live value of ``PV Name`` is used to compare to the stored value.
-* Compare mode=ABSOLUTE (default) will apply absolute delta comparison.
-* Compare mode=RELATIVE will apply relative comparison.
-* If an item in the configuration specifies a tolerance of zero, then a tolerance value specified in the API call will be ignored.
-* If the stored value is zero and compareMode is RELATIVE, then live value must also be zero to be treated as equal.
+* If the configuration of a PV does not specify a comparison mode and tolerance, the ``comparisonMode`` and ``tolerance`` request parameters are used. These however are optional and default to ABSOLUTE and zero respectively.
+* The base (reference) value is always the value stored in the value field of a snapshot item object. It corresponds to the ``pvName``` field, i.e. never the ``readbackPvName`` of a configuration item.
+* The live value used in the comparison is either the value corresponding to ``pvName``, or ``readbackPvName`` if specified. The latter can be overridden with the ``skipReadback`` request parameter.
 
 Return value: a list of comparison results, one for each PV in the snapshot, e.g.: