[IMP] studio: clarifying logic for time-triggered automation rules

task-5335209

Author: mcsi-odoo

content/applications/studio/automated_actions.rst

@@ -165,16 +165,44 @@ You can then define:
      the frequency of this check to ensure that more granular delays, e.g., 1 hour before the event
      start date and time, or 30 minutes after creation, can be respected as closely as possible.
 
-     To view or manually edit the frequency of the scheduler for a time-triggered automation rule,
-     with :ref:`developer mode activated <developer-mode>`, click :guilabel:`Scheduled action`.
+     To view or manually edit the frequency of the check for time-triggered automation rules,
+     with :ref:`developer mode activated <developer-mode>`, click :icon:`fa-arrow-right`
+     :guilabel:`Scheduled action`.
 
      .. image:: automated_actions/trigger-delay-scheduled-action.png
         :alt: Direct link to scheduled action for automations
 
      In the :guilabel:`Automation Rules: check and execute` scheduled action that opens, update the
      value of the :guilabel:`Execute Every` field, if desired. Clicking :guilabel:`Run Manually`
-     triggers the scheduled action to run immediately. To return to the automation rule setup, click
-     the automation rule name in the breadcrumbs.
+     triggers *the scheduled action* to run immediately. To return to the automation rule setup,
+     click the automation rule name in the breadcrumbs.
+
+  .. important::
+     Manually running the :guilabel:`Automation Rules: check and execute` scheduled action *does not
+     necessarily trigger the automation rule itself*. An automation rule only runs when the
+     scheduled trigger date & time falls *between* the last run of the scheduled action and the
+     current run (whether scheduled or run manually):
+
+     **last run --> scheduled trigger date & time --> current run**
+
+     .. example::
+        At 11:00 am on October 15 you create an automation rule that triggers the sending of an
+        email 30 days before the :guilabel:`Contract end date`; contracts end at 11:59 pm on their
+        contract end date.
+
+        This new rule will only run for contracts whose end date is at least 30 days *after* the
+        creation of the rule, i.e., an end date of November 14 or later. This is because until that
+        moment, the scheduled trigger date of `contract end date` - `30 days` will always be
+        *earlier than* the last run of the scheduled action.
+
+        For a contract with an end date of November 14, the scheduled trigger date & time is 30 days
+        before 11:59 pm on November 14, i.e., 11:59 pm on October 15. The rule will therefore run
+        the first time the :guilabel:`Automation Rules: check and execute` scheduled action runs
+        after the scheduled trigger date & time:
+
+        - last run of the scheduled action: October 15 (the scheduler runs minimum every 4 hours)
+        - scheduled trigger date & time: 11:59 pm on October 15
+        - current run of the scheduled action: 3:59 am on October 16 at the latest
 
 - :guilabel:`Extra Conditions`: Click :guilabel:`Add condition`, then specify the conditions to be
   met for the automation rule to run. Click :guilabel:`New Rule` to add another condition.