Applying for a permit

Raising a permit, linking its entities, submitting it for approval, and handling corrections, withdrawal, extension and reissue.

For Contractor applicant / requestor

Your role

You are the person on the ground who needs a job authorised — the subcontractor foreman, gang lead, or any verified site member (member and above). You raise the permit in-app, place the workers/plant/areas it covers and link them to it as its spatial footprint, tick the pre-work checks, quote your RAMS reference, and submit it into the approval chain. You own the permit while it is a draft or in corrections_requested — only you (or a superadmin) can edit, submit, withdraw, or delete it. Once you submit, the permit walks the approval chain out of your hands, but you stay in the loop: you are usually the named receiver, so the live walk-down ends with you countersigning to start work.

Note: A permit has no geometry of its own — there is no permit pin on the map. Its footprint is the entities you link to it. If nothing is linked, the permit has no place on the map.

What you can and can't do

You can:

Raise a new permit (creates a draft owned by you).
Edit, submit, withdraw, or delete your own draft.
Link/unlink placed entities (workers, plant, areas, deliveries) — but only while the permit is draft or corrections_requested.
Spawn entities pre-filled from a permit.
Request an extension on a live (issued) extendable permit (UK default: only General is extendable).
Reissue a spent permit (issued/expired/closed) into a fresh draft clone.
Edit and resubmit a permit that bounced back as corrections_requested.
Countersign at the walk-down when you are the named receiver.

You can't:

Endorse (stage-1) — that is the coordinator band.
Approve (stage-2) — that is the HSE/admin band.
Reject or request corrections at a gate (unless you happen to be the acting gate band).
Issue at the walk-down — that needs a Permit Appointment (an authorised-issuer record), which is granted, not implied by your role.
Edit, submit, withdraw, or link on another user's permit — the system returns 403 (PermitOwnershipError).
Edit or link after submission — link/unlink is locked once you leave draft/corrections_requested.
Decide extension requests (stage-2 only).
See another contractor's drafts or in-review permits — a permit you may not see returns 404 (its existence is hidden, not just blocked).
Upload XLSX permit batches, re-resolve locations, or touch permit types / appointments / site policy (those need coordinator or HSE/admin).

Note: Your board is contractor-scoped. You see your own drafts, your own contractor's in-review permits, and all the site-public issued/expired/closed permits. You do not see another subcontractor's in-flight work.

Your tasks

Task 1 — Raise a permit and submit it

There are two ways in. Both produce the same thing: a draft you own.

Route A — start from the type:

Press P (or click the dock toggle, tooltip "Open permits (P)") to open the Permits dock panel.
Click New permit (permit-board-new). A type picker lists the permit types configured for this site (e.g. General / Hot Works / Confined Space Entry — each shows a name + short code).
Pick a type. The system calls POST /permits/applications, creates a draft with you as requestor_id, and opens the apply workbench.

Route B — start from a selection:

Select the tokens you want on the map (the workers/plant/areas this permit covers).
Trigger request over selection. The system creates a default-type draft and links your selection to it in one go, then opens the apply workbench.

Then, in the apply workbench:

In the "Place under this permit" armed-tools row, arm a tool — Worker, Plant, or Work area — then click on the map to place a token. The map stays live behind the panel. Use the big dashed Add token affordance ("Arm a tool, then click on the map") if you prefer.
Placed/linked entities appear in the Linked entities tray, each with a label, its kind, and an unlink ×. Empty tray reads "Nothing linked yet — arm a tool and place, or request over a selection."
Tick the Pre-work checks (these save into the permit's pre-check results) and enter your RAMS reference. The expected attachments list (e.g. RAMS, Rescue plan) is a prompt only — nothing forces an upload.
When the footprint and checks are right, click Submit (btn-primary, enabled once can_submit and at least the basics are filled).

What the system does on Submit (POST .../submit): it validates the type is active and start_at < end_at; if the type requires_parent, it checks there is an active General parent whose window contains yours; it mints the permit number as CODE-NNNN (e.g. HW-0001) under a database lock; and it stamps submitted_at. The permit moves draft → requested.

Note: Your permit has no number while it is a draft — the CODE-NNNN number is minted only at Submit, so don't expect to quote a permit number before you've submitted. And if your type requires_parent (Hot Works, Confined Space Entry, Working at Height, Excavation, Electrical all do by default), Submit will be rejected unless an active General permit already covers your location and your whole window sits inside the parent's window — raise the General parent first.

Task 2 — Link entities as the permit's footprint

The permit's spatial life is its linked entities, so this is the core of authoring.

In the apply workbench, arm a place-tool and place a token, or select already-placed tokens and link them.
Each link calls POST .../link. The system returns the authoritative linked list, which replaces the tray contents and updates the map lens together.
To remove one, click the × on its tray row (POST .../unlink).
To spawn a fresh entity already filled from the permit (contractor, description, controls, window, pre-checks), use create-entity (POST .../create-entity) — handy when the worker/crane/work-area doesn't exist yet.

Note: You can only link entities belonging to your own (or an oversight-supervised) contractor — linking someone else's entity is refused. Linking is also draft-only: once you submit, the footprint is frozen — you cannot add or remove linked entities in requested/endorsed/approved. If you got the footprint wrong, either request corrections will bounce it back, or you withdraw and start again.

Note: Selecting a permit on the board lights the map lens (linked entities glow, everything else dims) but does not move the time scrubber. If the scrubber is parked outside the permit's window, the lens can look "lit empty" — use the "N tokens outside this time — jump to window" pill to jump the scrubber to the permit's start.

Task 3 — Track, withdraw, or discard your work in progress

Open the Permits panel (P). Your in-flight permits sit under the "My drafts & corrections" section of the board (private to you).
To pull a submitted-but-not-yet-live permit out of the chain, open it and Withdraw (can_withdraw; POST .../withdraw). Allowed from requested, endorsed, or approved. The permit moves to withdrawn (terminal) and any open gate Tasks on it are closed so nobody is left holding a stale task.
To bin a draft you haven't submitted, Discard (can_delete; DELETE .../{id}). Delete is draft-only — once submitted you can't delete, only withdraw.

Note: Withdraw is terminal. A withdrawn permit doesn't re-enter the chain — if you still need the work authorised, reissue it (Task 6) into a fresh draft.

Task 4 — Fix a permit that came back for corrections

If a reviewer bounces your permit, it lands in corrections_requested with their note attached.

You'll be notified ("Permit {number} needs corrections", with the reviewer's note in the body). Open it from My drafts & corrections.
It is editable again (it behaves like a draft) — adjust the footprint, pre-checks, RAMS, or window per the note.
Submit again (POST .../submit). The approval chain restarts at requested — endorsement and approval happen afresh.

Note: Corrections restart the whole chain, not just the failed gate. A stage-2 bounce still re-runs stage-1 endorsement on resubmit.

Task 5 — Countersign at the walk-down to go live

You are usually the named receiver (receiver_id defaults to the requestor), so taking the permit live is on you. The walk-down is a dual signature: the appointed issuer signs first, then you countersign — and your countersign is the action that actually makes the permit live.

After the appointed issuer signs, you get a permit_awaiting_countersign notification deep-linking you to sign.
Open /permits/:id/countersign (phone-friendly route). Read the Conditions of issue (read-only).
Tick "I accept these conditions".
Press Countersign & start work (enabled once can_countersign and you've accepted). This calls POST .../countersign: the permit flips approved → issued (LIVE), permit_issued fires, and the PDF is frozen to storage.

Note: Countersign is identity-gated: only the named receiver can do it. Even if the issuer is ready, the permit stays approved (an "awaiting countersign" flag) until you sign. The issuer signing alone does not make it live.

Note: Countersign is not a Task — there is no card in My Work for it. You reach it from the notification or its URL. (Only the issuer's walk-down gets a Task card.)

Task 6 — Extend a live permit, or reissue a spent one

These are two different tools — know which one applies.

Extend (stretch a live permit's end time in place, no re-issue):

The permit must be issued and its type must be extendable (UK default: only General).
In the permit detail body, open Request extension (can_request_extension). Pick a New end (datetime-local) that is later than the current end, add an optional reason, and Submit request.
This calls POST .../extensions. One pending request at a time. A child permit's new end can't outlive its parent.
The stage-2 band (HSE/admin) decides it. If approved, end_at moves in place — the status stays issued (it is not a new permit).

Reissue (clone a spent permit into a fresh draft):

Use this when the permit is issued/expired/closed and you need to authorise the work again — and especially when the type is not extendable (Hot Works, Confined Space Entry, etc. cannot be extended; they must be reissued).
From the permit, choose Reissue (can_reissue; POST .../reissue). The system clones type, parent, contractor, description, controls, window, and pre-checks into a fresh draft owned by you, with reissued_from_id pointing back at the predecessor. The original permit is unchanged.
The clone walks the full chain again (including a fresh walk-down) and mints a new number on its own Submit.

Note: High-risk types (HW / CSE / WAH / EXC / ELE) are not extendable — there is no "extend" on them. If the window's running out, you reissue (which re-runs the physical walk-down verification), you don't extend.

Note: An expired permit cannot be extended — extension only works on a still-issued permit. Once it's expired, your only path forward is reissue.

What you'll be notified about

As requestor (and usually receiver), you ride nearly every outcome on your permit — in-app and by email:

Event	You get
Permit issued / now live	Notification "Permit {number} is now live"
Permit rejected	Notification with the rejection reason in the body
Corrections requested	Notification "Permit {number} needs corrections" with the reviewer's note
Awaiting your countersign	permit_awaiting_countersign notification deep-linking you to sign (this is a notification, not a Task)
Extension approved / rejected	Notification of the outcome
Your live permit expired unclosed	A close_out_permit Task ("Close out expired permit {number}") lands for you and the receiver

You do not receive the review/approval gate Tasks (endorse/approve/issue) — those go to the coordinator, HSE, and appointed issuer.

Note: There is a known gap: clicking a permit notification does not currently open the Permits panel — it's informational only. Permit Tasks (like the close-out Task above) deep-link correctly; notifications don't yet. To act on a notification, open the Permits panel (P) yourself and find the permit.

Gotchas

Note: The Permits dock shortcut is P. The panel key is 'permits'. (Inside Add mode, A then P places a Point of Interest instead.)

Note: "Application" and "permit" are the same thing — the in-app permit is colloquially "the application" while it's pre-live, and the routes live under /permits/applications/..., but it's one Permit record throughout. There's no handoff to a separate object.

Note: Two different "permit" systems exist. This workflow is the first-class PTW apply flow. The legacy XLSX-import path (where a coordinator uploads a spreadsheet and you pick an imported permit to seed entity creation) is separate — imported permits arrive already issued and never had a draft you authored. Don't expect to edit an imported permit's approval chain; it doesn't have one.

Note: Only issued permits are selectable to seed entity creation. A draft or in-review permit can't be used that way yet.

Note: Clashes on your permit are advisory — they never block you submitting. (Red conflicts only force the approver to acknowledge them, not you.) The board's clash badge can appear a beat after the row loads, because clash counts are fetched separately and lazily.

Note: If you try to act on a permit that isn't yours or isn't visible to you, you'll get a 404, not a 403 — the system deliberately hides that the permit exists rather than telling you you're blocked.

Permits guide: Overview · Applying · Reviewing & approving · On-site signing · Configuring · Reference