Administration – Functional Specification v2 (the full module)

• Section subtitle is meta: the descriptive line under each section title (with its decision IDs) is tagged as an annotation, so the wireframe's "Spec refs & annotations" toggle hides it – the working UI shows just the title (item 1).
• One table-header grammar everywhere (item 2): a section's actions live in the card header, hard right – the primary create action in dark, any secondary action and the icon-only Columns control to its left. Applied by hand to Users / Roles / Teams and by a load-time pass that lifts the remaining sections' create actions out of their footers.
• The actions column is never removable (item 2, Ivan 15 Jul): the row-action column is excluded from the shared Columns show/hide menu on every table in the platform – it carries no data, and hiding it would strand the row controls. Implemented in table-tools.js (skip a header that is data-nosort or has no visible label).
• Every create button opens a real popup (item 3): "New / Add / Upload …" actions open a titled, entity-appropriate form (bespoke for Users, Roles, Teams; a shared configurable Admin create/edit popup for the rest) – no action dead-ends in a toast.

Administration is one left-nav section with four groups of sub-pages. Every page is admin-only and every change is audited (§7). One page shows at a time; the heading and description follow the selection, exactly as in v1.

Pages carried over from v1 unchanged in behaviour: Manage employees, Shift patterns, Responder pairing, Manufacturers & products, Store management, Quarantine management, Keyword management, Referral sources, Job durations, Task-type colours, Bottom-ribbon messages, Platform settings, Security & permissions. Their v1 specs still apply; v2 only re-homes them into the grouped nav and links them to the new pages (e.g. Job durations ← Task types).

The current Service Manager splits configuration across Administration, System Administration and the separate Identity apps (user & client management). The table maps every old area to its v2 home – nothing is silently dropped.

3.1 Users & sign-in G-011 · G-013 · R-006 · A-002

• One list of people. Grid: name, email, role, user groups, sign-in method, MFA, last sign-in, status (Active / On leave / Disabled-leaver). Users created directly in the ARC appear here too – SM holds the richer profile (R-006).
• Invite flow. Admin invites by email + role (+ groups); the user completes SSO/MFA enrolment at first sign-in. No admin-set passwords.
• Sign-in policy. SSO (Entra ID) enforced for staff; MFA required for non-SSO accounts (field app). Session timeout configurable; auto-save on timeout / leaving a page per G-011.
• Disable / leaver CHANGED: done from the user's Edit screen, not a separate table button – the account-status dropdown there (Active / On leave / Disabled / Disabled-leaver) is the single place status changes. Disabling removes access immediately and starts the leaver-retention clock (G-013, default 12 months, configured on Security & permissions); after it, the person is redacted via Data redaction. History stays until then. Users are never deleted.
• Layout CHANGED: Invite user is the table's primary dark header action; the Sign-in policy button sits at the page title (it is a page setting, not a table action) and opens the policy as a popup. A filter row offers search (name/email), status, team and role; each row has an Edit action.
• Invite is a 2-step flow CHANGED: step 1 chooses the sign-in method. For SSO, step 2 is a single directory autosuggest (type a name or email – the person already exists at the identity provider, so name and email come from there, not typed). For a password + MFA account, step 2 collects full name, email and role. In both, user groups are chosen from suggestions as removable chips – never free-typed.
• MFA is read-only on Edit CHANGED: the edit popup shows whether MFA is enabled but does not let it be changed – MFA is enrolled by the user, not set by an admin. The MFA dropdown was removed.
• Employment details that the scheduler needs (home base, custom schedule, sex, reschedule rights) stay on Manage employees – the two pages link both ways per person.

3.2 Roles & permissions G-009 · Q-005 · A-003

• Role = category + permission row. Categories are the fixed G-009 set (Responder / Administrative / Engineering). Default roles: Administrator, Supervisor, Dispatcher, Coordinator, Assessor, Team leader, Responder, Installer, Stock controller; admins can add more.
• Matrix levels per module CHANGED: Admin (configure) · Edit · Edit assigned (records assigned to them – the field-app level, previously labelled "Edit own") · Edit own NEW (records the user created themselves – item 5.4, for self-serve coordinators who must not touch other people's records) · View · – (hidden). Module-specific values (Own van, Edit stock tasks) are documented in a "What do the levels mean?" reference popup opened from the section and the role editor.
• Editing CHANGED: New role is a primary dark action in the table header (with the Columns control) opening a popup – name, category, and a per-module level dropdown for each of the seven modules; every row has an Edit action opening the same popup pre-filled.
• Task-type filter. Each task type maps to exactly one role (Q-005); assignee pickers therefore show only people whose role matches, on shift. Ghost persons are impossible by construction.
• Roster view/edit and password policy deliberately stay on Security & permissions (v1 behaviour) – the matrix links there rather than duplicating.

3.3 Teams G-009 · Q-005 · D-001

• Team: name, category (fixed list), home base, members; unlimited sub-teams (kept from the old SM – schemes and departments use it). Teams of category Responder feed the dashboard's "On-shift responders" (D-001). CHANGED: New team (primary, dark, header, hard right) and Add sub-team (secondary) open real popups; a sub-team inherits the parent's category. Each row has an Edit action.
• Groups drive pickers. A person can belong to several teams; when they are made responsible for work, the user chooses (and the system stores) which group applies (Q-005).
• Membership editing is drag-between-columns (available ⇄ in group), as in the old Workgroups – familiar and quick.
• Archiving a team hides it from pickers but keeps history; deletion only when never referenced.
• CHANGED The section is titled simply Teams (Ivan, 15 Jul 2026); the explanatory "How groups reach the rest of the app" panel was removed from the page – it documented the assignment chain (task type → role → on-shift picker; Responder-category teams into the dashboard's on-shift count), which belongs in this spec, not as on-screen chrome.

3.4 Carried from v1 unchanged

Manage employees (custom schedules up to 4-week rotations, home base, sex for C-012 restricted visits, reschedule rights) · Shift patterns (+ break allowance per role) · Responder pairing (bind/unbind, overlap release, audited). See file 17 / the v2 wireframes for full behaviour.

CHANGED (Ivan, 15 Jul 2026): Manage employees gains a filter row – search name, role, level, gender, team, and custom-schedule (has / none) – since not every employee carries a custom schedule. Responder pairing row actions (Edit / Unbind) are now icon-only, consistent with the platform's row-action convention.

4.1 Task types Q-005 · C-005 · S-005

• Catalogue of every task the system can schedule. Fields: name, class (General / Request / Agreement), role (Q-005), default duration (from Job durations for sized field jobs, or a fixed value), colour (from Task-type colours), linked form (optional – presented for completion when the task completes), recurrence (Agreement class only, e.g. assessment reviews).
• Request-class types also declare which request types they may appear in; Agreement-class types drive recurring work (welfare calls, reviews) and the next-review RAG in Reports.
• In use → archive only (history keeps it); never used → delete allowed. Same rule as the old SM, kept everywhere in v2.
• CHANGED (Ivan, 15 Jul 2026): the row Edit opens a popup (was a toast). The editor is class-dependent – Request adds a reactivation-installation flag and a referral form; Service Agreement adds a review recurrence. It carries the SLA times the task type owns: per priority (Normal / Urgent only), an accept / on-site / complete target in working hours – modelled on the old SM's Incident Type SLAs (accept/arrival/completed). The list shows the Normal/Urgent completion SLA in a column, and that is what the SLA overview page summarises.

4.2 Request task sets Q-001 · Q-002 · Q-003 · Q-004 · G-010

• The four request types are fixed (Q-001): Installation, Equipment change (only after an installation completes), Decommission, Custom task.
• CHANGED Renamed Request task sets. The page shows one request type at a time (chosen from the selector), not all sets at once. Per type – and per client (G-010) – an ordered default task set, each row with a role and an SLA offset in working hours from acceptance (was working days; the numbers are unchanged, the unit is hours). Wireframes show the agreed shapes, including pick stock first with the auto-raised van transfer (Q-004) and the S-005 decommission chain ending in "archive data & remove from ARC".
• NEW Add / Edit a default task opens a popup carrying every table field: task name, role (dropdown), and an SLA target entered as digits with a fixed "working hours" suffix. The request type is not selectable – it is fixed to the set being edited and shown for context.
• On a live request: non-applicable defaults can be marked complete immediately, custom tasks can be added (Q-003); completing the last task prompts to close the request (Q-002).
• Editing a set affects future requests only.

4.3 SLA overview Q-006 · X-001

• CHANGED (Ivan, 15 Jul 2026): the old "SLA matrix" was wrong – it put the SLA on the request with four priorities. SLA lives on the task type (§4.1), and the platform has only Normal / Urgent priorities. This page is now a read-only overview: task type × {Normal, Urgent} completion target, in working hours; each row links to the task type to edit.
• A request's "next action" window is derived from its tasks' targets – never user-picked (Q-006); the UI shows the latest date.
• The amber warning threshold (default 75% elapsed) stays here as a global read; the resulting approach/breach notifications are configured in §6.3 (X-001).

4.4 Forms & assessment templates R-007 · A-005

• Three template types: Assessment (appears in the Assessment Editor and the field app), Referral (drives referral creation and the public survey, R-007), Task (attached to task types, presented on completion).
• Lifecycle (kept from the old SM – it works): draft → publish (locks) → revise (new draft version) → archive. Instances permanently keep the revision they were created with; archived templates stay referenced. Drafts can be deleted; published never.
• Builder: sections (custom, or pre-defined: Service User Details, Address, Contacts, Services, Keywords, Dwelling) → questions (text / dropdown / checkbox / date / number; required flag; comment box) → reusable answer sets. Sections and questions clone from existing templates. Referral forms must contain Service User Details + Address; surname, organisation, referral date and priority are mandatory.
• Assessment templates carry a review cadence feeding the next-review RAG report.

4.5 Carried from v1 unchanged

Job durations (job type × S/M/L/XL minutes, C-005/C-006 – now referenced by Task types) · Task-type colours (optional custom palette; platform defaults when off).

5.1 Organisations & funders R-004 · S-021 · X-004

• One register with usage flags: Referrer · Funder/payee · Stock owner · Site (schemes). Details: reference/account numbers, phones, email, contract dates, address; contacts; (sub-)teams for finer reporting.
• The system “External” organisation receives public referrals (R-004) and cannot be edited or archived.
• Funder + account ref is the key the finance export uses to bill service level/cost per agreement (S-021, X-004 – seam in §6.4).
• In use → archive only; never referenced → delete. Archived orgs can be reinstated.

5.2 Service types S-021 · P-006

• Service-type list with default cost, billing cycle (weekly / monthly / one-off) and allowed payees. Services attach to agreements with start/end dates; an end date auto-cancels the service, and agreements expiring within 7 days surface as a standing view (S-021).
• Characteristics (responder service, private pay, scheduled calls…) are kept as filterable flags – they are precisely the filters of the Service-agreements report (P-006).

5.3 Reasons & lookups S-004 · Q-006 · Q-008 · A-006

• Grouped lists: termination reasons, request cancellation / hold / resolutions, referral rejection / hold / cancellation, stock return reasons, stock transfer reasons, roster absence types. Each value: add, rename, retire.
• Gone: suspension reasons (S-004 – suspend/resume removed) and request causes (Q-006 – “we already know”).
• Changed from the old SM: there, editing a reason silently rewrote every historical record. In v2 a rename creates a new value and retires the old – history keeps the wording it was recorded with (A-006).

5.4 Reference library Q-017 NEW

• Admin-curated documents (guides, quick sheets, policies, scripts) with type and “suggest on” tags – request types and/or products.
• The request Links panel searches this library and pre-suggests matches from the request type and affected equipment (Q-017), alongside free URLs (Q-009).

5.5 Carried from v1 unchanged

Manufacturers & products (barcode mapping profiles I-002, RMA warranty rules, product definitions I-001, versions, kits) · Store management and Quarantine management (v1 pages, unchanged) · Keyword management (fixed vocabulary, colours, ARC palette sync, C-012 sex-restriction keywords, G-008 colour question still open) · Referral sources (list + colours).

6.1 Carried from v1 unchanged

Bottom-ribbon messages (timed, hideable notices) · Platform settings (distance unit & time format G-012, uncompleted-task release, stock-transfer receipting default I-004, handover escalation hours) · Security & permissions (password policy, roster view/edit, leaver retention G-013). New in v2: Platform settings also hosts the task-generation horizon (how far ahead Agreement-class recurring tasks materialise; old-SM default 21 days) – migrated from Group Characteristics.

6.2 Notifications & SLA watch X-001 · P-007 · S-021 NEW

• Rule grid: event × channel (in-app / push to field app / email) × audience. Shipped events: SLA amber, SLA breach, unassigned-approaching-breach (the “SLA watch” line in Messages), handover overdue, stock below reorder (P-007), agreement expiring (S-021).
• Global toggle for incomplete-step prompts before proceeding (X-001).
• Audiences are roles/groups, resolved at send time via §3 – no named individuals in rules.

6.3 Integrations X-004 · R-006 · S-005 NEW

• Status page of every external seam: ARC/PNC (user sync R-006, palette push, decommission removal S-005 – connected), Teams/365 roster sync (connected), DMP (SIM suspend on scrap/loss – planned), finance export (planned), Power BI / raw data (TBD), Zoom Contact Center click-to-call (seam from Mark’s design – schedule & outcome records already shaped for it), Mosaic / Liquid Logic / CM2000 (TBD).
• Each entry: what it does, status chip, configure/details. The point is honesty in the UI – features that depend on a seam say so, and land without rework when it connects.

6.4 Data redaction S-003 · G-013 NEW in admin UI

• Queue + search (person, or “terminated within N months”). Eligibility: terminated agreement, nothing open or pending; contacts redacted separately; staff leavers auto-queue when their retention ends (G-013).
• Nightly service at 06:00 processes the queue. Redaction is permanent: names removed from history, anonymised aggregates remain (S-003).
• Redacting in SM does not redact the ARC/PNC – the entry stays flagged until the ARC-side step is confirmed (kept from the old SM, made visible instead of a manual-only warning).

• Everything on these pages is audited: who, what, when, before → after. The Admin audit log page gives a filtered read-only view; the cross-module Audit report lives in Reports (P-008).
• Archive over delete, uniformly: anything ever referenced can only be archived (hidden from pickers, kept on history) and reinstated; deletion only for never-used records, with confirmation.
• Per-client config (G-010): default task sets and the SLA matrix carry a client selector with a platform-default fallback; everything else is single-client.
• Prospective changes: config edits affect future records (new requests, new services); open work keeps the rules it started with. The two exceptions are colours/labels (cosmetic, apply everywhere at once) – and that is exactly why reasons are versioned rather than renamed in place.

New entries proposed by this spec – to be reviewed and, if agreed, added to the Decisions Register as A-001…A-010. Until then they are proposals, not decisions.

• Mark’s Admin contents. His build has an Admin nav section, but no capture shows it expanded – if screenshots exist, reconcile against this spec.
• Print definitions (A-009): configurable sections vs one fixed, well-designed layout for the S-020 PDF?
• API clients: where do integration credentials live – a panel under Integrations, or outside the product entirely?
• Keyword colours (G-008): full colour set vs the 3 ILOS colours is still TBD – affects the Keywords page and the ARC palette sync.
• Default role permissions: the matrix rows in the wireframe are a starting point; the levels per role need a review round with the client.
• Per-client scope: is the client selector needed anywhere beyond task sets and the SLA matrix (e.g. reasons, service costs)?
• Notification audiences: confirm the shipped rule set and whether users may mute individual rule types per person.