Skip to main content

Admin Lesson 04 — Configuring SWMS

For: Admin only

Goal​

Define the global SWMS categories used across all sites, then upload PDFs per site so foremen can allocate them to workers.

Before you start​

  • You have your SWMS PDFs ready (max 20 MB each, application/pdf only).
  • You know what categories you want — examples: "Working at Heights", "Hot Works", "Confined Space", "Excavation", "Manual Handling".
  • For each PDF you know: the issuing company (your principal name like "Saiyu", or the subcontractor's company exactly as it's spelled in workers.company) and an optional scope description ("Eastern Scaffold, levels 3-7") if you'll have multiple SWMSs in the same category at the same site.

Steps​

1. Edit the global category catalogue​

Settings page with the SWMS tab selected Screenshot: Settings page at /settings/swms. Title "SWMS Configuration". List of 6 categories: Working at Heights, Hot Works, Confined Space, Excavation, Manual Handling, Electrical. Each with Edit and Delete buttons. "+ Add Category" button at the bottom.

  1. Click your avatar → Settings → SWMS tab.
  2. You see the global SWMS category list. These categories are shared across every site.
  3. Click + Add Category to create a new one. Provide a name and optional description.
  4. Click Edit on a row to rename. Click Delete to remove — be aware that deletion checks for existing documents and prevents the delete if any document references the category.

2. Move to a site's SWMS hub​

The per-site work — marking required categories, uploading PDFs, viewing coverage signals, exporting the evidence pack — happens at /swms/sites/[siteId], NOT in Settings.

  1. Click SWMS in the top nav.
  2. Click Manage SWMSs → on the target site.

3. Mark required categories (planning aid)​

Per-site SWMS hub with the required-categories checklist Screenshot: Top of /swms/sites/[siteId]. Required Categories panel with 6 checkboxes — Working at Heights (ticked), Hot Works (ticked), Confined Space (unticked), Excavation (ticked), Manual Handling (unticked), Electrical (unticked).

  1. Tick the categories you expect this site to need. This is purely a planning aid — it doesn't gate uploads or allocations.
  2. Below the document section, an Expected SWMS categories with no documents uploaded panel will list any required category without any uploaded PDF, so you don't forget to upload one.

4. Upload a SWMS PDF​

Upload SWMS dialog with category, title, company, scope, file, and notes fields Screenshot: Upload SWMS dialog. Category dropdown set to "Working at Heights", Title "Perimeter scaffold installation", Company input "Eastern Scaffold Co.", Scope input "Levels 3-7 perimeter scaffold", File input showing "scaffold-swms-v2.pdf" (1.4 MB), optional Notes textarea. Upload button at the bottom.

  1. Click Upload SWMS (admin-only button on each category section, or a top-level Upload button — depends on your UI version).
  2. Pick the Category from the dropdown.
  3. Enter the Title — a short human label for this specific document (e.g. "Perimeter scaffold installation"). Required.
  4. Enter the Company. Use the exact spelling of workers.company so the allocation modal puts the right workers in the top section.
  5. Optionally enter Notes — any extra context for foremen allocating this SWMS.
  6. (Optional) Enter a Scope description to distinguish this SWMS from another in the same category at the same site.
  7. Choose the PDF file. Max 20 MB.
  8. Click Upload. The new document appears in its category section with version 1 and Allocated count 0.

5. Watch coverage signals​

The amber Coverage signals panel at the top of the site hub flags concerning documents:

  • stale_outstanding — someone allocated >3 days ago hasn't acknowledged.
  • no_allocations — document exists, nobody allocated.
  • stale_doc — document hasn't been edited for 12+ months (might be out of date legally).

Each signal has an inline Allocate or Chase button that scrolls you to the relevant card.

6. Replace a SWMS version​

Replace SWMS dialog Screenshot: Replace SWMS dialog opened from an existing document's "Replace with new version" button. Shows current version "v1" and a "New version" upload slot, plus a "Change notes" textarea ("Updated edge protection requirements").

  1. On a document card, click Replace with new version.
  2. Upload the new PDF and add Change notes so the supersede notification can name what changed.
  3. Submit. The system:
    • Marks the old document as superseded.
    • Marks every existing allocation (pending AND already acknowledged) as superseded.
    • Creates fresh pending allocations on the new version for both cohorts.
    • Sends each affected worker a "SWMS Updated" email/SMS with a new 14-day sign token.

7. Export the evidence pack​

Evidence Pack Export card with date range Screenshot: Evidence Pack Export card at the bottom of /swms/sites/[siteId]. From-date input set to "2026-01-01", To-date input set to "2026-05-19", Download Evidence Pack button.

  1. Scroll to the Evidence Pack Export card at the bottom of the site SWMS page.
  2. Pick a date range — usually project start to project end, or incident-window if you're responding to an audit request.
  3. Click Download Evidence Pack. You get a ZIP containing:
    • Every relevant SWMS PDF (deduped — one copy per document/version).
    • Per-allocation signature PNGs.
    • manifest.csv listing every allocation event with worker name, induction number, SWMS title/version/company/scope, status, dates, and the channel they signed via.
  4. Save it somewhere durable (project share, audit folder). The download is generated on demand — there's no historical archive on the server side.

Done​

Your SWMS categories are defined, the site has the PDFs uploaded with companies and scopes, foremen can now allocate to workers via foreman lesson 04, and you have an evidence pack export path ready for audit.

Things to know​

  • Allocation IS scope declaration. Don't try to auto-allocate by company. Make the foreman tick deliberately — same-company workers aren't automatically in scope.
  • One signature covers a (worker, site) batch. A worker with 3 pending SWMSs at one site signs once for all 3.
  • No calendar expiry. Signatures last until the document is superseded. Editorial discipline (you reviewing + superseding) is the only re-sign trigger.
  • Site archive revokes pending allocations at the site (they become revoked). Acknowledged signatures are preserved as immutable audit history.
  • 30s CPU limit on Cloudflare Workers means a very large site evidence pack export might time out. If it does, narrow the date range or run per-category chunking (talk to a developer).

→ Next: Admin Lesson 05 — General settings and branding