Read the job log

The Jobs tab of the administration page answers one question: what happens to this organization when nobody is pressing anything.

Open it at /matterdata/jobs on the organization’s own address. Only a login that carries the tenant administrator flag can open it. Read Manage logins for your organization for that flag.

What is in the log

One card per scheduled occurrence the organization has. Every organization has the engine’s own nightly housekeeping. An application adds one card per job it declares.

Name	What it does	Schedule
mtd_retention	enforces every table’s retention, then removes unreferenced images	every day at 03:00, in the application’s time zone
mtd_reset	replaces the organization with its stored template	the time you set. Present only when a reset is configured

An empty page is not an error. An organization gets its records the first time a running service reads the directory, and the page says so.

Read one card

Each card carries a state tag and three facts.

Tag	Meaning
Never run	there is a schedule and no run yet
Last run succeeded	the last run finished
Last run failed	the last run failed. The message is on the card
Last run stopped: time exceeded	the last run used its whole time budget
%d failures in a row	consecutive failures. At three the service also reports an error
Running now	a service holds the lease right now
Due	the next run is in the past and has not started

The facts are Next run, Last run and Duration in milliseconds. Times are drawn in the application’s time zone. The administration page is the engine’s own page, so a reader’s own time zone does not apply to it.

A scheduled run starts a little after its time rather than exactly on it. Every organization on a node would otherwise open its database in the same second. The spread is derived from the organization and the job name, so it does not wander between restarts:

• a job with a stated time, such as every day at 07:30, starts inside that minute. It is never moved into the next one.
• an every <period> job starts up to one period late, and at most one hour late.

A run marked due with Run now is not spread.

Mark one run due

Press Run now on a card.

The page executes nothing

The button writes “this occurrence is due” on one record and returns. The running service claims it, performs it under the same lease and the same time budget as a scheduled run, and records the result. The flash message says queued, not run.

Two waiting times, and the page names both:

• within a minute, while the serving process has this organization open.
• within an hour otherwise, when the scheduler next reads the directory.

The same act is available at a command line:

matterdata run-job -dir data -tenant my-club mtd_retention

The job name comes after the flags. Add -app <name> only when two applications in the organization declare a job with the same name. The command prints both waiting times, and it says so when another process holds the lease.

Three submissions are refused with a sentence, and none of them changes anything:

• a job this organization does not have, or no longer has.
• the reset. It has its own control, described in Reset a demonstration organization every night.
• a job whose record changed while the request ran.

An application’s own job does not run yet

A job you declare gets a card, a schedule and a clock. The script does not run. The runtime has no executor for an application-declared job. Every occurrence is therefore claimed, recorded as failed, and its clock advances so that the failure cannot repeat in a loop.

The card shows it as Last run failed, with a message naming the missing half. The service also reports it once per job when it first reads the declaration, so the fact is available before 03:00 rather than after it.

See Jobs and retention for the declaration and Project status for what is missing.

What the audit log records

Pressing Run now writes one admin.command event, kept for 365 days, naming the administrator and the job. A refused press records nothing.

Each run of the nightly housekeeping writes one job.run event, kept for 365 days. The event carries the outcome, the duration, the number of records written and the number of images removed. A successful reset is the one exception, because its own log is the file being replaced.

Read Security model for every class and its retention.