Medical & insurance guide

One switchable module, two registers that are usually run by two different people — and two separate permissions to match, because occupational health holds data that benefits administration has no business reading. Where an install does both jobs with one person, grant them both.

• Medical fitness — the register of examinations, the catalogue of examination types, the rules saying who must hold what, and the matrix that turns a pile of certificates into an answer to "who is overdue".
• Group insurance — the insurers, the policies, one row per covered life (staff and their family alike), the renewal chain, and the list of people on the roll holding no cover today.

Examination types is the list of medicals your company tracks. It is data rather than a fixed list in the software, because validity periods differ by client and by regulator: a resort adds Dive medical, a vessel operator adds whatever their flag state asks for, and neither needs us to ship a new version.

Each type carries:

• A short code — used as the column header on the compliance matrix and in exports, so keep it short: FOODH, ANNUAL.
• A validity in months, which pre-fills the expiry date when an examination is recorded. Leave it blank for something done once — a pre-employment screen does not lapse.
• Certificate expected, which decides whether a record with no file attached is flagged as incomplete evidence. A food-handler card is asked for by an inspector; an internal fitness-to-return check is not.

Six types ship with the app so a new instance is usable on day one — pre-employment, periodic/annual, food handler, seafarer (ENG1 / STCW) on a two-year cycle, fitness to return to work, and a drug & alcohol screen. Edit them to match your own regulator. Seeding only ever runs into an empty catalogue, so your validity periods and retirements are never undone by an update.

A type that has examinations recorded against it is deactivated rather than deleted — an inspection export must never render a row as an unnamed medical. Deactivating hides it from the pickers and leaves history intact.

Open the person's card, expand the Medical fitness fold and choose Add examination. The closed line of that fold already shows the latest verdict and its expiry — "Fit · expires 12/03/2027" — because that is usually all the permit chase came for.

The examined-on date is the evidential one an inspector reads off the certificate, so it is required even when nothing lapses. The expiry is pre-filled from the type's validity and can then be overridden: a doctor may clear somebody for six months where your table says twelve, and the certificate in hand outranks the policy table.

The outcome is a fitness-to-work decision, and there are five:

A re-examine link appears on a current row whose type lapses. It records the new examination as a new row that supersedes the old one — history stays readable and greyed rather than being overwritten, which is what lets you answer "was this person cleared last March" a year later. Delete a re-examination and the one it replaced becomes current again.

The register opens on current examinations only — that is the current:yes chip above the box, and removing it widens the list to every superseded row in every chain. Everything else about the box works as described in the filtering guide; try outcome:Fit expiry:<=+30d.

A register of certificates cannot tell you who is missing one, because a gap is the absence of a row. Medical requirements is where you say who owes what, and it is the thing the compliance matrix is computed from.

A rule names one examination and up to four scopes — company, department, designation and work site. They are combined with AND, and a blank scope means "any":

• All four blank → every member of staff. Everyone has a pre-employment screen.
• Designation = Cook, the rest blank → every cook, in every company, on every site. Every cook holds a food-handler medical.
• Designation = Deckhand + Site = the vessel → only deckhands on that vessel.

Grace days — 30 by default — is how long a new joiner has from their joining date before a missing examination counts against them. It matters more than it looks: without it the screen flags every arrival on their first morning, the breach count never reads zero, and a compliance board that is never green stops being read inside a fortnight.

Clearing mandatory makes the rule advisory. It still shows as a column on the matrix, but a gap against it never counts as a breach — useful for a medical you would like people to have without pretending it is a legal gate.

Medical compliance is the grid: your people down the side, the requirements that apply to them across the top, and one cell per pair. It is the screen you take into a meeting, and its export is the artefact an inspection actually receives.

A cell can also be a faint dot: the rule does not apply to that person — a blank, not a pass. Nothing is owed, so nothing is missing.

The headline tiles distinguish two things that sound alike. Compliant means nobody on that row is in breach. Cleared means every mandatory examination they owe is actually on file and unexpired — a new starter inside their grace window is compliant but not cleared, and counting them as cleared would read as more people fit for work than there are.

Narrow by site, department or examination, or tick breaches only to get the worklist. Export CSV writes one row per person per requirement rather than a grid — a spreadsheet of cells cannot be filtered or pivoted by whoever you send it to.

This module records whether somebody can safely do their job, and with what limits. It has no field for a condition, a test result or a diagnosis, and that is a deliberate constraint rather than an omission: health data is special-category data, and the employer's legitimate interest stops at the fitness verdict. The clinical detail belongs with the examining clinic, not in a system hundreds of people hold a login to.

The second half of the model is field by field, and it is what makes the module usable:

• Anyone with medical.view reads the verdict, the dates and the status — enough to run the permit-renewal chase without opening anybody's paperwork.
• sensitive.medical on top unlocks the restrictions, the clinic name, the certificate number and the certificate file itself. Grant it to occupational health, not to everyone.
• sensitive.pay covers what the examination cost, like every other money column in the app.

Exports leave gated columns out entirely rather than filling them with bullets, and the audit entry records that they were left out — a file with a "Clinic" column full of masks still tells the reader the column exists and how many rows have one filled in. And editing an examination without the medical claim never erases what you cannot see: those values are carried over from the stored row, so correcting an expiry date cannot wipe the restrictions keeping somebody off night shifts.

Insurers comes first. An insurer is a row rather than a name typed on each policy for three reasons that all bite in practice: staff need to know who to ring to claim, the insurer stays the same across renewals while the policy number does not, and "cost by insurer" stops meaning anything the moment somebody types both "Allied" and "Allied Insurance". Nothing is seeded here — who underwrites you is a fact about your company.

Two fields on the insurer are worth filling in properly, because they are the ones an employee uses at the worst possible moment: the claims hotline, which becomes a tap-to-call button in the staff portal, and the network URL, which links to the insurer's own list of clinics. That is a link rather than a list we keep, on purpose — the insurer's page is the one that is right today, and a copied list is wrong the month a clinic leaves the network.

Policies is the contract: insurer, policy number, an internal name you will recognise ("Group Medical 2026"), the cover type (medical, dental, vision, life, accident, travel or workers' comp), the term, the sum insured per life, the age a child ages off, how far ahead the renewal should be chased, the broker, and the policy document itself. Leave company blank for a group scheme bought at holding level; set it to scope the contract to one legal entity.

The list is ordered the way the question runs — what needs doing, what is running, what is coming, what went wrong, what is history. A policy with covered lives on it cannot be deleted: those rows are the evidence those people were insured. A finished policy simply ends on its end date.

Renewing records a new policy that points back at the one it replaces — never an edit of last year's dates, because overwriting them destroys the evidence that somebody was covered when they made a claim, and claims are settled months after the period they belong to. A renewal has to be with the same insurer and for the same cover; a chain that jumps between contracts is a filing error, not history.

Once the renewal is on file, its page offers to bring the previous contract's covered lives across. The plan is recomputed the moment you click rather than taken from the page you are looking at, so a stale tab cannot re-add somebody you have just removed. It then tells you exactly who it left behind and why:

• Already enrolled here — added by hand, or by an earlier run.
• No longer on the roll — the scheme is smaller this year, which is not an error.
• Past the child age limit — the one exclusion worth checking by eye, because it is the family member who thinks they are still covered.

Premiums come across exactly as they were — check them against the renewal schedule, since that is the number the insurer has just changed. Member cards do not come across at all: the insurer reissues those, and last year's number at a reception desk is worse than none.

Enrolment happens on the employee's card, in the Insurance cover fold — not on the policy page — because adding a life needs that person's family list, which is their personal data rather than a property of the contract. The fold's closed line carries the claims hotline for exactly the reason the portal does.

There is one row per covered life: the employee's own, plus one for each dependant on the same policy. That is why the cover tier — Self, Self + spouse, Family — is never a field you set: it is counted from the rows, so it cannot disagree with reality the moment a child is added. Each row carries the member number and the card scan, both of which need Sensitive · Personal, because they identify a named person to the insurer.

A few rules the form will hold you to:

• Cover cannot start before the policy does — a back-dated enrolment reads as though it were true, and the date is what a disputed claim turns on.
• A dependant can only be enrolled against their own employee.
• The same life cannot be enrolled twice on one policy.
• You can enrol on any policy that has not yet run out, including one whose renewal is already on file.

Ending cover is also one of the five exit-clearance gates: a leaver with cover that has no end date — theirs or a dependant's — blocks offboarding sign-off, because cover with no end date is cover the insurer still believes in.

Uninsured staff is everybody on the roll holding no live cover today. Unlike the medical side it needs no rule table, and that is worth understanding rather than working around: a medical recurs on a cycle that differs per job, so somebody has to say which job needs which; being insured does not — being on the roll is the rule.

Narrow by cover type to ask a sharper question — everyone has medical, only the crew have accident — and by site or company. The export sorts people into three states that mean different things: never enrolled, cover lapsed (with the date it lapsed and how many days ago), and not started for an arrival whose first day has not come, who is not late and never appears as such.

If no policy is live at all the screen says so instead of listing your whole workforce — true, and useless. The answer there is to record the contract, not to chase four hundred people.

The nightly expiry scan covers both registers on the same 90 / 60 / 30 / 7 / 0-day ladder as passports and permits, alerting once as each threshold is crossed rather than every night — see the expiry alerts guide for who receives them. Two passes, because they are two different acts:

• Medical clearances — per person, so somebody can be chased. Only examinations that actually cleared someone and carry an expiry ride the ladder.
• Policy renewals — once per policy, not once per covered life. When a group policy lapses every life lapses with it, and chasing that per person would put four hundred notifications in one inbox overnight and train everybody to filter the sender.

Analytics › Compliance carries the module's headline numbers — uninsured staff, policies renewing within 90 days, medicals expired, medicals due within 30 days, and how many people carry a verdict that limits where they can be deployed — plus a covered-lives-by-insurer breakdown you can click into.

Four exports leave the module: the medical register, the compliance matrix, the insurance census (the file a broker asks for once a year, and most of why the cover register exists) and the uninsured list. Both registers are also sources in the report builder if you want your own columns.

Where the staff portal is on, each employee gets a My insurance page: who insures them, the policy and cover limit, since when, their member number, their card to download, and the family members covered alongside them. At the top sit the two things somebody standing at a clinic reception actually needs — a tap-to-call claims hotline and a "Where can I go?" link to the insurer's own network list.

It is read-only by design. Cover is a contract between the employer and an insurer, not something staff can self-assert; what the page fixes is that the system already knew the answer to "am I covered and who do I call" and the only route to it used to be asking HR. Last year's contract drops off once it ends, so nobody quotes an expired card number at a desk.

Premiums are never shown there. Medical records are not in the portal at all — fitness examinations stay with HR and occupational health.

• Medical · View — the register, the compliance matrix, the verdict and the dates. Medical · Manage — record examinations, edit the catalogue, write the requirement rules.
• Insurance · View — the policy list, the cover register, the uninsured screen. Insurance · Manage — create policies, enrol and end cover, run a renewal, maintain the insurer list.
• Sensitive · Medical — restrictions, clinic, certificate number and the certificate file. Occupational health, not everyone.
• Sensitive · Personal — member numbers, card scans and dependants' names. Sensitive · Pay — premiums and examination costs.
• Turning the module on takes three steps, not two: deploy, flip the feature flag, then grant the permissions in Roles. Role defaults only ever seed a role that has no claims at all, so on an existing install nobody except Admin picks up a newly added permission automatically.

Worth remembering

• Premiums are recorded, not deducted. Both shares sit on the cover row for the census and for costing; nothing reaches a payslip on its own. Recover the employee's share through an ordinary recurring payroll deduction.
• Filing next year's policy does not end this year's cover — the dates do.
• Cover ends, it does not get deleted; an examination is superseded, not overwritten.
• An examination type or an insurer that is in use is deactivated rather than deleted.
• The validity period only pre-fills an expiry date; the certificate in hand overrides it.
• "Awaiting certificate" never counts as fit, and shows as not cleared on the matrix.
• Advisory requirements never count as breaches; a new starter within grace is not a breach either, but they are not cleared yet.
• The medical register opens on current examinations only; the cover register has no such default, because a cover row has dates rather than a current flag.
• No alert fires for a dependant ageing off — check the age limit at renewal.