Document expiry alerts
A daily sweep looks at every employee document with an expiry date and raises an alert when it comes within 30 days, within 7 days, and when it has expired. Alerts go to the organisation's Admins and Managers and to the document's owner: once a month out, every day in the final week, and once on expiry. A document with no expiry date is never chased.
What has to be true before anything is chased?
The document needs an expiry date. The sweep selects on that column. A licence uploaded without one is invisible to it, permanently, and nothing on the Documents tab will tell you that — the row simply carries no expiry badge.
The document must not be archived. Archived documents are excluded from the sweep, which is the intended way to stop a superseded licence from alerting.
The document must belong to an organisation. Agency officers' documents are alerted through the separate agency compliance sweep, not this one, and are skipped here.
The scheduled job must actually be running. The sweep is one of the daily jobs that ShiftTracker's own background worker runs at 03:15 UTC, so no outside scheduler or secret is involved. A deployment where that worker is not running produces no alerts at all, and nothing in the app itself reports it. The same sweep can be run by hand from the server's cron route, which needs the shared cron secret.
How do I make sure a document gets chased?
- Upload the document with an Expiry date filled in. See Upload employee documents.
- If the date was missed at upload, open the row and set it — editing the expiry of an already-verified document also re-copies the new date onto the roster's own licence expiry field.
- Check the badge on the row. Anything inside 30 days shows a coloured Expires in Nd badge, and the header above the sections counts them as · N expiring soon.
- When the replacement arrives, upload it as a new document and archive the old one. Archiving stops the alerts.
What are the three windows?
The sweep runs once a day and puts each eligible document into exactly one of three states, based on today's date in UK time — the same day boundary for every organisation.
| State | When | Title on the alert | Priority |
|---|---|---|---|
| 30 days | Expiry is more than 7 days away but within 30 | Document expires in ≤ 30 days | Normal |
| 7 days | Expiry is today or within 7 days | Document expires in ≤ 7 days | High |
| Expired | Expiry is before today | Document expired | High |
The message names the document, its type, whose it is and the date: for example SIA Licence (licence.pdf) for Kirsty Fraser expires 2026-09-30. Clicking it opens that person's record.
The sweep only looks one day into the past. A document that expired last month has already passed out of the selection window and stops being alerted — the alert marks the moment of expiry, it is not a standing report of everything currently out of date. For that, use the badges on the Documents tab, which have no lower bound and read Expired Nd ago.
Each run is capped at 1000 documents, taken in expiry order so the most urgent go first. Anything past the cap waits for tomorrow's run.
Who gets told?
Every active Admin and Manager in the organisation, plus the owner of the document. Admins and Managers are taken to the employee's record; an owner who uses the employee portal is taken to their own documents page there instead. Control is deliberately not on the list, even though Control can see documents. Managers are on this list, which is worth noting because the missed check-call escalation uses a different set.
Delivery is three things at once, and only the first is guaranteed:
- An in-app notification, visible in the bell to exactly the people named above.
- A live push over the socket connection to anyone with the app open.
- One queued email to the organisation's contact address — not one per recipient, and one summary listing every document alerted that morning. That job goes through the Redis-backed notification queue, so on a deployment without Redis, or without the queue worker running, the email is the part that quietly does not arrive.
How often does the same document alert?
It depends on the window:
| Window | How often |
|---|---|
| 30 days | Once, on the first sweep after the document comes within 30 days. A month-out reminder repeated every morning is what teaches people to ignore alerts. |
| 7 days | Every day until it expires — up to eight times. The final week is meant to nag. |
| Expired | Once, the day after the expiry date. |
So a licence uploaded with an expiry two months away produces one alert a month before it runs out, one every day for its last week, and one the day after.
The "once" for the 30-day window is worked out from the notifications already sent for that document. Old notifications are eventually cleared out by the platform, so a document that sits in the 30-day window for a long time can occasionally be announced a second time.
There is no per-organisation control over the thresholds, the recipients or the frequency. The levers are the expiry date and the archive button.
What do the badges on the Documents tab mean?
The badges are computed in your browser when the tab loads, from today's date. They are independent of the sweep, so they are correct even on a deployment where the scheduled job never runs.
| Badge | Condition |
|---|---|
| Expired Nd ago | The expiry date has passed |
| Expires in Nd (red) | 7 days or fewer remaining |
| Expires in Nd (amber) | 8 to 30 days remaining |
| Expires 30 Sep 2026 (grey) | More than 30 days remaining |
| No badge | No expiry date recorded |
If it goes wrong
| What you see | What it means |
|---|---|
| No alerts at all, ever | The daily job is not running: the background worker is down. Nothing in the interface reports this. |
| Alerts in the bell but no email | The email leg goes through the Redis queue. Check the queue worker is up and that the organisation has a contact address on file. |
| A Control user says they never get these | Correct. Control can read documents but is not on the alert list. |
| A document you know is expiring is not alerting | Either it has no expiry date, it has been archived, or it belongs to an agency officer rather than an employee. |
| The same document alerts every morning | Expected in its final week. A month out it alerts once; inside 7 days, daily. |
| An expired document stopped alerting | Also expected. The sweep only reaches one day back; the row's own Expired badge is the standing record. |
Related
- Keep officers' compliance documents — how agencies are alerted about their officers
- Upload employee documents
- Check-call windows and escalation
- Permissions reference
Last updated 2026-11-17