SSL Service Manager – Referrals Specification

Scope & structural change wireframe ↗

Referrals is where prospective service users enter the system before they hold a service agreement. In the old SM this was Intake (ILOS) / the Add Referral + Referrals screens (OSM); the SSL Service Manager keeps it as a top-level section (G-004) and folds in the related decisions:

Old SM	SSL Service Manager	Ref
Intake (ILOS) / Add Referral + Referrals (OSM) – templated referral forms and a referrals list	Referrals – one section: a referral console, template-driven New referral, referral detail with a validate → convert lifecycle.	R-001, G-004
Default referral forms (NSM + old form) with a "Picked Stock" block	Default forms combine NSM + old form with "pick stock" removed – stock is handled later, in Requests / Inventory.	R-001
Quick Agreement – combined a referral + a risk assessment in one step (e.g. hospital discharge), bypassing stock management	Removed. No longer needed – becomes a simpler referral form; the Connect risk assessment is completed at conversion.	G-006
Address/phone match handled in the agreement actions ("add a new user to an existing agreement")	Moved to the referral page – duplicate detection runs at referral creation (R-005), offering to add the prospect to the matched agreement (S-007).	R-005, S-007

"Referrals – NSM 'Intake'. New template (our surveys); links are saved in the system. … External links to surveys should be available, so they can be filled in by third parties (publish these as a public page with an obscure url). The requester will need to provide their name (this needs to be compulsory). … Provide default forms (combine NSM with OLD – remove 'pick stock' from the old form)." – consolidated notes, M2 (R-001, R-002).

Design principle. A referral is a pre-agreement record. It can be created internally (typed in from a phone call) or submitted externally through a published survey; it is then validated, and either converted into a service agreement (creating a service-user profile, file 03) or rejected with a recorded reason. Everything the operator needs to triage, chase and convert lives on this one console.

1 · Referrals console wireframe ↗

The landing view is a cross-client list of referrals with working status filters, search and per-row quick actions – the same engine pattern as the Requests console (file 14), for consistency.

Status filters & scope NEW

Five count tiles at the top are the status filter – clicking a tile (New · In review · On hold · Accepted · Closed) filters the list and highlights the active tile; clicking it again clears. Counts are computed live. The Closed tile combines Converted and Rejected and shows the split in its sub-label – the two outcomes that drive the Referral report (P-004). A separate All referrals / My referrals scope toggle limits to referrals the signed-in user created or handles.

Columns

Column	Notes	Ref
Referral	Prospect name above the referral ID (REF-yyyy-nnnn) – never an ID alone.	R-001
Source	Default · GP · Hospital discharge · Social Services · Self-referral · Public / external – the referral type / template.	R-007
Address	Used for duplicate detection against existing agreements.	R-005
Referred on	Referral date, plus days open – RAG-aged (amber ≥ 7 days, red ≥ 14) so stale referrals surface. The old SM tracked "Number Of Days" in each state.	Notes M2
Status	Fixed pill tokens (shell doc): New = blue, In review = amber, On hold = purple, Accepted = teal, Converted = green, Rejected = grey.	Q-008
Linked	A link icon when the referral matched an existing agreement at the same address/phone – the old SM "Has Linked" column.	R-005
Actions	Per-row quick actions by lifecycle state – validate (new/review), convert (accepted), assign, reject – without first opening the referral.	Q-005

The list paginates at 25 rows per page with explicit page controls, mirroring the old SM advanced-search results. The inline controls sit on one row: the scope toggle, a text filter that highlights matching characters, and a Source dropdown. The old SM "Advanced Search" (Status / Priority / On Hold Reason / Name / Address / Telephone / Customer Reference) is covered by the header global search plus these inline filters. The referral itself carries no Priority field (dropped vs the old SM – see §9 / OQ-RF9); urgency reads from the Source and the days-open aging.

2 · Templates & public surveys wireframe ↗

Referral templates are surveys. Each can be published to a public page with an obscure URL so third parties (GPs, hospital discharge teams, the public) can fill it in; the requester's name is compulsory. Links are saved in the system, and electronic requests can also be imported from websites, email and MS Forms.

Behaviour	Detail	Ref
Default forms CHANGED	Combine the NSM form with the old SM form; the old form's "pick stock" block is removed.	R-001
Public surveys NEW	Published to an obscure URL; fillable by third parties; requester name compulsory; submissions land as new referrals.	R-002
Referral sources NEW	Different referral types – Public, GP, Hospital discharge, Social Services – and electronic import from web / email / MS Forms.	R-007
External organisation	Organisation = the logged-in user's organisation; an "External" organisation exists for public referrals. (Greg Mason to provide sample referrals.)	R-004
Create / edit a template NEW	The Templates page has a working New template popup (name, source, base field set, additional fields, publish toggle → generated public link) and a working Edit action on each row that opens the same popup pre-filled. Defect fixed: the row pencil previously opened the New referral popup instead of editing the template, so templates could not be edited at all. The row now carries three distinct actions – Copy link, Edit template (pencil) and Use template (opens a new referral on it).	R-002, R-001

Configuration vs. use. The deep configuration of templates (field library, referral causes, rejection reasons, source list) remains an Administration responsibility; this page is where the intake team creates, edits, publishes and uses them day to day. The two views act on the same objects.

3 · Creating a referral wireframe ↗

The operator first picks a template (the old SM "Choose a template for the new Referral"), then completes a two-step form – Prospect & address → Source & details – keeping the dynamic, template-driven field model.

Field model

Group	Fields / behaviour	Ref
Template	Default · GP · Hospital discharge · Social Services · Public self-referral – the form adapts (e.g. GP adds practice / NHS number; hospital adds ward / discharge date).	R-002, R-007
Prospect (service user) details CHANGED	Title, Forename, Surname, Known as, DOB, Customer reference, phone numbers, Self-referral flag – from the old Add Referral form. Mandatory: Title/salutation, Surname, and at least one contact telephone number. A referral nobody can ring is not actionable, and the salutation is needed for every letter and call script. Phone numbers are a repeatable list (as on the service-user edit popup), not two fixed fields.	R-009
Blank on open CHANGED	The form opens completely blank – no example or pre-filled data of any kind. (The wireframe previously seeded it with the Margaret Carter sample, which made every new referral start as somebody else.) The template dropdown is reset to "Default referral" and the form to step 1 every time New referral is pressed, so a template picked earlier from the Templates page never carries over into an unrelated referral.	R-009
Other prospects	"Add another prospect" – dual-occupancy households share an address / equipment.	S-007
Address + duplicate detection NEW	As address/phone are entered, the system searches existing agreements at the same address and, on a match, asks whether to add the prospect to the existing agreement or continue as new. (Moved here from the agreement actions.)	R-005
Referral source NEW	A referral keyed in here defaults to "No referral – created in the system": staff raised it, nobody referred it, and there is nothing further to record. A source can be selected instead (GP referral, Hospital discharge, Social Services, Self-referral, Public / external) – the case where the referrer phoned in because the survey link was not available to them. Selecting a source reveals the Referred by block and makes the referrer's name mandatory. Choosing a source also switches the form to that source's template.	R-009, R-007
Referrer details	Job title, name, phone, email; "Use my details" pre-fills from the logged-in user. Name is compulsory on public surveys, and whenever a source is selected on a manual referral.	R-002
Attachments NEW	Multiple files can be attached to a referral – discharge summaries, GP letters, care-package documents, photos of the property or keysafe. Accepted types are restricted to Word (.doc, .docx), PDF and image files, up to 20 MB each; anything else is refused with a message naming the file. Files can be chosen or dropped onto the form, are listed with type icon and size, and can be removed before saving. Attachments can also be added later from the referral detail, are carried onto the service agreement on conversion, and appear in the audit trail (who attached what, when).	R-009
Organisation / source	The logged-in user's organisation, or "External" for public referrals; the old funder/source list (F-/R- Professional Services, Social Services, R- Family & Friends, F- Client or Family, S- Own Stock).	R-004
Other referral details	Referral date, Referral cause (standard category). The old "Installation Tasks" and "Picked Stock" blocks are removed from the form.	R-001

Removed by decision. No "pick stock" on the referral form (R-001); no combined risk assessment – the Quick Agreement is gone (G-006). The Connect assessment is completed at conversion (S-016).

4 · Referral detail & lifecycle wireframe ↗

The detail view manages a single referral and its progress through the lifecycle pipeline.

Lifecycle

A referral moves Received (New) → In review → Accepted (validated) → Converted, or is Rejected, or held On hold. This generalises the old SM's "Awaiting Validation → Validated" states and adds the explicit outcomes the Referral report needs.

State	Meaning	Ref
New	Received, awaiting triage (internal entry or external survey submission).	Notes M2
In review	Being validated / triaged (old SM "Awaiting Validation").	Notes M2
On hold	Awaiting information / funder authorisation – records an On hold reason (old SM "On Hold Reason"), who placed it and a review date; surfaced by the On hold filter.	Notes M2
Accepted	Validated and ready to convert (old SM "Validated").	Notes M2
Converted	Became a service agreement / service user – terminal success (feeds P-004).	P-004
Rejected	Not processed, with a recorded reason – terminal (feeds P-004).	P-004

Detail content

Duplicate-match alert – when the referral matched an active agreement, an inline panel offers "Add to existing agreement" or "Not the same household". R-005
Deactivated-agreement indicator NEW – the same address search also surfaces agreements at this address that were deactivated, in the same alert grammar as the possible-match but in amber. It names the previous service user, the deactivation date and reason, and links straight through to the deactivated agreement (which opens read-only, S-008). This matters twice over: equipment may still be in the property from the previous service, and the history is relevant to the new assessment. Dismissible; dismissing keeps it in the address history rather than deleting it. R-005, S-008
Attachments NEW – the files that came with the referral (Word / PDF / image), addable at any time until conversion, carried onto the agreement on conversion. R-009
Prospect details, Other prospects (dual occupancy), Address (tel:/maps links). No client photo – captured at conversion against the monitored organisation's logo. S-002
Risk assessment – not on the referral form; the Connect assessment begins at conversion. G-006, S-016
Referral history – state changes with date, days-in-state and who changed it (the old SM "Referral History" view, brought onto the detail).
Details – Source, Organisation, Referrer (+phone/email), Referral date, Referral cause, Handler. Editable until an agreement exists (§7). R-003
Survey link – copy the public link / send a personalised edit link (§7). R-002
Actions – Validate, Convert, Put on hold, Assign handler, Reject.

5 · Conversion to a service agreement wireframe ↗

Converting an accepted referral creates the service-user profile (file 03) and ends the referral. Where duplicate detection found a match, the operator chooses between two routes:

Route	Detail	Ref
Add to existing agreement	The prospect joins the matched agreement (same household / shared equipment) – no fresh agreement number. The agreement is already valid, so no re-validation is needed.	R-005, S-007
Create a new service agreement	A fresh agreement with its own number, scope and funder.	S-007

On conversion: scope and funder are set; a Connect risk assessment is then required before any installation request can complete; and further edits to the person's details move to the Friends & Family app (the referral is no longer the place to edit).

"Send a personalised url of the survey to the person who is filling it in; they should be able to go back and edit the details as long as there is no formal service agreement in the system; at that point details can only be edited via the 'friend and family' app." – consolidated notes, M2 (R-003, X-003).

6 · Rejection & the Referral report wireframe ↗

Rejecting a referral closes it and requires a mandatory standard reason (from the admin-defined category list) so the system "knows" why it was not processed. This is what powers the new Referral report: how many referrals were received, how many converted to service users, and how many were not processed and why.

Rule	Detail	Ref
Mandatory reason	Standard category (e.g. no responder coverage, duplicate, ineligible, declined, insufficient information, gone into care, deceased) – not free text.	P-004
Coverage signal	Repeated "no responder coverage in area" rejections flag where new responders may be needed – a reporting need raised in M5.	Notes M5
Audit	Recorded with name, timestamp and reason.	S-014

Report split. The old Cancellation Reasons report is removed and split into a Referral report (received / converted / rejected with reasons) and a Request report (cancelled requests). Both live in the Reports module.

7 · Editing & survey links wireframe ↗

A referral is editable while it is still a referral. A personalised survey URL can be sent to the person who filled it in; they can return and edit their submission until a formal service agreement exists. After conversion, the personalised link stops working and the person's details are managed in the Friends & Family app.

Public link – the obscure survey URL, copyable and saved in the system. R-002
Personalised edit link – sent to a named requester (name required); lets them edit until an agreement exists. R-003
Edit referral – operator edits (source, cause, handler) are audited; locked to the Friends & Family app post-conversion. R-003, X-003
Read-only once converted CHANGED – conversion freezes the referral. The Edit button is removed (replaced by a "Read-only" chip and a banner), the Actions card is removed entirely (nothing in it can be done to a converted referral, so an empty card would be pure noise), no further attachments can be added, and the lock is released. The referral is now a historical record of what was received; the live data lives on the service agreement, and contact details are self-managed in Friends & Family. This closes the gap where a converted referral could still be edited out of step with the agreement it created. R-009, R-003

8 · Locking, assignment & unlock wireframe ↗

Opening a referral locks it to that user and moves it to In review, so two people never triage the same case. The lock is the reason reassignment was originally dropped – but a lock without an escape route strands work, so the model is now completed with three explicit routes out.

Behaviour	Detail	Ref
Lock on open	The referral is locked to the person who opened it; the list shows a padlock and tints the row. The lock releases when they leave the referral.	R-008
Who holds it CHANGED	In the list the padlock is information only – hovering it shows the platform's styled tooltip (the navy tooltip card used everywhere else, not the browser's default title bubble) naming the holder, when they took the lock and their team. It is keyboard-focusable, so the tooltip is reachable without a mouse. There is no unlock action in the list: unlocking is a considered decision and is taken on the referral itself, where the full context is in view.	R-008
Lock panel on the referral NEW	The referral carries a Lock panel reading "Locked by K. Jackson since 17 Jun 2026, 08:52 (2 hours ago)" on one line – holder and duration are read together, not as two separate facts – with the team beneath. How long a referral has sat on someone's desk is the question that decides whether to force it open. The Unlock referral button sits here, at the same size as the other referral actions.	R-008
Assign to another person / team NEW	Restored. Reassignment was removed earlier as unnecessary once referrals locked on open; in practice a referral still has to move when the handler is off, overloaded, or it belongs to another team. The lock-on-open behaviour is unchanged – the lock simply follows the assignment: assigning to a person transfers the lock to them; assigning to the team queue releases it, and whoever opens it next takes it. Group is chosen first, then the person within it (Q-005). Audited. The popup carries no explanatory note and no free-text field – it asks for the group and the person, and nothing else.	R-008, Q-005
Privileged unlock NEW	Users holding the Unlock referrals privilege (Administration → Security & permissions) can force-release a lock: from the referral itself, or inline from the list. Per the standing rule for irreversible actions this is never one click – a confirmation popup states that the holder's unsaved changes will be lost, a reason is mandatory (off sick / on leave / left the organisation / left open in error / urgent), and the action is audited. The unlocker can optionally take the referral in the same step; otherwise it returns to the team queue.	R-008
Roster integration NEW	Tasks are not the only thing stranded when someone goes off. Marking a person sick or on holiday on the roster now surfaces the referrals locked to them in the same reassign workflow, alongside their booked tasks – each can be reassigned (lock transfers), released to the team queue (unlocked), or deliberately left locked. The workflow now opens even when the person has no booked tasks but does hold locked referrals, which previously slipped through entirely.	R-008, C-002

Why the lock alone was not enough. The lock solves double-triage, but it creates a single point of failure: a referral opened at 16:55 by someone who then calls in sick is invisible work that nobody can touch. Reassignment and the privileged unlock are the two ways out, and the roster is where the need is actually noticed – hence surfacing locked referrals there rather than waiting for someone to chase the referral.

9 · Dependencies & out of scope wireframe ↗

Area	Owned by	Why
Template / survey configuration, sources, referral causes, rejection & on-hold reason categories	Administration	All configured per client (R-001, R-002, R-007); this module consumes them. Until Administration is built, lists are illustrative.
Service-user profile, agreement record, the actual conversion target	Service User Profile (02/03)	Conversion creates the profile; "add to existing agreement" lands there (S-007).
Connect risk assessment	Assessments (profile)	Completed at conversion; a request cannot complete until its assessment is published (S-016).
Installation request raised from a converted referral	Requests	Installations normally originate from a referral; the request is raised after conversion (Q-001).
Post-agreement self-service edits	Friends & Family app	After an agreement exists, contacts self-manage data (R-003, X-003).
Referral report (received / converted / rejected with reasons)	Reports	This module is operational intake; trend reporting lives in Reports (P-004).

10 · Coverage – old Referrals / Intake / Quick Agreement

Disposition of the old SM intake surfaces against this module (screenshot group 4 Referrals + the Quick Agreement screens). Counts to be reconciled against the catalogued screenshot set (OQ-RF8).

Old SM element	Disposition	Where
Add Referral – "Choose a template" + form	SPECCED + WIREFRAMED as the template chooser + two-step New referral	§3
Referrals list + Advanced Search (Status / Priority / On Hold Reason / Name / Address / Telephone / Customer Reference)	SPECCED + WIREFRAMED as the console with count-tile filters + scope + search + source; advanced fields via the header search	§1
Referral History view (current state, days, state changes)	SPECCED + WIREFRAMED as the Referral history card on the detail	§4
"Has Linked" column	RECAST as the Linked column + duplicate-match flow	§1, R-005
"Picked Stock" block on the form	REMOVED from the referral form	§3, R-001
"Installation Tasks" multi-select on the form	REMOVED here – default task sets belong to the Request raised after conversion	§3, Q-003
Quick Agreement (referral + risk assessment in one step)	REMOVED – simpler referral form; assessment at conversion	§3, G-006
Self Referral flag · Other Service Users · Referrer Details · Organisation list · Referral Cause · On Hold Reason	KEPT (provenance to confirm – OQ-RF7)	§3, §4
Priority (Normal / Urgent) on the referral	REMOVED – a referral is a pre-agreement enquiry with no SLA; urgency is carried by Source (e.g. Hospital discharge) and the days-open aging. Confirm with Tunstall (OQ-RF9).	§1, R-001
Users created directly in the ARC	DEPENDENCY – must be visible in the SM; SM holds richer data (R-006)	§8, R-006

Open questions for Tunstall

ID	Question	Ref
OQ-RF1	Confirm the referral source / template list (Default, GP, Hospital discharge, Social Services, Self, Public) and which are published publicly. Greg Mason's sample referrals would let us finalise the per-template field sets.	§2, R-002/R-004/R-007
OQ-RF2	Confirm the lifecycle states and their names – is the proposed New → In review → Accepted → Converted / Rejected (plus On hold) right, and do you want a distinct Triage state (as Mark's Intake had) separate from "In review"?	§4
OQ-RF3	Are there SLA / age targets for referrals (when an unactioned referral should be chased / escalated)? The list RAG-ages at 7 / 14 days as a placeholder.	§1
OQ-RF4	Define the duplicate-match rule (R-005): match on address, phone, or both; automatic vs. operator-confirmed; and the dual-occupancy / "one next-of-kin per" rule carried from the transcript coverage review (07).	§3, 07
OQ-RF5	Permissions: who may convert vs. reject referrals? On conversion, should the first installation request (and its assessment) be auto-created, or raised separately in Requests?	§5
OQ-RF6	Confirm the rejection and on-hold reason category lists (candidate sets shown), and whether "no responder coverage" rejections should feed a responder-recruitment view (M5).	§6, P-004
OQ-RF7	Confirm the old-form fields kept as agreed referral fields – Referrer details, Organisation list, Referral cause, Self-referral – none were re-decided in the meetings.	§3
OQ-RF9	Confirm dropping the old-SM Priority (Normal / Urgent) field from referrals – we propose urgency be read from Source (e.g. Hospital discharge) and the days-open aging instead, since a pre-agreement referral carries no SLA. Reinstate if triage needs an explicit flag.	§1, §9
OQ-RF8	Provide the catalogued Referrals / Quick Agreement screenshot set so the coverage counts can be reconciled programmatically (as done for the profile module).	§9

SSL Service Manager · Referrals specification v0.9 · paired with 16 Referrals wireframes. Every decision ID links to the register (00); every section links to its wireframe screen. Keep this spec and the wireframes in sync.