Messaging (Fax, SMS, Email)¶
⚠ FIRST PASS -- do not treat this as a contract. Both profiles on this page are
#draft.
An outbound fax, SMS or email has one input and one kind of record:
- The request, a
NexusCoreCommunicationRequest, is what a client posts to the message exchange service's$send-messageoperation to send the message: to whom and at what address, by which channel and sending account, and what to send. The service validates it against the profile and does not store it; nothing refers back to it. The operation's definition (where it is served, what it answers) is not in this guide yet; what is settled is the request's shape. - One delivery record per send, an outbound-delivery
NexusEmrCoreCommunication, one per recipient per channel, is the record of what was sent and what happened to it, including a failure. The operation answers with these records, so the caller holds their ids before the first send attempt. A resend, made through the service's$resend-messageoperation, is a new delivery whosebasedOnnames the attempt it repeats.
The request¶
A request is one channel, or a fax with an email (invariant nexus-commreq-channels). With a fax and
an email, the one document is faxed to the fax recipients and attached for the email recipients; the
body string goes only in the email.
| Fact | Element |
|---|---|
| Who asked, and when | the authenticated caller of $send-message; requester (a Practitioner, PractitionerRole or Device) and authoredOn are allowed but not must-support, and the service does not read them |
| The patient the message is about | subject, absent for a message about no patient |
| Each channel | one medium entry with two codings: the kind and the sending account |
| Each recipient, and the address to use | a contained Organization with name and telecom; recipient is a local #id reference to it, with the name as display |
| What to send | payload |
| The email's subject | the nexus-communication-email-subject extension |
Recipients are contained. The number or address chosen is copied into the request rather than
read off a stored Practitioner, Organization or Patient, because a stored record's contact details
can change after the send, and each delivery keeps the address it used. A bare number carries the number as its name. Every recipient
is a contained Organization (nexus-commreq-recipient-contained) with a name and at least one
address (nexus-commreq-recipient-named), at most one address per channel
(nexus-commreq-one-address-per-channel), each address for a channel on the request
(nexus-commreq-address-matches-medium), and every channel has at least one address
(nexus-commreq-channel-has-addressee).
The fax and email request example, abridged:
{
"resourceType": "CommunicationRequest",
"id": "commreq-consult-fax-and-email",
"contained": [
{ "resourceType": "Organization", "id": "r1", "name": "Lakeshore Cardiology",
"telecom": [ { "system": "fax", "value": "905-555-0142" } ] },
{ "resourceType": "Organization", "id": "r2", "name": "Northside Physiotherapy",
"telecom": [ { "system": "email", "value": "intake@northside.example" } ] }
],
"extension": [ { "url": "https://fhir.apps.health/StructureDefinition/nexus-communication-email-subject",
"valueString": "Consult note: A. Linwood" } ],
"status": "active",
"subject": { "reference": "Patient/avery-linwood" },
"medium": [
{ "coding": [
{ "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode", "code": "FAXWRIT" },
{ "system": "https://fhir.apps.health/CodeSystem/nexus-message-integration",
"code": "7f3c2a90-51d4-4e0b-9a1e-2c5d8b6f0a11", "display": "Main Street fax" } ] },
{ "coding": [
{ "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode", "code": "EMAILWRIT" },
{ "system": "https://fhir.apps.health/CodeSystem/nexus-message-integration",
"code": "b21e9c44-0f6a-47d2-8e33-91aa7c5e2d08", "display": "Clinic email" } ] }
],
"recipient": [ { "reference": "#r1", "display": "Lakeshore Cardiology" },
{ "reference": "#r2", "display": "Northside Physiotherapy" } ],
"payload": [
{ "contentReference": { "reference": "DocumentReference/anemia-consult-20250408/_history/1" } },
{ "contentString": "Please find the consult note attached." }
],
"authoredOn": "2025-04-10T09:58:00-06:00",
"requester": { "reference": "Practitioner/dr-emily-carter" }
}
Medium codes¶
The kind is a code from the Communication Medium value set, all HL7 v3 ParticipationMode:
| Code | Channel | telecom.system of the address |
|---|---|---|
FAXWRIT |
fax | fax |
EMAILWRIT |
email |
|
SMSWRIT |
SMS | sms |
The invariants test these codes by system and code directly rather than by value-set membership,
so they are evaluated by offline validators. A reader picks the kind out of medium by its system,
not by position.
The integration coding¶
Beside the kind, each medium entry carries the clinic sending account that carries that channel:
a coding under nexus-message-integration.
The code is the account's id in the clinic service and display is the account's name when it was
used. The code system has content = not-present: its codes are each clinic's own account ids, held
by the clinic service, unique and never reused.
On the request the account coding is required on every entry. On a Communication it is the
integration slice of medium.coding, copied from the request's entry for that channel, and absent
on records written before 1.31.0. Whether an account belongs to the clinic, and whether it sends the
kind it is paired with, are checked by the service that sends the message, not by the profiles.
Rules per medium¶
| Medium | What the request sends | Invariants |
|---|---|---|
| Fax | exactly one contentReference, version-specific (DocumentReference/<id>/_history/<vid>), so the record says which version was faxed |
nexus-commreq-fax-document |
| SMS | exactly one payload, a contentString with the text |
nexus-commreq-sms-text |
at most one contentString, the body, plus one contentReference per attachment; a subject in the email-subject extension, which nothing else carries |
nexus-commreq-email-body, nexus-commreq-email-subject |
On the Communication for an email send, the subject is
topic.text,
copied from the request's extension. Fax and SMS carry no topic.
The delivery record¶
An outbound delivery is a Communication with the
outbound-delivery category. It carries
exactly one medium from the value set above (nexus-communication-outbound-medium) and exactly one
nexus-communication-delivery-address
extension, the number or address actually used (nexus-communication-outbound-delivery-address).
| Fact | Element |
|---|---|
| The earlier delivery a resend repeats | basedOn, on a resend only; a first send carries none |
| The recipient | one recipient: the name as display (the number or address, for a bare number), no reference |
| The sender | sender: the clinic Organization; the account is the integration coding |
| What was sent | payload, as on the request; a fax by version-specific reference |
| The delivery service's id for the message | identifier, e.g. under nexus-srfax-fax-id, nexus-ringcentral-message-id or nexus-sendgrid-message-id |
| Pages a fax service reports it sent | the nexus-communication-page-count extension |
The delivered fax example, abridged.
It is a first send, to a bare number, so it carries no basedOn.
{
"resourceType": "Communication",
"id": "comm-outbound-fax-delivered",
"extension": [
{ "url": "https://fhir.apps.health/StructureDefinition/nexus-communication-delivery-address",
"valueContactPoint": { "system": "fax", "value": "+1 403 555 0187" } },
{ "url": "https://fhir.apps.health/StructureDefinition/nexus-communication-page-count",
"valueUnsignedInt": 3 }
],
"identifier": [ { "system": "https://fhir.apps.health/NamingSystem/nexus-srfax-fax-id", "value": "418823517" } ],
"status": "completed",
"category": [ { "coding": [ { "system": "https://fhir.apps.health/CodeSystem/nexus-communication-category",
"code": "outbound-delivery" } ] } ],
"medium": [ { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode",
"code": "FAXWRIT" },
{ "system": "https://fhir.apps.health/CodeSystem/nexus-message-integration",
"code": "7f3c2a90-51d4-4e0b-9a1e-2c5d8b6f0a11", "display": "Main Street fax" } ] } ],
"subject": { "reference": "Patient/avery-linwood" },
"sent": "2025-04-10T10:02:00-06:00",
"received": "2025-04-10T10:04:00-06:00",
"recipient": [ { "display": "+1 403 555 0187" } ],
"sender": { "reference": "Organization/cedarbrook-clinic" },
"payload": [ { "contentReference": { "reference": "DocumentReference/anemia-consult-20250408/_history/1" } } ]
}
A failed send is shown by the failed SMS example.
Status¶
The request (status,
invariant nexus-commreq-status) is always active: it is posted to be sent and is not stored, so
it has no lifecycle of its own. What happened to each send is on its delivery.
Each delivery (status):
| Status | Meaning |
|---|---|
preparation |
queued, not yet accepted by the delivery service |
in-progress |
accepted by the delivery service |
completed |
delivered |
not-done |
failed for good, with the service's error code and text in statusReason; or cancelled before the service accepted it |
stopped |
cancelled after the service accepted it |
sent
is when the delivery service accepted the message and
received
is when it reported delivery. A retry after a failure is a new Communication whose basedOn names
the failed attempt; the failed attempt keeps not-done.
What the profiles do not settle¶
- Finding the deliveries of one send in the store. The request is not stored and a first send
carries no
basedOn, so nothing in the store groups the deliveries one request produced. A caller that needs the grouping keeps the ids from the operation's reply. What would settle it is a reader that needs to find them from the store alone. - Application access. No SMART on FHIR scope reaches delivery records. Opening them is a decision for that type on its own; what would decide it is an application that needs to read them. A request is not stored, so there is nothing of it to expose.
Related¶
NexusCoreCommunicationRequestandNexusEmrCoreCommunication, the profiles