Skip to content

Background Jobs Run Now PR Review

Ed Mozley edited this page Nov 14, 2026 · 1 revision

Run now on Background jobs, and who ran what - PR review

PR #345 by vsc55 Β· Closes #343 Β· Verdict: merge, with fixes Β· 5.3.0

To run a scheduled job outside its schedule - to check a fix, or to sync now rather than in six hours - you had to find the job's own page, if it had one, or a command line on the server. Each scheduled job on Reporting β†’ System logs β†’ Background jobs now has a Run now button beside Edit: it starts the job at once, as its own process, exactly as the built-in scheduler would, and the run is recorded as Run now with who pressed it. vsc55 added an audit trail on top: every press is on the record, a refused one too, and the run history says who started each run. User page: Background jobs Β§6a. Internals: Background jobs - Developer Guide Β§5a.

What was checked

Question Result
Can the request choose what runs? No - jobRunNow() takes only a job key; the command is the registry's, parsed by jobSchedulerCommand() (`php cron
Who may press it? Whoever may change the schedules (jobHealthMayConfigure(), the "Change what background jobs are expected to do" permission); a viewer gets 403
Can a GET run a job? No - run_now is a POST action only; tests/get-must-not-write.php passes
Does it change the schedule? No - job_schedules is not touched
Twice at once? Refused while a run started within the job's max_runtime is still running - and the job's own run lock would turn a second one away anyway
Is every press recorded? Yes - started, it is a manual run with the analyst's id; refused (not needed, running already, could not start), it is a skipped manual run by whoever pressed it, with the reason
Does the child know who pressed it? Yes - FREEITSM_JOB_TRIGGER=manual and FREEITSM_JOB_ANALYST, read by JobRun::scheduledTrigger() and JobRun::start() - given to that process only after the merge (fix 2)

On the test install: tests/job-run-now.php 24 checks (15 in the PR as submitted) - including a real process told it is Run now, popen / proc_open disabled, and the endpoint (403 for a viewer, GET never runs, an unknown job refused); vsc55 also reported tests/job-scheduler.php 38/38 and tests/job-health.php 35/35, and ran API activity log tidy-up from the browser.

What was changed on merge

  1. A server with popen / proc_open disabled gets could not be started, recorded, instead of a PHP error: PHP 8 throws calling a disabled function, so jobSchedulerSpawn() checks function_exists() first and returns false.
  2. Only the new process is told it is Run now, and by whom. The PR set FREEITSM_JOB_TRIGGER / FREEITSM_JOB_ANALYST with putenv() and put them back afterwards. putenv() changes the whole process, so in a threaded server (Apache's mpm_winnt, a ZTS build) another request starting a job at that moment would have recorded it as somebody's Run now. jobSchedulerSpawn() now takes the variables as an array and gives them to proc_open() as the child's environment.
  3. api/reporting/job_health.php no longer returns an exception's own text - unexpected errors are logged and the caller gets a fixed sentence; only its own messages (Unknown job.) are shown.
  4. The button is hidden for a job that is not needed here (its status is Not needed).
  5. Run now runs a job whose schedule is Off, as decided below - written into the jobRunNow() docblock and a new help paragraph (reporting.help.s3_jobs_run_now).
  6. Tests: tests/job-run-now.php 15 β†’ 24 checks.
  7. Changelog ids renumbered to #2935 (the feature) and #2936 (the merge fixes) - the PR's #2929, then #2927, had been taken.
  8. Translations of the new strings into the eight maintained languages; this write-up, the user page, the developer guide, a Feature Bingo card and vsc55's entry on the Contributors page.

Decided

  • Run now takes only the registry's command - nothing from the request reaches a shell (Ed, 2026-11-14).
  • Who pressed it is recorded, on the run, and on a refused press too (Ed, 2026-11-14).
  • It still runs a job whose schedule is Off. Off means "the scheduler does not start it"; the person pressing Run now is asking for that one run. The schedule stays Off (Ed, 2026-11-14).

Worth knowing

  • proc_open() with an environment array: jobSchedulerSpawn($php, $script, $args, $env) merges $env over getenv() and passes it as proc_open()'s $env_vars. Without $env it still uses popen(), as the scheduler and the fallback always did. The shell returns at once; the job carries on detached.
  • A Run now does not prove the schedule works. Rule 1 of job health still holds: only scheduled runs keep a job healthy, so a job whose cron line has gone turns overdue however often somebody presses Run now.
  • The PHP it starts is intuneFindPhpExe()'s, with the Intune PHP setting as the override - the same one the fallback uses.
  • "Who started it" in the run history, a job's Last run and a run's details: the analyst's name, or System for a schedule, the fallback or a token address.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally