# Cronjob

> Cron job scheduler service for webtrees

---

![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)
![webtrees major version](https://img.shields.io/badge/webtrees-v2.2|v2.3-green)

A **cron job scheduler service** for webtrees: schedule maintenance/batch jobs with standard cron expressions, watch their run history in the admin UI, and trigger them manually. The module is the *service*; the OS (classic cron or a systemd timer) only has to call one small script once per minute.

- **Job registry + run history** in two own tables (`cj_job`, `cj_run`)
- **Admin UI** (control panel): job list, create/edit form, run history, run now, enable/disable, delete
- **Isolated execution**: every job runs as a separate child PHP process ([`proc_open`](https://www.php.net/manual/en/function.proc-open.php), no shell), with per-job timeout and captured output
- **Self-registration**: other modules can advertise their jobs (a <a href="https://github.com/bschwede/wt-cronjob/tree/main/cron-jobs.php" target="_blank" rel="noopener"><code>cron-jobs.php</code></a>
 manifest or a `getCronJobs()` method); they appear here, created disabled and ready to enable
- **Event-driven jobs**: jobs can fire on events instead of a schedule — queued by a token-protected **webhook**, by a direct `EventQueue::push()` call from other modules, by the built-in **pseudo-event** pollers, or by **route events**
- **Failure notification**: per-job opt-in to alert the site's administrator accounts when a job fails
- **Offline awareness**: while `data/offline.txt` exists the tick is skipped before any database access
- **No core changes, no changes to other modules**

![Cronjob Scheduler](img/cj/cronjob-scheduler.png)

It was originally developed as a support module for [LinkEnhancer](../linkenhancer) to keep its indexes up to date.

## Support

- **Issues**: for any ideas you have, or when finding a bug you can raise an [issue](https://codeberg.org/bschwede/wt-cronjob/issues).
- **Translations**: [Contribute on Codeberg Weblate](https://translate.codeberg.org/projects/wt-modules/cronjob/)

---

Section pages:

- [Setup](/wt-modules/en/docs/cronjob/setup/): Installation and requirements
- [Usage](/wt-modules/en/docs/cronjob/usage/): Creating jobs, run history, and the admin UI
- [The Tick](/wt-modules/en/docs/cronjob/tick/): How the once-a-minute tick schedules and runs jobs
- [Events](/wt-modules/en/docs/cronjob/events/): Event-driven jobs, webhooks, pseudo-events, and route events
- [Howto](/wt-modules/en/docs/cronjob/howto-use/): How can other custom modules make use of this cronjob module?
- [CLI Scripts](/wt-modules/en/docs/cronjob/cli-scripts/): Command-line scripts and maintenance
- [Security](/wt-modules/en/docs/cronjob/security/): Security model and command validation