Communication — who is told about a fax¶
The fax app tells a member of staff when a fax needs a person. It does so with an internal note in Spruce
Health that pages the person: the note lands in their Pages, and they resolve the page when they are done.
A page is what typing @name in an internal note does in the Spruce app; the fax app adds it for you, and the note
shows the @name. Nothing the app sends can be seen by a patient.
There are two flows, and nothing else to decide:
- A fax that needs a person (results left out, a fax held, a fax given up, a fax the app does not process): an internal note to the fax owner, in a thread of the owner's own. No group or team conversation is needed.
- An imaging report: an internal note inside the patient's own thread in Spruce, paging the care coordinator of the patient's doctor, the front desk when you name one, and the doctor only when the finding is major.
What triggers a notice¶
| What happened | Who is paged | Where the note goes | What the note says |
|---|---|---|---|
| A fax was filed, and too many lab results could not be filed (the warn thresholds of Settings) | the fax owner, and the people beside them | the fax owner's thread | how many results were left out, the document type, the Elation report, links to the fax and to the review queue |
| A fax was held by the verdict: nothing was filed | the fax owner, and the people beside them | the fax owner's thread | how many results could not be filed; the fax stays in the Elation inbox |
| A fax was given up after its retries (off unless switched on) | the fax owner, and the people beside them | the fax owner's thread | why it was given up; it stays in the Elation inbox |
| A fax was not processed: over the page cap, or a document the app does not file (anything other than a lab result or an imaging report), or a lab page beside a filed page with nothing the app could file (on the "Fax not processed or given up" switch) | the fax owner, and the people beside them | the fax owner's thread | why: the page count and the cap, or the document type, or the pages read as a lab with no value; what the rest of the fax became; it stays in the Elation inbox |
| An imaging report was filed to a patient's chart | the care coordinator of the patient's doctor; the front desk when named; the doctor for a major finding | the patient's own thread in Spruce, as an internal note | how serious the finding was judged, then the report's Findings and Impression, word for word as printed, and the Elation report |
| An imaging report of a known patient could not be filed (with "Fax given up" and "Imaging report" both on) | the same people as for a filed report | the patient's own thread | that the report is not in the chart and is still in the Elation inbox, with its Findings and Impression when they could be read |
| An imaging report arrived, and the patient could not be found in Spruce, or had no chart in Elation and went to the staging chart | the fax owner; the doctor too for a major finding | the fax owner's thread | that a report arrived and why nobody on the patient was told, with the Elation report, and for a major finding the verdict and its reason. No text of the report |
| An imaging report was filed to a patient's chart and Patient message draft is on (People tab) | the front desk when named, else the care coordinator; never the doctor | the patient's own thread, right after the imaging note (a note conversation of its own, "Patient message draft (fax)", when the patient has no thread) | a draft of what the front desk may tell the patient, in plain words written from the report's Findings and Impression in the tone of your example messages, with the test's name and the Elation report. Only for a result judged no acute finding or routine follow-up — never for a major finding, never when the severity was not judged. Headed "DRAFT … Not sent to the patient. The clinician has not reviewed these words." |
| A lab report was filed to a patient's own chart (the "Lab results filed" switch) | the front desk when named, else the fax owner | the patient's own thread (a note on the contact when the patient has no thread). When the patient is not in Spruce nothing is sent: the Notices tab shows the notice as cancelled, "patient not in Spruce" | one line — "Lab results for this patient are filed in Elation." — and the Elation report. No values, no names |
| A prior authorization fax arrived (Elation's three Prior Auth types; the "Prior authorization fax" switch) | the front desk when named, else the fax owner | the patient's own thread when the chart matched; the fax owner's thread otherwise | that a prior authorization fax is in the Elation inbox and is not filed: handle it from the inbox, with the fax link. The app never files or processes a prior authorization |
Each kind has its own switch (Setup, What triggers a notice). A fax uploaded in the harness tells nobody unless "Harness uploads too" is on.
Where a note goes¶
The fax owner's thread. The app makes it in Spruce the first time a notice (or the test note) needs it: a note conversation named "Fax notices", with the fax owner and the people under Also tell as members. Nothing has to be created by hand. When those people change, the app makes a new thread for them. If you would rather have the notices in a team conversation you already use, pick it under Setup, Where notices go: this is optional.
The patient's thread. The patient's existing conversation with the practice. The note is internal: staff see it, the patient does not. A patient who has no thread on the practice's line gets a note linked to the contact instead, which only staff can open.
When the doctor is paged¶
Every imaging note pages the care coordinator. The doctor is paged only for a major finding, so that a page from the fax app keeps meaning something. The app judges the report's Impression when the fax is filed:
| Judged | Means | Who is paged |
|---|---|---|
| Major finding | the radiologist flagged the result as critical or called it in; an acute or life-threatening finding; a new finding suspicious for malignancy; clear progression of a known cancer; an urgent recommendation | the care coordinator, the front desk when named, and the doctor |
| Routine follow-up | an incidental finding with routine follow-up, a chronic condition unchanged | the care coordinator, the front desk when named |
| No acute finding | normal, stable, benign | the care coordinator, the front desk when named |
| Severity not judged | the judgement did not run | the care coordinator, the front desk when named. The note says so: read the Impression |
The note's first lines say what was judged and why, in fixed words ("MAJOR FINDING, needs the doctor: a new finding suspicious for malignancy"). The doctor's Spruce account is set per doctor on the People tab. A doctor without one: the fax owner is paged for the major finding instead, and the note says so. The judgement never changes what is filed or what the note quotes: the coordinator always gets the whole Findings and Impression.
The patient is matched by name and date of birth¶
Spruce is not linked to Elation in this practice. An imaging note goes on a patient only when exactly one Spruce contact has the same given name, family name and date of birth as the Elation chart. Two contacts, none, or a contact that is linked to another chart: the report's text goes nowhere, and the fax owner gets a note with the link instead. A wrong chart is worse than a missing note.
The patient's doctor is read from the Elation chart when the note is planned. A doctor without a care coordinator on the People tab falls back to the fallback care coordinator; the People tab counts how often that happened, by doctor.
A patient who had no chart in Elation gets one made from the fax when the fax prints a full name and date of birth. That chart is the patient's own: the Spruce contact is looked up from it like any other, and the note goes into the patient's thread. The new chart names no doctor, so the fallback care coordinator is paged. During the pilot such a patient is never on the pilot list, so the note is recorded, not sent.
The four modes¶
| Mode | What happens |
|---|---|
| Off | Nothing is planned and nobody is told. This is where the app starts |
| Dry run | Every notice is planned and recorded with who would have been told. Nothing is sent |
| Pilot | A note is sent only when every person it pages is on the pilot list and, for a note on a patient, the patient is on it too. Everything else is recorded |
| Live | Notes are sent to everyone the settings name |
The mode moves one step up at a time and any number of steps down. Turn off always works, at once. Lowering the
mode cancels what was not sent yet, so switching on again never sends a backlog. The server has a ceiling
(COMMUNICATION_MAX_MODE): the page cannot switch on a mode above it.
Setting it up¶
Open Communication in the fax app. The banner at the top says the mode in effect.
- Setup, Connection. The card says whether the server can reach Spruce and for which organization. Press Use with your organization's name. An operator sets the token on the server; nothing secret is ever typed into the page.
- People. Choose the fax owner: that is all a fax that needs a person requires. Optionally, under Also tell, tick people (they are paged) and teams (they are added to the owner's thread). For imaging: choose the fallback care coordinator, optionally a front desk person, then add one line per doctor with the care coordinator and, when the doctor should be paged for major findings, the doctor's own Spruce account. Under Patient message draft, switch the draft on when the front desk should get a draft of what to tell the patient after each imaging result, and paste up to five example messages (one per paragraph, at most 600 characters each): they set the tone and the length of the draft, never its content. Save.
- Setup, Where notices go. Nothing is required here. Pick a team conversation only if the notices about faxes should be posted there instead of the owner's thread (or paste its link; only conversations without a patient can be chosen). Switch on the kinds of notice you want — the two front-desk notices ("Lab results filed", "Prior authorization fax") page the front desk named on the People tab, the fax owner when none is. Save.
- Setup, Pilot. Tick the people who may be paged during the pilot and enter the Elation ids of the patients
who may receive a note. Save. Then press Send a test note, look for it in Spruce under Pages, and press
Check that it arrived. The first test note makes the owner's thread. The pilot cannot start before the page
says "The setup is proven." A test note that ends Failed with "Spruce refused the request" is one the
operator looks into with the probe (
scripts/spruce/probe_spruce.py --write --shape all): the page never shows Spruce's reason, the probe does. - Setup, Mode. Each step says what is still missing. Switch to Dry run, watch real faxes for at least two clinic days, then Pilot, then Live. Every switch asks first and says in plain words what will happen.
The Notices tab¶
Every notice, newest first: what it is about, the fax, who is paged, where, and its state. The page does not refresh by itself: press Refresh.
| State | Meaning |
|---|---|
| Waiting | It will be sent on the next round (a limit was reached, or Spruce asked to slow down) |
| Sent, not yet seen | Spruce accepted it; the app has not read it back yet |
| Delivered | The app read it back in the conversation, readable by staff only (an internal note, or a message in a team conversation) |
| Recorded, not sent | Planned in a dry run, or outside the pilot |
| No answer yet | Spruce did not answer. The same request is sent again; it cannot arrive twice |
| Never appeared | Spruce accepted it and it never showed. It is sent once more, without the text of the report |
| Needs a person | A setting keeps it from being sent. Details says which one; fix it, then Try again |
| Failed, Cancelled, Expired | Final. A failed notice can be tried again; it then carries no text of the report |
Details shows the route the notice took and its history. The exact words are shown for a note that carries no text of a report. For a note with Findings and Impression the page shows the section names and their length: the text is in Spruce, never on this page.
The fax explorer has a Notices tab on every fax, with the same states.
What the app never does¶
- It never messages a patient. The part of the app that talks to Spruce can send an internal note, or a message in a team conversation after checking that the conversation is staff only, and nothing else. The patient message draft is an internal note for the front desk: the app never sends those words to the patient, and the note says the clinician has not reviewed them.
- It never sends the text of a report to a thread that is not the patient's own, or to a patient the pilot list does not name while the pilot runs.
- It never stores the words of a note unless the first attempt to send it was not accepted; then it keeps them for the retry, for 72 hours at most, and erases them as soon as the note is accepted.
- It never writes a name, a date of birth or the words of a note into a log.
- If a note is ever read back as something a person outside the practice could read, all sending stops until a person has looked. The banner then says "All sending is stopped".
- It never pages a doctor for a finding it did not judge major, and it never decides anything else from that judgement.
Limits¶
At most 20 notes an hour and 100 a day (Setup, Limits). The limits count attempts. A note that does not fit waits, oldest first, imaging reports before the rest. None is dropped.