Skip to content

EP Cron

EP Cron is the background-task scheduler for the EP Suite. Instead of every plugin carrying its own ?ep_*_cron= URL, one secret heartbeat drains every due task across every EP plugin, exactly once. Press Use hosted pulse and the ElmsPark pulse service calls that heartbeat for you, so there is no cron job to set up. A Background Tasks screen shows you the heartbeat, every registered task, its schedule, and its last result, so a silent cron failure becomes something you can see.

Published by ElmsPark Studio.

  • No cron line needed. The hosted pulse calls your heartbeat every five minutes. One button switches it on, and your own cron job remains an option.
  • One heartbeat for the whole suite. A single secret URL replaces the per-plugin ?ep_*_cron= endpoints. Point one system cron (or your host’s scheduler) at it.
  • Exactly-once. Every due task runs under a run-level lock and a per-task atomic claim with a fencing token, so a task can never double-run even if two triggers fire at once. This matters most for tasks that move money or send mail.
  • Observable. The Background Tasks screen lists every registered task with its schedule, status, last run, last result, and run count, plus the heartbeat’s freshness. A stalled cron shows up as a stale heartbeat instead of staying invisible.
  • Self-healing schedule. A crashed or timed-out task is reaped and re-queued; a task whose owning plugin is deactivated is pruned automatically.
  • Backoff on failure. A failing task retries with exponential backoff and full jitter, and dead-letters after its maximum attempts rather than hammering forever.
  • A registry for plugin authors. Any EP plugin registers a recurring task in one line; EP Cron owns the scheduling and the exactly-once guarantee.
  • PageMotor 0.11.5 or later (the heartbeat, the Background Tasks screen, and the API and MCP actions).
  • EP Suite base class.

EP Cron is optional for every other EP plugin: without it, each plugin keeps its own cron endpoint. With it active, those plugins register their work centrally and run off the one heartbeat.

  1. Download ep-cron.zip from the EP Suite downloads page.
  2. Upload via Plugins → Manage Plugins. Activate.
  3. Open Plugin Settings → EP Cron. Under Hosted pulse, press Use hosted pulse (below). If you would rather run your own cron job, copy the heartbeat URL instead.

Adding a cron line on a server is the one step many site owners cannot do. The hosted pulse does it for you: the ElmsPark pulse service calls your heartbeat every five minutes, with nothing to install on your server.

To switch it on, open Plugin Settings → EP Cron, find Hosted pulse, and press Use hosted pulse.

The pulse service then checks that you own the site. It does this by fetching a one-time code from your site’s address, which usually takes under a minute. The status then reads Active, and changes to Active — pinged once the first call arrives.

What it needs:

  • The site at the root of its own domain, such as https://example.com. A site installed in a sub-folder cannot be checked, so use your own cron job instead.
  • The site reachable from the internet when the check runs. A site behind a login wall, a maintenance page or a firewall will fail the check.
  • PHP curl on your server, which nearly every host has.

What it shares: your domain and your heartbeat URL, so the service can call it. The heartbeat URL triggers a run and returns a short run report. It exposes no site content.

To switch it off, press Stop hosted pulse. Background tasks then stop running until you add a cron job yourself.

EP Cron does its work when an external cron calls one secret URL:

https://your-site.com/?ep_cron_run=<secret>

The secret is generated once and checked with a timing-safe compare; a wrong or missing token returns HTTP 403 and does no work. The ready-made URL is on the EP Cron settings screen. The hosted pulse calls it for you. To call it yourself instead, point a system cron job or uptime monitor at it, every five minutes:

*/5 * * * * curl -s "https://your-site.com/?ep_cron_run=<secret>" >/dev/null 2>&1

Each beat takes a non-blocking run-level lock, so two overlapping beats cannot both drain the queue; the second simply bails. Keep the URL private (anyone with it can trigger a run, though it exposes no data).

The settings screen is a live dashboard:

  • Heartbeat status. Green when it last beat within the expected window, amber when stale, red when it has not beaten at all (your cron is not wired up).
  • Task table. Every registered task with its owner plugin, schedule, status, last run, last result, and total runs.
  • Run now. Force one task to run immediately.
  • Test now. Record a heartbeat by hand to confirm the plumbing.
  • Regenerate secret. Rotate the heartbeat URL. The old URL stops working immediately, so update wherever your cron runs.
  • Log retention. How long to keep the run history (7, 14, 30, or 90 days).
  • Pause all background tasks. The heartbeat keeps beating but no task runs. Use it during maintenance. A consumer that respects the pause (EP Newsletter does) holds its work until you unpause.

A plugin registers a recurring task in its construct(), guarded so it is a no-op when EP Cron is not installed:

if (class_exists('EP_Cron_Registry')) {
EP_Cron_Registry::schedule(
'my-plugin-task', // globally-unique key, prefixed with your plugin
EP_Cron_Registry::EVERY_5_MIN, // interval (named constants, floored at 60s)
array($this, 'run_my_task'), // handler: no args, returns an array (or throws)
array('label' => 'My plugin — what this does')
);
}

The handler runs only when due, and only ever once per due window. EP Cron has already taken the lock and claimed the job before it calls you, so the handler just does its (chunked) work and returns a summary array. Throw to signal failure and trigger backoff. Named intervals run from EVERY_MINUTE to DAILY.

EP Newsletter 1.4.1 is the first plugin to move onto EP Cron: its queue registers as ep-newsletter-queue and runs off the one heartbeat. See EP Newsletter.

”The heartbeat is red / no tasks are running”

Section titled “”The heartbeat is red / no tasks are running””

Nothing is calling the URL. If you use the hosted pulse, check that its status reads Active. If you use your own cron job, confirm the cron line is installed (crontab -l), the URL and secret are exactly as shown on the settings screen, and that a manual curl of the URL returns a JSON run-report rather than 403 (wrong secret) or an error.

It failed its maximum attempts and was dead-lettered. Check its last error on the Background Tasks screen, fix the underlying cause, then Run now to retry it.

”Hosted pulse could not confirm this site”

Section titled “”Hosted pulse could not confirm this site””

The pulse service could not fetch its check code from your site. That usually means the site was not reachable from the internet when it tried, or it sits in a sub-folder. Make sure the site’s home page loads from outside your network, then press Try again.

”I rotated the secret and now nothing runs”

Section titled “”I rotated the secret and now nothing runs””

Regenerating the secret changes the URL. If you use your own cron job, update it to the new URL shown on the settings screen. If you use the hosted pulse, press Stop hosted pulse and then Use hosted pulse again, so the service has the new URL.

”Tasks stopped after I ticked Pause all”

Section titled “”Tasks stopped after I ticked Pause all””

That is what it does. Untick Pause all background tasks to resume.

For a quick question about this plugin, EP Support inside your admin is the fastest option. The chat widget sits on every EP plugin settings page and knows which one you’re on, with starter questions and links preloaded for that exact screen.

For anything bigger — a bug report, a feature request, or a “how do I…” that needs a real reply — open a ticket at help.elmspark.com. A real person, helped by AI, writes the reply. Usually within a few hours. Tickets don’t disappear into the void.

  • Several sites on one database server no longer hold each other up. Each site’s background runner now has its own lock. Before, sites sharing a database server competed for one lock, so when two heartbeats arrived in the same moment one site could silently skip its run.
  • Forcing a task to run now needs an admin connection. A producer-level API key can still list tasks and check scheduler health, but can no longer force a task (such as a newsletter send) to run.
  • Needs PageMotor 0.11.5.
  • Nothing to do after updating.
  • Security fix for hosted pulse. The verification code the pulse service uses to confirm your site is now only published while the service is confirming it. Once it reports your site as active, the code is kept private. Nothing to do: pulse keeps running as before.
  • Not released on its own: this fix reaches you in 0.2.7.
  • Settings language menu. The language menu in this plugin’s settings now lists only the languages it is actually translated into, plus English, so you can no longer pick a language that changes nothing.
  • Corrects the PageMotor 0.11.3 preparation shipped in 0.2.3. That release grouped this plugin’s API and MCP actions into families, but in a shape PageMotor 0.11.3 does not accept. On 0.11.3 the plugin would have registered none of its actions, and nothing on screen would have said so.
  • This version uses the shape 0.11.3 expects, and keeps the earlier shape for sites still on an older PageMotor. One build serves both, so there is no order you have to update things in.
  • Safe to install now. Nothing you can see changes.