Background tasks

P2Lab Mirakl runs 14 scheduled tasks in the background — they pull orders, push stock, refresh data, clean up old logs, and so on. None of them do anything unless two things are running on your host:

1. A scheduler that fires due tasks. On a Shopware installation this is the scheduled-task:run command, usually called from cron once a minute.
2. A worker that runs the dispatched work. This is the messenger:consume async command, kept running as a long-lived process.

Without the scheduler, tasks never become due. Without the worker, the dispatched jobs pile up in the queue and nothing happens.

The task catalogue

Each task runs at a default interval and can be re-tuned on the Shopware admin page Settings → System → Scheduled tasks. Sync-related intervals can also be set per feature on the Mirakl → Settings → Sync Settings tab — see Settings.

Task	Default interval	What it does
Stock sync	15 min	Pushes stock updates for all active offer mappings to the marketplace.
Order import	30 min	Pulls new and updated orders from each marketplace and creates them in Shopware.
Product export	30 min	Picks up products queued for export and sends them to the marketplace catalog.
Import status check	5 min	Polls running product, offer and stock imports for completion; fetches per-line error reports on failure.
Message sync	30 min	Pulls new inbound order messages. Off by default.
Order document sync	30 min	Pulls new inbound order documents. Off by default.
Document request sync	24 h	Pulls operator document requests (invoices, credit notes). Off by default.
Invoice sync	24 h	Pulls new invoices from the marketplace. Off by default.
Transaction log sync	24 h	Pulls new transaction log entries from the marketplace. Off by default.
Transaction log export poll	5 min	Polls the operator’s async transaction log export job and downloads the file when ready.
API log cleanup	24 h	Deletes API log rows older than API Log Retention (days).
Sync log cleanup	24 h	Deletes sync log rows older than Sync Log Retention (days).
Task progress cleanup	24 h	Deletes finished entries from the Tasks list.
Export cleanup	1 h	Deletes finished product-export entries and the generated CSV files.

Enabling and disabling each sync

Each sync has its own master switch on the Mirakl → Settings → Sync Settings tab. When a switch is off, the scheduled task still fires on its interval but the handler simply skips it — no marketplace call is made, no permanent state is changed. Flipping the switch off is the recommended way to pause a sync.

By default:

• Enable Stock Sync, Enable Order Import, Enable Product Export — on.
• Enable Message Sync, Enable Order Document Sync, Enable Document Requests Sync, Enable Invoice Sync, Enable Transaction Log Sync — off. Switch them on as you need them.

The four cleanup tasks (API log cleanup, Sync log cleanup, Task progress cleanup, Export cleanup) don’t have a switch — they always run. They use the retention settings on the Logs card of the Mirakl → Settings → Options tab.

Long-running operations triggered from the admin

When you trigger something from the admin that takes a while — a manual export, a manual sync, refreshing reference data, a wizard step with a progress bar — the plugin creates an entry in the Tasks list (Dashboard → Quick Start → Tasks) that the admin polls for progress.

Each entry passes through these stages: waiting → in queue → processing → completed (or error, or cancelled). The list shows the percentage and the latest message. The Task progress cleanup task removes finished entries after a day.

Recovery if a worker dies

The plugin is built to survive worker restarts without losing or duplicating work:

• Self-chaining batches — long uploads dispatch the next page before returning, so a crash mid-batch loses at most one page. The next scheduled run re-discovers it and resumes.
• Cursor-based syncs (order import, message sync, document sync, invoice sync, transaction-log sync) remember where they got to last time. A crash restarts from the same cursor on the next run — no duplicates, no skipped records.
• Throttle locks — the one-minute pacing lock (see API throttling) automatically frees itself after a short delay if the worker that was holding it died.

Tips and gotchas

Tip

If your queue grows faster than it drains, scale to multiple worker processes. They coordinate with each other through the pacing lock so they won’t double-spend the rate budget.

Caution

Don’t run the scheduler command as a long-lived process — it’s a one-shot that fires the due tasks and exits. Either run it from cron every minute, or use Symfony’s --time-limit / --max-iterations options to keep it bounded.

Note

The configured interval is a minimum, not a guarantee. If your cron only fires the scheduler every five minutes, then five minutes is the smallest possible gap between two runs of the same task, regardless of what you set on the Sync Settings tab.

Caution

For multi-host worker setups, configure a shared lock store (Redis or Doctrine) for Symfony Lock — otherwise the hosts won’t coordinate their pacing and you may consistently see rate-limit messages from the marketplace. See API throttling.

Related

• Sync logs — what each task writes
• API throttling — how the plugin paces its own calls
• Settings — all the configurable intervals and switches
• Reference → Enums — the values used in the Tasks list