Installing, copying and editing work permit templates

A work permit template is the permit’s structure: the gate questions, the blocks (boxes) and their rows, the rules, the headcount, the required documents and the layout of the boxes — it never holds filled-in values. Every permit type has its own template. The built-in set is built on four main types — general, hot work, confined space entry and ATEX (explosive atmosphere zone): hot work, confined-space entry and an Ex zone are main hazards, each issued on its own type. Next to the other built-in templates (electrical, excavation, crane, structural modification, ad-hoc worksheet, combined), the supplementary hazards (line breaking, electrical, excavation, structural, lifting, vehicle, height, simultaneous work) reach the templates from one shared built-in box set, as boxes opened by a question. An issued permit is bound to the template snapshot taken at issue, so changing the template does not change permits that have already been issued.

Before you start

Permission: managing templates and policy — ptw:manage. This right does NOT grant the right to issue.
Loosening without a reason: saving a setting looser than the OPEREX recommended value asks for a reason. Whoever holds the ptw:loosen_without_reason right (by default only the System administrator; it can be given to others in the permission matrix) saves without a reason — for setting up the company baseline. The loosening is still recorded: on the Permit settings → OPEREX standard tab’s deviation list, marked Accepted without a reason, by right (a reason can be added there later under Add a justification afterwards), and an audit record is kept of the save. Exception: enabling One-person issue (no requester) still asks for its own reason, even with this right — that reason goes into the chain and onto the paper of issued permits.
Where to find it: the Permit settings → Work permit templates tab.

The base templates come from the built-in set and carry a Base template badge in the list. The built-in content is a floor: on it you can only tighten. The header parameters, gate questions, blocks, rules and preparation tasks cannot be edited; the required-document list can be extended (you can add your own document or certificate and remove it again), but a built-in entry cannot be removed or changed, and neither can the built-in gas-test requirement. The name, your own form number, the layout of the boxes (width, new row) and the active state are yours to set. To shape a base template to your own needs, make a copy: the copy is freely editable, and a built-in refresh never touches it. (A base template that no longer holds the built-in content — because you rewrote it earlier, or because the built-in content has been updated since — is editable; a refresh, however, returns it to the built-in content, and then it becomes locked.)

Steps

The work permit templates tab: at the top the buttons to write the recommended required documents and to install and refresh the base templates; below it the table of templates with type (built-in base templates carry a Base template badge), key and version, your own form number, minimum headcount, maximum validity and the Active status column, with a ⋮ menu on each row. — The templates. Every row has a ⋮ menu: Edit · Blank form PDF · Required documents · Make a copy · Deactivate (or Activate). Built-in templates show their English names; your own templates keep the name you gave them.

Install the missing base templates. Install base permit templates creates the templates missing from the built-in set. It is idempotent: it does not overwrite existing templates or your own — if everything is there, nothing happens.
Look over the table. The Type column shows the name, the key, the version and the “… gate(s) · … block(s) · … rule(s)” counts. In the Own form number field you can type the document identifier that appears on the paper (it is saved automatically when you leave the field or press Enter). The Active column tells you whether the template can be chosen for a new permit.
Activate or deactivate. The row’s ⋮ menu has Deactivate / Activate. A deactivated template cannot be chosen for a new permit, but the permits issued with it remain.
Set the required documents. The ⋮ Required documents (…) item opens the compact editor under the row:
- Document · Applies to (Every worker · Work supervisor · Watcher · Entrant · Worker · At least N of them · The issuer) · At least this many people · Only with this marker → Add row;
- Required certificates — kind, marker, file required → Require certificate;
- Required gas test — the required gases, Validity of one measurement (minutes), An extension needs a new measurement → Save gas-test requirement (if you tick no gas at all, saving removes the requirement).
On a base template the built-in entries are marked “built-in” and their Remove button is disabled — hovering it tells you why. If the gas-test requirement is built-in, its fields are disabled too, with the reason above them.
Make a copy if you want to shape a base template to your own needs: ⋮ Make a copy. This is the only way to customise a base template’s content. If you then take the original out of the choice with ⋮ Deactivate, the risk assessment suggests the copy instead and starts the permit from it.
Open the editor. ⋮ Edit opens the Edit work permit template page. On a locked base template a window comes up first: “Factory template — not editable”. Make a copy and edit it makes a copy and opens the copy’s editor right away; Just view it stays on the built-in template. On a locked base template the content (questions, boxes, rules, parameters, and the JSON load) is shown disabled — only the name and the layout (box width, new row) can be set; the required-document list is extended in the compact editor of step 4.
Find your way with the “Template sections” bar. The jump bar under the header takes you to the parts of the page and shows where you are while scrolling: Layout · Questions · Boxes · Rules · Prerequisites · Parameters · Preparation · Advanced (JSON). The page is one document, with one save.
Arrange the boxes on the “Layout and preview” canvas. The canvas shows the permit as it will look when issued. At the top stand the page’s fixed parts (Basic data, Step 2 — Additional hazards, Risk sheet), marked “fixed — not editable” — the template does not arrange them, they are only shown. Below them come the template’s boxes:
- in the box header the width (Auto · ⅓ · ½ · ⅔ · 1 — one third, half, two thirds, full), ↵ (Starts a new row) and the ↑ / ↓ order;
- the question buttons of the Gate simulator only switch the preview: you see what appears for a given “yes” answer (All no resets it; hidden boxes are listed under “Hidden in this simulation:”);
- where a row leaves room, “Empty space · …” is shown; the Gap checker on the right runs through every gate combination, and clicking a combination sets the simulator to it. Automatic layout fixes the width of unset boxes so that no empty space remains without a gate or with one gate; Reset widths puts them back;
- clicking a box opens the Selected box panel on the right, with its Content, Visibility (Always shown, or the questions that open it), Rules and Layout in one place, and it states whether the box deviates from the OPEREX standard;
- if you delete a box or a question that a rule refers to, the page first lists the referring rules and the number of questions that open it — Delete together with the rules or Cancel decides.
Edit the parts (on a copy). Below the canvas the detailed list edits the same thing, in this order:
- the Template name (the Key cannot be changed) — at the top of the page;
- Gate questions: The question, Blocks it opens, the headcount tightening, the Header field it makes mandatory and the Marker (a “yes” makes it live) — the type marker comes with the question, and a “yes” answer makes it live (together with the prerequisites bound to that marker);
- Blocks and their rows: Label · Kind · Mandatory · N.A. allowed · Two-column responsibility · and the Meaning id (from the risk assessment template);
- Cross-field rules: IF this is the situation, THEN require this — and the Message shown when it is not met;
- Required documents, Certificates and gas testing;
- Header parameters: Valid for at most this many hours · Minimum head count · Minimum number of watchers · Production lead countersignature · Signature roles, the flags (Must be finished within one shift · Workers must acknowledge · May run overnight · Hand-back questions are required · Standing (recurring) permit allowed), the main hazards (The type’s own main hazard(s) — always live — and Further main hazards covered, which may come with a question; what neither lists, this type cannot issue) and Risk sheet sections on this type (none ticked = all);
- Preparation tasks (template);
- at the very bottom the Advanced (JSON) part (see below).
Insert a box from the library, if you need one. In the canvas header the + Box from the library… picker inserts a box of the shared box library (with its question, blocks, rules and prerequisites; “The “…” box is inserted — save to keep it.”). When you select a box that came from the library, the panel says so (“Library box: …”): Edit in the library (every template) takes you to the library box, and Detach makes it the template’s own part — from then on the library no longer overwrites it. No box can be inserted into a locked base template, nor into a template with errors (fix them first).
Save it. A slim save bar is always visible at the bottom of the page: the status on the left (“No changes to save.” · “Unsaved changes — valid, ready to save.” · or the error, e.g. a missing name), and Save template on the right, which saves a new version of the template. With errors, the bar’s “… error(s) to fix” link jumps to the list above it. Above the bar the page tells you: “Saving affects the NEXT permits.” If the change loosens the OPEREX standard, saving asks for a reason (“The change loosens the OPEREX standard — give a reason and the save continues with it.”).
Refresh the base templates when a new built-in version arrives. Refresh base permit templates asks for confirmation, then replaces the base templates’ blocks, gate questions and rules with the latest version (the required documents, headcounts and names are kept; copies are untouched). A base template that this returns to the built-in content becomes locked — the confirmation question says so.

The header of a locked built-in base template (hot work permit): the template name and key, the current version and the scope; below it the box that says what is locked and what can be extended, and the Make a copy and edit it button; at the bottom, how many items carry a reference to the risk assessment template. — The header of a locked base template: it says what is locked and how to customise it (Make a copy and edit it), and how many items carry a reference to the risk assessment template — these are the ones a risk assessment can pre-tick.

If it worked

After saving: “Saved. The new template version is v….” Installing and refreshing open a result window. Installing reports the number (“… base template(s) installed.” or “All base templates were already present — nothing changed.”), refreshing item by item: “… base template structure(s) refreshed; … already up to date; … own template(s) untouched.” If the refresh brought a new mandatory item, the window highlights that drafts created from then on need it filled in as well.

Both buttons switch back on a switched-off base template that none of your active templates stands in for (otherwise the risk assessment would find no active template for it). One that a template of your own stands in for stays off. The window shows all three lists: Base templates switched back on, Base templates left switched off (with the stand-in), and — if the risk-assessment template still prescribes a permit with no active template — Permit templates still missing, with a Manage missing templates button. If you don’t need a base template that was switched back on, switch it off again: if the risk assessment prescribes it, you will be asked for a replacement.

Common problems

What you see	Why	What to do
“The save DID NOT happen: this is a locked base template — its built-in content cannot be changed …”	You tried to save the built-in content of a base template.	Make a copy (Permit settings → Work permit templates → ⋮ → Make a copy) and edit that.
“Not saved: this is built-in content of a locked base template — a built-in entry cannot be removed or changed …”	You tried to remove a built-in required-document entry or change the built-in gas test.	You can add your own entries; deviating from a built-in one is only possible on a copy.
“The save DID NOT happen: somebody else changed this template in the meantime …”	Another edit was saved in the meantime. Your changes are still on the page, but were not written.	Open the template in another tab and re-apply your change by hand, or reload the page (that discards your edits).
“The template cannot be saved while these remain:” and a list with Where: … / Value: … lines	The structure is invalid — the list tells you, item by item, where and what the error is.	Fix it in the places listed, then save again.
Under a block: “It is not “always visible”, and no gate question opens it — so it would never appear on a permit.”	Nothing opens the block.	Mark it Always visible, or bind it to a gate question.
“No item carries a reference (ref) to the risk assessment template.”	On a permit started from a risk assessment nothing would be pre-ticked.	For a built-in template, run Refresh base permit templates; on your own template, add the Meaning id on the items.
“This template has no required-document list - the competence gate would stay silent even when switched on.”	The competence gate works from the template’s required-document list.	Add rows, or use the Write in the recommended list button.
“Install the competence types on the Person register page first.”	There is no document type yet.	Person register → Competence types → Install default types.

Worth knowing

The box library: at the bottom of the Permit settings → Work permit templates tab, the Box library table shows the shared boxes (Box · Carried by: … template(s); a built-in box has a factory badge). Edit opens the Edit a library box page: there the box is edited in one place, and Save box updates every template that carries it (“The box is saved: … template(s) updated.”); the width set in each template is kept. Locked factory templates are skipped (“… locked factory template(s) skipped (a copy or the factory refresh is needed there).”), and the page marks, template by template, which one is locked and which one differs. You can change a library box directly in a template too, but the next library save overwrites it — so either edit it in the library or detach it.
Why a base template is locked: the built-in content is the shared starting point that built-in refreshes maintain; if it could be rewritten in place, the next refresh would overwrite the change — and the “built-in” badge would stay on a template whose safety content had been taken out. So the built-in content is a floor: you can tighten it (your own entries), not loosen it. A copy separates the two: the built-in one can be refreshed, yours stays yours.
The key cannot be changed: the permits already issued carry it, and it decides whether a base template needs to be installed.
The Meaning id (ref) ties a template row to the vocabulary of the risk assessment template (hz.…, ppe.…, ctl.…). Where there is a ref, a risk assessment’s prescription appears as a tick; where there is none, as condition text. On built-in templates the refresh adds them; on your own template you add them by hand.
Write in the recommended list only fills base templates whose required-document list is empty — it is meant for templates installed earlier.
A template bound to a site can only be chosen on that site — the editor’s header states the scope.
Editing with JSON (Advanced): the template definition can be copied out (for example to another site) or pasted in; pasting only loads the draft, and saving goes through the usual button.
A template is one layer of the process: next to the risk catalogue and the policy it shapes the permit, while the fixed core (the signature chain, the two-sided hand-back) is the same for every template. Overview: Permit to work — the process.

The risk assessment templateThe questions, the vocabulary and the rules — where the refs point.

Rolling out the risk assessmentWhy the base templates need a refresh before switching it on.

Person register and documentsThe document types the required-document list refers to.

Policy gatesWhen the required-document, certificate and gas-test gates speak.