Adding campaign republish behavior docs

docs/campaigns/creating_campaigns.rst

@@ -51,6 +51,7 @@
 
 -  **Category** - Choose a Category to assign your Campaign to. Categories help you organize your Campaigns. To learn more about creating and managing Categories, see :doc:`/categories/categories-overview`.
 -  **Allow Contacts to restart the Campaign** - Click the toggle switch to allow Contacts to restart the Campaign if you're building a Campaign for a recurring message - for example birthdays, subscriptions - or transactional operations - for example activity notifications, updating data. Enabling this option allows Contacts to go through the same Campaign multiple times.
+-  **Campaign Reactivation Behaviour** - Configure how scheduled events with relative delays should behave when the Campaign is reactivated after being deactivated. You can override the global default setting for this specific Campaign. See :ref:`Campaign Reactivation Behaviour<campaign reactivate behavior>` for more information about the available options.
 -  **Active** - Click the toggle switch to turn the Campaign on or off. Ensure that you don't activate a Campaign until you're actually ready for it to go live. You can also schedule to activate or deactivate a Campaign at a future date by selecting a time and date.
 
 #. Click **Launch Campaign Builder** to start building your Campaign, and add at least one event. For information about how to use the Campaign Builder, see :doc:`/campaigns/campaign_builder`.

docs/campaigns/managing_campaigns.rst

@@ -31,4 +31,107 @@
 
 The **Contacts** tab displays a grid view of all the Contacts that you have added to your Campaign.
 
-The **Recent Activity** panel on the right displays the recent activities that have taken place in the Campaign.
+The **Recent Activity** panel on the right displays the recent activities that have taken place in the Campaign.
+
+.. vale off
+
+.. _campaign reactivate behavior:
+
+Campaign reactivation behaviour
+********************************
+
+.. vale on
+
+When you deactivate and then reactivate a Campaign, Mautic provides control over how scheduled events with relative delays - such as "Send Email 5 days after joining" - should behave. This feature gives you flexibility in managing Campaign timing based on your specific use case.
+
+.. note::
+    This setting only affects events that use relative delays (interval-based scheduling). Events with absolute dates aren't affected by this setting.
+
+Configuring reactivation behaviour
+===================================
+
+You can configure the reactivation behaviour at two levels:
+
+1. **Global default** - Set in Configuration > Campaign Settings > Campaign Reactivation Behaviour. This applies to all Campaigns unless overridden.
+2. **Per Campaign** - Set when creating or editing a Campaign. This overrides the global default for that specific Campaign.
+
+Reactivation behaviour options
+===============================
+
+There are three options available for how scheduled events should behave after reactivation:
+
+Count delay regardless of activation state
+-------------------------------------------
+
+This is the default behaviour. The original trigger date is used and inactive time doesn't affect scheduling.
+
+**Example scenario:**
+
+- Campaign trigger date: January 1
+- Event delay: 10 days
+- Calculated event date: January 11
+- Campaign deactivated: January 5
+- Campaign reactivated: January 7
+
+**Result:** the event still executes on January 11, as originally scheduled.
+
+**When to use:** this option maintains the original scheduled timing, treating the Campaign's activation state as irrelevant to the delay calculation. Use this when you want consistency with the original schedule, or when temporarily deactivating a Campaign shouldn't affect when events execute.
+
+Restart on reactivation
+---------------------
+
+The delay counter resets completely when you reactivate the Campaign.
+
+**Example scenario:**
+
+- Campaign trigger date: January 1
+- Event delay: 10 days
+- Original calculated event date: January 11
+- Campaign deactivated: January 5
+- Campaign reactivated: January 7
+
+**Result:** the event is rescheduled to execute 10 days after reactivation, on January 17.
+
+**When to use:** this option is useful when you want to ensure all Contacts receive the full intended delay after any Campaign changes. For example, if you deactivate a Campaign to make significant updates and want everyone to experience the complete updated workflow timing.
+
+Count delay only while active
+------------------------------
+
+Events only count days when the Campaign is active. Inactive periods don't count toward the delay.
+
+**Example scenario:**
+
+- Campaign trigger date: January 1
+- Event delay: 10 days
+- Original calculated event date: January 11
+- Campaign deactivated: January 5 (after 4 days active)
+- Campaign reactivated: January 10 (after 5 days inactive)
+
+**Result:** the event is rescheduled to execute on January 16. The 4 days while active (January 1-5) count toward the 10-day delay, leaving 6 more days needed after reactivation (January 10 + 6 days = January 16).
+
+**When to use:** this option is ideal when you want precise control over the actual time Contacts spend in an active Campaign state. Use this for compliance scenarios, trial periods, or when you need to pause Campaigns without affecting the intended engagement timeline.
+
+Viewing last activation date
+=============================
+
+On the Campaign details page, you can see the **Last Publish Date** which indicates when the Campaign was most recently activated. This date is used as the reference point for the "Restart on reactivate" option to recalculate scheduled event timings.
+
+Activate and deactivate Campaigns
+==================================
+
+When you activate or deactivate a Campaign, Mautic displays a confirmation message that shows the current reactivation behaviour setting. This helps you understand what happens to scheduled events before you confirm the action.
+
+For example: "All scheduled events execute according to the reactivation behaviour setting. Currently set to: Count delay regardless of activation state"
+
+.. warning::
+    When you deactivate a Campaign, all processing of Contacts and Campaign events - including scheduled events - stops immediately. Scheduled events remain in the queue but won't execute until you reactivate the Campaign.
+
+.. note::
+    The recalculation of scheduled events happens when the Campaign event log is being evaluated by the Cron job, not at the moment you reactivate the Campaign. This means that if a recalculated trigger date is still in the past when evaluated, the event executes immediately. If it's in the future, the event is rescheduled accordingly.
+
+Tracking rescheduled events
+===========================
+
+Mautic records all changes to scheduled event trigger dates in the ``campaign_lead_event_log.metadata`` column. This audit trail allows you to investigate when and why events were rescheduled, providing transparency and helping with troubleshooting.
+
+You can view this information in the Contact's timeline under **Campaign Event Scheduled** entries, where rescheduled events show the updated trigger date and the reason for the change.

docs/configuration/settings.rst

@@ -156,7 +156,17 @@
 
 * **Use date range for all views** - When viewing a Campaign, the date range of actions, conditions, decisions, and Contacts displayed in the tabs, Mautic uses this date range by default.
 
-* **Use summary statistics** - Improves performance when viewing a Campaign with thousands of events per day by using summarized data. When you first turn on this setting you need to run a :ref:`cron job<campaign cron jobs>` to summarize existing data.
+* **Use summary statistics** - Improves performance when viewing a Campaign with thousands of events per day by using summarized data. When you first turn on this setting you need to run a :ref:`Cron job<campaign cron jobs>` to summarize existing data.
+
+* **Campaign Reactivation Behaviour** - Configure how scheduled events with relative delays in the middle of the workflow should behave when the Campaign is reactivated after being deactivated for a while. This setting provides a global default that can be overridden per Campaign. This setting affects how the :ref:`Campaign Cron jobs<campaign cron jobs>` schedule events. See :ref:`Campaign Reactivation Behaviour<campaign reactivate behavior>` for more information.
+
+  Available options:
+
+  - **Count delay regardless of activation state** - The original trigger date is used. Events execute based on the calendar days from when they were originally scheduled, regardless of whether the Campaign was active or inactive during that period. This is the default behaviour.
+
+  - **Restart on reactivation** - The delay counter resets when the Campaign is reactivated. Events are rescheduled to execute the full delay period after the last activation date.
+
+  - **Count delay only while active** - Events only count days when the Campaign is active. If the Campaign is inactive, those days don't count toward the delay, and events are rescheduled accordingly when the Campaign is reactivated.
 
 Optimal for Contact event scheduler
 ===================================
@@ -283,7 +293,7 @@
 Configuring the Queue
 =====================
 
-The system can either send Emails immediately or queue them for processing in batches by a :doc:`cron job </configuration/cron_jobs>`. Documentation relating to configuring the queue is in the :doc:`queue </queue/queue>` section.
+The system can either send Emails immediately or queue them for processing in batches by a :doc:`Cron job </configuration/cron_jobs>`. Documentation relating to configuring the queue is in the :doc:`queue </queue/queue>` section.
 
 Immediate delivery
 ------------------
@@ -293,13 +303,13 @@
 Queued delivery
 ---------------
 
-Mautic works most effectively with high send volumes if you use the queued delivery method. Mautic stores the Email in the configured spool directory until the execution of the command to process the queue. Set up a :doc:`cron job </configuration/cron_jobs>` at the desired interval to run the command:
+Mautic works most effectively with high send volumes if you use the queued delivery method. Mautic stores the Email in the configured spool directory until the execution of the command to process the queue. Set up a :doc:`Cron job </configuration/cron_jobs>` at the desired interval to run the command:
 
 .. code-block:: shell
 
     php /path/to/mautic/bin/console messenger:consume email
 
-Some hosts may have limits on the number of Emails sent during a specified time frame and/or limit the execution time of a script. If that's the case for you, or if you just want to moderate batch processing, you can configure batch numbers and time limits in Mautic's Configuration. See the :doc:`cron job documentation </configuration/cron_jobs>` for more specifics.
+Some hosts may have limits on the number of Emails sent during a specified time frame and/or limit the execution time of a script. If that's the case for you, or if you just want to moderate batch processing, you can configure batch numbers and time limits in Mautic's Configuration. See the :doc:`Cron job documentation </configuration/cron_jobs>` for more specifics.
 
 
 Mail send settings
@@ -467,7 +477,7 @@
   :width: 600
   :alt: Screenshot showing Import Settings Configuration in Mautic
 
-* **Automatically import in the background if the CSV has more rows than defined** - If there are more than the specified number of rows in an import file, the CSV automatically sets to import in the background which requires a :ref:`cron job<import contacts cron job>` to trigger. Set to 0 if you want to always import files in the background recommended for performance optimization.
+* **Automatically import in the background if the CSV has more rows than defined** - If there are more than the specified number of rows in an import file, the CSV automatically sets to import in the background which requires a :ref:`Cron job<import contacts cron job>` to trigger. Set to 0 if you want to always import files in the background recommended for performance optimization.
 
 Export settings
 ===============
@@ -485,7 +495,7 @@
   :width: 600
   :alt: Screenshot showing Segment Settings Configuration in Mautic
 
-* **Show warning if Segment hasn't been rebuilt for X hours** - Every time a :ref:`cron jobs<segment cron jobs>` runs, Segments are rebuilt. If there is an error that prevents a Segment from rebuilding, Mautic displays a warning message. This field allows you to configure the allowable length of time between rebuilds, after which the warning message appears.
+* **Show warning if Segment hasn't been rebuilt for X hours** - Every time a :ref:`Cron jobs<segment cron jobs>` runs, Segments are rebuilt. If there is an error that prevents a Segment from rebuilding, Mautic displays a warning message. This field allows you to configure the allowable length of time between rebuilds, after which the warning message appears.
 
 Company settings
 ****************
@@ -768,7 +778,7 @@
   :width: 600
   :alt: Screenshot showing Webhook Settings Configuration in Mautic
 
-* **Queue Mode** -  Select how to process Webhook events. The process immediately executes the Webhook event as soon as it arrives. The queue mode improves performance by only adding the event to the queue and requires processing by a :ref:`cron command<webhooks cron job>`.
+* **Queue Mode** -  Select how to process Webhook events. The process immediately executes the Webhook event as soon as it arrives. The queue mode improves performance by only adding the event to the queue and requires processing by a :ref:`Cron command<webhooks cron job>`.
 
 * **Order of the queued events** - Process the events in chronological or reverse chronological order if a Webhook has a queue of multiple events.