Adding campaign republish behavior docs

Author: escopecz

docs/campaigns/creating_campaigns.rst

@@ -51,6 +51,7 @@ To begin creating Campaigns, perform the following steps:
 
 -  **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 Republish Behaviour** - Configure how scheduled events with relative delays should behave when the Campaign is republished after being unpublished. You can override the global default setting for this specific Campaign. See :ref:`Campaign Republish Behavior<campaign republish 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

docs/campaigns/managing_campaigns.rst

@@ -31,4 +31,105 @@ The **Conditions** tab displays a tabular list of all he conditions that you hav
 
 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 republish behavior:
+
+Campaign Republish Behavior
+***************************
+
+.. vale on
+
+When you unpublish and then republish 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 are not affected by this setting.
+
+Configuring republish behavior
+===============================
+
+You can configure the republish behavior at two levels:
+
+1. **Global default** - Set in Configuration > Campaign Settings > Campaign Republish 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.
+
+Republish behavior options
+==========================
+
+There are three options available for how scheduled events should behave after republishing:
+
+Count delay regardless of publish state
+----------------------------------------
+
+This is the default behavior. The original trigger date is used and unpublished time doesn't affect scheduling.
+
+**Example scenario:**
+
+- Campaign trigger date: January 1
+- Event delay: 10 days
+- Calculated event date: January 11
+- Campaign unpublished: January 5
+- Campaign republished: 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 publish state as irrelevant to the delay calculation. Use this when you want consistency with the original schedule, or when temporarily unpublishing a Campaign shouldn't affect when events execute.
+
+Restart on republish
+--------------------
+
+The delay counter resets completely when you republish the Campaign.
+
+**Example scenario:**
+
+- Campaign trigger date: January 1
+- Event delay: 10 days
+- Original calculated event date: January 11
+- Campaign unpublished: January 5
+- Campaign republished: January 7
+
+**Result:** The event is rescheduled to execute 10 days after republishing, 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 unpublish a Campaign to make significant updates and want everyone to experience the complete updated workflow timing.
+
+Count delay only while published
+---------------------------------
+
+Events only count days when the Campaign is published. Unpublished 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 unpublished: January 5 (after 4 days published)
+- Campaign republished: January 10 (after 5 days unpublished)
+
+**Result:** The event is rescheduled to execute on January 16. The 4 days while published (January 1-5) count toward the 10-day delay, leaving 6 more days needed after republishing (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 publish date
+=========================
+
+On the Campaign details page, you can see the **Last Publish Date** which indicates when the Campaign was most recently published. This date is used as the reference point for the "Restart on republish" option to recalculate scheduled event timings.
+
+Publishing and unpublishing Campaigns
+======================================
+
+When you publish or unpublish a Campaign, Mautic displays a confirmation message that shows the current republish behavior setting. This helps you understand what will happen to scheduled events before you confirm the action.
+
+.. warning::
+    When you unpublish 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 republish 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 republish 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

@@ -158,6 +158,16 @@ Campaign settings
 
 * **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 Republish Behaviour** - Configure how scheduled events with relative delays in the middle of the workflow should behave when the Campaign is republished after being unpublished for a while. This setting provides a global default that can be overridden per Campaign. See :ref:`Campaign Republish Behavior<campaign republish behavior>` for more information.
+
+  Available options:
+
+  - **Count delay regardless of publish 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 published or unpublished during that period. This is the default behavior.
+  
+  - **Restart on republish** - The delay counter resets when the Campaign is republished. Events are rescheduled to execute the full delay period after the last publish date.
+  
+  - **Count delay only while published** - Events only count days when the Campaign is published. If the Campaign is unpublished, those days don't count toward the delay, and events are rescheduled accordingly when the Campaign is republished.
+
 Optimal for Contact event scheduler
 ===================================