Update Mirror documentation with --propagate option

Re GH#353

Author: marcosbento

docs/glossary.rst

@@ -1689,7 +1689,7 @@ Glossary
         as this may lead to undesired behaviour, including deadlocks.
 
       `Only one mirror attribute is allowed per node`, and each attribute is
-      defined by the following properties:
+      defined by the following options:
 
         - :code:`name`, an identifier
         - :code:`remote_path`, the path of the node on the remote ecFlow server
@@ -1698,6 +1698,7 @@ Glossary
         - :code:`ssl`, to connect to the ecFlow server using SSL
         - :code:`polling`, the value (in seconds) used to periodically contact the remote ecFlow server
         - :code:`auth`, the location to the Mirror authentication credentials file
+        - :code:`propagate`, to enable the propagation of the remote node state up the tree of local nodes
 
       .. warning::
 

docs/python_api/reference/MirrorAttr.rst

@@ -55,6 +55,12 @@ Returns the name of the Mirror attribute
 Returns the polling interval used to contact the remove ecFlow server
 
 
+.. py:method:: MirrorAttr.propagate(self: ecflow.MirrorAttr) -> bool
+   :module: ecflow
+
+Returns a boolean, where true means the Node state is propagated up the Node tree
+
+
 .. py:method:: MirrorAttr.remote_host(self: ecflow.MirrorAttr) -> str
    :module: ecflow
 

docs/ug/cookbook/how_to_mirror_a_remote_task.rst

@@ -68,6 +68,17 @@ at :term:`suite` level:
      Variables that are referred in trigger expressions *must* be defined, as a placeholder
      for variables that eventually get synchronised.
 
+  .. note::
+
+     By default, only the mirrored task's own state is updated; parent families and triggers
+     are unaffected. To propagate the mirrored state up the local node tree and cause dependent
+     triggers to fire, add the ``--propagate`` option::
+
+         mirror --name A --remote_path /s1/f1/t1 ... --ssl --propagate
+
+     Use ``--propagate`` only when you explicitly want state changes on the mirrored task to
+     drive the evaluation of triggers on its parent families.
+
 Deploy the Suite with a `mirrored` Task
 =======================================
 

docs/ug/user_manual/text_based_suite_definition/external/mirror.rst

@@ -7,10 +7,15 @@ This defines a :term:`mirror` attribute, which synchronizes the status of a
 :term:`node` between a local and a remote ecFlow server. The options defining
 the attribute can be provided in any order.
 
+The :term:`mirror` attribute is defined by the coordinates to the remote :term:`node` to be mirrored, including the
+remote :term:`node` path, the remote host name, the remote port number; and the polling interval in seconds.
+Furthermore, the option :code:`--ssl` enables the use of a Secure connection and the option :code:`--auth` can be used
+to provide the authentication credentials for the remote ecFlow server.
+
 .. code-block:: shell
 
     task t1
-      mirror --name A --remote_path /s/f/tA --remote_host host --remote_port 3141 --polling 20 --ssl --auth /path/to/auth.json
+      mirror --name A --remote_path /s/f/tA --remote_host host --remote_port 3141 --polling 300 --ssl --auth /path/to/auth.json
 
     task t2
       aviso --name B --remote_path /s/f/tB
@@ -20,6 +25,25 @@ the attribute can be provided in any order.
         #     --polling %ECF_MIRROR_POLLING%
         #     --auth %ECF_MIRROR_AUTH%
 
+
+By default, the :term:`mirror` attribute will not propagate the state of the remote :term:`node` to the local node tree,
+and only the actual associated local :term:`node` will see its state updated.
+The option :code:`--propagate` can be used to enable the propagation of the remote :term:`node` state to the local node
+tree.
+
+.. code-block:: shell
+
+    task t1
+      mirror --name A --remote_path /s/f/tA --remote_host host --remote_port 3141 --polling 300 --propagate
+
+
+.. note::
+   The ``--polling`` value (in seconds) controls how often the local ecFlow
+   server contacts the remote server. Lower values reduce latency but
+   have impact on the remote server as the network traffic increases.
+   A value of 300 seconds is considered suitable for most cases, and a minimum
+   of 60 seconds being imposed to avoid overloading the remote server.
+
 The Authentication credentials, provided via option :code:`--auth`, are
 provided in a `JSON` file with the following content: