From e670d37424cfcc20c0cc0c49bbbbcf87775d7bd6 Mon Sep 17 00:00:00 2001 From: Rohit Pavaskar Date: Tue, 12 May 2026 19:01:31 +0530 Subject: [PATCH] Add documentation for mautic:campaigns:resume-stuck command Document the new command that resumes execution for contacts stuck in campaign workflows. This command helps recover contacts that got stuck due to exceptions, server issues, or events added after contacts had already progressed past that point. Related to: mautic/mautic#15310 --- docs/configuration/command_line_interface.rst | 3 ++ docs/configuration/cron_jobs.rst | 48 +++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/docs/configuration/command_line_interface.rst b/docs/configuration/command_line_interface.rst index 5e3a4429..a8f5a5dd 100644 --- a/docs/configuration/command_line_interface.rst +++ b/docs/configuration/command_line_interface.rst @@ -89,6 +89,9 @@ These are the commands you may need to use in relation to your Mautic instance. * - ``mautic:campaigns:rebuild`` - Rebuild Campaigns based on Contact Segments. - ``mautic:campaigns:update`` + * - ``mautic:campaigns:resume-stuck`` + - Resume execution for Contacts stuck in Campaign workflows. + - * - ``mautic:campaigns:trigger`` - Trigger timed events for active Campaigns. - diff --git a/docs/configuration/cron_jobs.rst b/docs/configuration/cron_jobs.rst index 26ab7063..810aee81 100644 --- a/docs/configuration/cron_jobs.rst +++ b/docs/configuration/cron_jobs.rst @@ -87,6 +87,54 @@ Since Mautic 5.1, Mautic triggers Campaigns in order from newest to oldest. This that these messages are only added to the queue when frequency rules apply either system wide or per Contact. +Resume stuck Campaign Contacts cron job +======================================= + +Sometimes Contacts can get stuck in Campaign workflows due to exceptions, server issues, or Events being added after the Contact has already progressed past that point in the Campaign. The ``mautic:campaigns:resume-stuck`` command identifies and processes these stuck Contacts. + +.. code-block:: php + + php /path/to/mautic/bin/console mautic:campaigns:resume-stuck + +This command: + +- Finds Contacts that are stuck at specific points in a Campaign due to previous exceptions or errors +- Identifies Contacts where new Events were added after they had already executed parent Events +- Resumes execution for these Contacts so they can continue through the Campaign workflow +- Ignores Contacts that were manually removed from the Campaign +- Skips scheduled Events that haven't been executed yet +- Doesn't process decision Events as they require Contact interaction + +Command parameters: +~~~~~~~~~~~~~~~~~~~ + +- ```` (required): The ID of the Campaign to process. + +- ``--dry-run``: Find stuck Contacts and their next Events without actually executing them. Useful for previewing what the command would do. + +- ``--batch-limit=X`` or ``-l X``: Set the batch size of Contacts to process per round. Defaults to 1000. + +- ``--min-contact-id=X``: Process only Contacts with ID greater than or equal to this value. + +- ``--max-contact-id=X``: Process only Contacts with ID less than or equal to this value. + +Example usage: + +.. code-block:: php + + # Preview stuck contacts without executing events + php /path/to/mautic/bin/console mautic:campaigns:resume-stuck 5 --dry-run + + # Process stuck contacts in campaign 5 with smaller batches + php /path/to/mautic/bin/console mautic:campaigns:resume-stuck 5 --batch-limit=100 + + # Process a specific range of contacts + php /path/to/mautic/bin/console mautic:campaigns:resume-stuck 5 --min-contact-id=1000 --max-contact-id=2000 + +.. note:: + + This command only works with published Campaigns that aren't deleted. It processes a maximum of 5000 records in a single execution to prevent performance issues. + .. vale off Custom Field cron jobs