Communication Profile¶
| Canonical | https://fhir.apps.health/StructureDefinition/nexus-emr-core-communication |
|---|---|
| Status | draft (experimental) · 1.33.0 |
| Base | Communication (constraint) |
| Source | FSH · JSON |
Nexus EMR profile for Communication, covering three distinct populations: WELL-internal staff chat about a patient, eReferral correspondence passed through from or to external partners, and outbound delivery (one fax, SMS or email sent to one recipient through a delivery service). First pass -- the pass-through boundary and message threading are not yet settled.
FSH
The authored source of truth: resources/StructureDefinition-nexus-emr-core-communication.fsh (edit on GitHub). One FSH file may define several related artifacts.
// NexusEmrCoreCommunication.fsh
// FIRST PASS. Three genuinely different things share this resource type today, and the profile
// has to acknowledge each without pretending they are one model.
//
// 1. WELL-INTERNAL CHAT. The in-app chat panel runs entirely on Communication -- staff
// messaging each other about a patient. Internal operational read/write.
// 2. eREFERRAL PASS-THROUGH. Communication instances arriving from and going to external
// eReferral partners (Ocean and others), where the shape is the partner's, not ours.
// 3. OUTBOUND DELIVERY. One fax, SMS or email transmitted to one recipient through a delivery
// service, recorded with its delivery lifecycle. Marked by the `outbound-delivery` category
// (CodeSystem-nexus-communication-category.fsh), which switches on the rules below.
//
// THE FIRST TWO NEED DIFFERENT THINGS FROM THIS GUIDE, which is why they are modelled apart rather than
// reconciled. Pass-through (2) needs to be DOCUMENTED: the shape is the partner's, and a consumer
// needs to know it arrives unaltered and what may be relied on. Internal chat (1) needs a governed
// CONTRACT, because it is a surface this platform owns and writes, and nobody else's specification
// is going to constrain it.
//
// WHAT THIS RESOURCE IS NOT, ruled 2026-08-19: **it is not the conversation on a Task.** An earlier
// design paired every Task with Communication resources for its turns, and both shapes ended up
// partly documented at once, which is worse than either. A task's turns are `Task.note` repeats,
// typed to the Task Note profile -- see `StructureDefinition-nexus-emr-task-note.fsh`, and the
// `note` element on the ClinicalTask profile for the reasoning and for the additive graduation
// valve if per-turn identity is ever needed. The two populations above are messages that exist in
// their own right; a task turn is not one of them, and a writer reaching for Communication to
// record "what was said on this task" is reaching for the wrong resource.
//
// FIRST-PASS SCOPE. Skeleton, the `category` discriminator that separates the two populations,
// and the constraints that keep internal chat readable. Deliberately NOT settled: the
// pass-through boundary (which elements external partners may set freely), message threading
// (`inResponseTo` vs `partOf` -- the chat panel currently threads by neither), and whether
// internal chat should move off Communication entirely onto a non-clinical transport.
Alias: $NexusEmrCoreCommunication = https://fhir.apps.health/StructureDefinition/nexus-emr-core-communication
// The category discriminator is what lets a reader tell internal chat from partner traffic.
// Without it the two populations are indistinguishable and a chat panel query can surface
// eReferral correspondence (or vice versa) into a surface never designed for it.
Invariant: communication-has-category
Description: "SHOULD carry a category identifying which population this Communication belongs to (internal chat vs external eReferral traffic) -- the two are otherwise indistinguishable to a reader"
Severity: #warning
Expression: "category.exists()"
// OUTBOUND DELIVERY: EXACTLY ONE MEDIUM, FROM THE MEDIUM VALUE SET. The medium decides how the
// delivery address is read (a number to dial, a mobile to text, an address to mail), so a delivery
// record with none, or with two, cannot be accounted for. The codes are tested explicitly rather
// than with memberOf(): these invariants are evaluated by offline validators, and membership needs
// a terminology service. A code added to ValueSet-nexus-communication-medium.fsh is added here too,
// and to the request's medium invariants (StructureDefinition-nexus-core-communicationrequest.fsh).
Invariant: nexus-communication-outbound-medium
Description: "A Communication carrying the nexus-communication-category `outbound-delivery` code SHALL carry exactly one `medium`, and it SHALL carry a code from the nexus-communication-medium value set: v3 ParticipationMode FAXWRIT, EMAILWRIT or SMSWRIT."
Severity: #error
Expression: "category.coding.where(system = 'https://fhir.apps.health/CodeSystem/nexus-communication-category' and code = 'outbound-delivery').exists() implies (medium.count() = 1 and medium.coding.where((system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and (code = 'FAXWRIT' or code = 'EMAILWRIT' or code = 'SMSWRIT'))).exists())"
// OUTBOUND DELIVERY: THE ADDRESS ACTUALLY USED, ALWAYS. Not inferred from `recipient`: the
// referenced resource's number can change after the send, and a bare number has no resource. See
// CommunicationDeliveryExtensions.fsh. `extension.where(url = ...)` rather than the `extension(...)`
// shorthand, for the TypedFhir subset reason given on the Provenance profile.
Invariant: nexus-communication-outbound-delivery-address
Description: "A Communication carrying the nexus-communication-category `outbound-delivery` code SHALL carry exactly one https://fhir.apps.health/StructureDefinition/nexus-communication-delivery-address extension: the number or address the message was actually sent to."
Severity: #error
Expression: "category.coding.where(system = 'https://fhir.apps.health/CodeSystem/nexus-communication-category' and code = 'outbound-delivery').exists() implies extension.where(url = 'https://fhir.apps.health/StructureDefinition/nexus-communication-delivery-address').count() = 1"
// Profile Definition
Profile: NexusEmrCoreCommunication
Parent: Communication
Id: nexus-emr-core-communication
Title: "Communication Profile"
Description: "Nexus EMR profile for Communication, covering three distinct populations: WELL-internal staff chat about a patient, eReferral correspondence passed through from or to external partners, and outbound delivery (one fax, SMS or email sent to one recipient through a delivery service). First pass -- the pass-through boundary and message threading are not yet settled."
* insert UniversalProfile
* ^url = $NexusEmrCoreCommunication // Canonical URL from alias
* ^status = #draft
* insert NoResourceNoteExtension
* ^experimental = true
* obeys communication-has-category
* obeys nexus-communication-outbound-medium
* obeys nexus-communication-outbound-delivery-address
* . ^short = "Nexus EMR Communication Core"
* . ^definition = """
A message, usually about a patient. WELL-internal staff chat, eReferral correspondence
exchanged with an external partner, or an outbound delivery: one fax, SMS or email sent to one
recipient through a delivery service. `category` distinguishes them and readers should scope
on it -- the populations have different authorities over their content.
"""
// -----------------------------------------
// Outbound delivery -- the facts R4 has no element for (CommunicationDeliveryExtensions.fsh)
// -----------------------------------------
* extension contains
NexusCommunicationDeliveryAddress named deliveryAddress 0..1 MS and
NexusCommunicationPageCount named pageCount 0..1 MS
* extension[deliveryAddress] ^short = "The number or address an outbound delivery was actually sent to"
* extension[deliveryAddress] ^comment = "Required on an `outbound-delivery` Communication (invariant `nexus-communication-outbound-delivery-address`)."
* extension[pageCount] ^short = "Pages of an outbound fax the delivery service reports it transmitted"
// THE effective date for this profile: when the message was sent, falling back to when it was
// received. A message with neither is undatable and cannot join any date-driven chart surface.
* insert EffectiveDate([[sent | received]])
* insert Salient(status, status, code)
* insert Salient(category, category, coded)
* insert Salient(date, [[sent | received]], dateTime)
// CLOSED TO SMART APPS PENDING AN EXPOSURE DECISION, and it was briefly open for read AND write.
//
// This type was left closed deliberately when SMART exposure was first declared in the IG.
// 1.26.0 opened it on the reasoning that the shipped application reads and writes it -- which is
// true, and is not the same question: the first-party application takes its permissions from role
// claims through its own security context, never from a SMART scope. "The endpoint serves it" and
// "a third-party app may reach it" are two decisions, and this mechanism exists precisely to keep
// them apart.
//
// WHAT CHANGED SINCE THEN IS THE ARGUMENT FOR CLOSING IT AGAIN RATHER THAN AGAINST. This type
// now carries a patient's CORRECTION REQUEST and their STATEMENT OF DISAGREEMENT -- the statutory
// record of a dispute between an individual and their custodian. A wildcard read reaches both, and
// a wildcard write would let an application post into that space.
//
// The read half is genuinely arguable: a statement of disagreement is required to follow the record
// it disputes when that record is disclosed, so an application assembling a disclosure has a real
// claim to it. The write half is not arguable on the same grounds and was granted with it, because
// the grant is per type and these are one type. That is the decision to take, and it should be
// taken knowing which content is behind it.
//
// What would decide it: an application that names whether it needs the clinical message thread, the
// privacy correspondence, or both -- and a ruling on whether the two can be separated at all, given
// that a SMART scope names a resource TYPE and `Consent` already demonstrates what it costs when
// three families share one.
* meta.source 0..1 MS
* meta.source ^short = "Identifies EMR instance & pipeline version the resource came from"
* meta.source ^definition = "A URI that identifies the EMR pipeline and version from which this resource originated. This tells you which EMR instance (recommend using the instance identifier), and the version of the pipeline code/transformations."
* text 0..1 MS // Narrative element with human-readable summary
* text ^short = "Narrative"
* text ^definition = "A human-readable narrative summary of the NexusEmrCoreCommunication resource for human interpretation."
// NOT Must Support, and the reason is that nothing mints one. `identifier` here is
// RECOMMENDED but not required, under no mandated system -- and since the instance-scoped
// scheme was retired no producer writes a business identifier onto this type at
// all. Must Support asserts that an implementer can be expected to populate an element;
// claiming it for one the specification neither mandates nor produces states a guarantee
// that is not being made. The element stays available and documented -- a writer with a
// source-system identifier should still carry it.
* identifier 0..*
* identifier.system 1..1
* identifier.value 1..1
* identifier ^short = "Business identifier(s) for the communication"
* identifier ^definition = """
Unique identifiers for the communication.
A business identifier is recommended but not required (identifier is 0..*). For eReferral traffic this is where the partner's own message identifier belongs -- it is the only governed way to correlate a reply with what it replies to across the boundary.
⚠ HERITAGE EMR SITUATION -- UNRESOLVED. Heritage EMRs have internal messaging and inbox features, but they are NOT modelled as FHIR Communication: they are local message tables with their own threading, read/unread state, and per-user routing that has no FHIR equivalent. Nothing currently maps them into this resource. Two consequences: (1) a heritage-sourced message has no identifier this IG can name, so any ingest would have to mint one, and (2) migrating that history at all is an open decision -- the alternative is to leave heritage messages in the source system and have this resource cover only natively-authored traffic. Until that is decided, treat every Communication here as either WELL-internal-native or external eReferral, never heritage-migrated.
For an outbound delivery this is where the delivery service's own message id belongs, under that service's system: [`nexus-ringcentral-message-id`](../fhir/NamingSystem-NexusRingcentralMessageIdNS.md), [`nexus-srfax-fax-id`](../fhir/NamingSystem-NexusSrfaxFaxIdNS.md) or [`nexus-sendgrid-message-id`](../fhir/NamingSystem-NexusSendgridMessageIdNS.md). A service's id is unique only within that service, so match system and value together. It is present once the service has accepted the message.
If no recognized system exists, implementers MAY invent a URI for the system.
A source system's own identifier SHOULD be carried alongside this one, flagged `use = secondary`. See [Carrying the raw code](../guide/patterns/raw-codes.md).
"""
* status 1..1 MS
* status ^short = "preparation | in-progress | not-done | completed | entered-in-error | ..."
* status ^comment = """
Internal chat writes `completed` on send. For eReferral traffic the partner's lifecycle applies and `status` is pass-through -- do not infer local workflow state from it.
For an outbound delivery, `status` is the delivery lifecycle:
- queued, not yet accepted by the delivery service: `preparation`
- accepted by the delivery service: `in-progress`
- delivered: `completed`
- failed for good: `not-done`, with `statusReason` carrying the delivery service's error code and text
- cancelled before the delivery service accepted it: `not-done`
- cancelled after the delivery service accepted it: `stopped`
`sent` is when the delivery service accepted the message, and `received` is when it reported delivery. A retry after failure is a new Communication whose `basedOn` names the attempt it repeats; a failed attempt keeps `not-done`.
"""
// -----------------------------------------
// Category -- the population discriminator (see communication-has-category)
// -----------------------------------------
* category 0..* MS
* category from NexusCommunicationCategoryVS (extensible)
* category ^short = "Which population: internal staff chat, or external eReferral correspondence"
* category ^definition = """
Which population this Communication belongs to. Readers should scope on it -- internal chat and
external eReferral correspondence have different authorities over their content, and a chat surface
that does not scope will surface partner correspondence into a panel never designed for it.
**Outbound delivery is not chat.** A Communication carrying `outbound-delivery` from
`nexus-communication-category` records a fax, SMS or email sent through a delivery service. A chat
surface must exclude it, including one that today selects everything that is not eReferral.
⚠ HERITAGE EMR SITUATION -- UNRESOLVED. If heritage-EMR message history is ever migrated (see
`identifier`), it becomes a THIRD population alongside internal chat and eReferral, and this element
is where that distinction would have to live. No code for it exists, because the migration decision
has not been made. Anyone binding a value set here must resolve that first, or the binding will need
widening the moment migration is agreed.
"""
* category ^comment = "Bound extensible to `nexus-communication-category`, which includes every HL7 communication-category code (staff chat writes `notification`) plus this guide's `outbound-delivery`. Extensible because the pass-through boundary is not yet decided: a partner-supplied category, and the Patient Request for Corrections codes a statement of disagreement carries, must stay conformant. Readers MUST still tolerate a text-only category, and must not treat an unrecognized one as invalid."
* subject 0..1 MS
* subject ^short = "The patient the communication is about"
* subject only Reference(NexusEmrCorePatient)
* subject ^comment = "0..1 per R4. Internal chat about a patient SHOULD carry it -- a chat message with no subject cannot be scoped to a chart, and cannot be filtered out of one either, which is the access-control concern. An outbound delivery carries the patient the message concerns when there is one, and none for a message about no patient."
* sender 0..1 MS
* sender ^short = "Who sent the message"
* sender only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCorePatient or NexusEmrCoreRelatedPerson or NexusEmrCoreOrganization or NexusEmrCoreAppDevice)
* sender ^comment = "Practitioner is the primary provider identity in this IG. Organization covers a partner-system sender on inbound eReferral traffic; Device covers system-generated messages. On an outbound delivery the sender is the clinic Organization; the account that carried it is the `integration` coding in `medium`. RelatedPerson covers a SUBSTITUTE DECISION-MAKER acting for the patient -- a distinct fact from the patient acting themselves, and one that must not be flattened onto Patient: where a right over the record is exercised by proxy, the record has to show that authority was delegated, because that is what is checked when the exercise is challenged."
* recipient 0..* MS
* recipient ^short = "Who the message was addressed to"
* recipient only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCorePatient or NexusEmrCoreRelatedPerson or NexusEmrCoreOrganization or NexusEmrCoreCareTeam)
* recipient ^comment = "On an outbound delivery: one recipient per Communication, the recipient's name as `display` (the number or address, for a bare number), and no reference. The recipient as asked was in the request to send, a contained Organization that links no stored record, and the request is not stored: the delivery keeps the name as `display` and the address actually used in the `deliveryAddress` extension."
* medium 0..* MS
* medium from NexusCommunicationMediumVS (preferred)
* medium ^short = "How the message was sent: FAXWRIT | EMAILWRIT | SMSWRIT"
* medium ^comment = "An outbound delivery carries exactly one, from the Communication Medium value set (invariant `nexus-communication-outbound-medium`), and beside that code the `integration` coding naming the clinic sending account that carried it. Bound preferred rather than extensible so that eReferral traffic keeps whatever medium its partner sends; the invariant is what makes it strict for outbound delivery."
// THE SENDING ACCOUNT. On an outbound delivery the account that carried the message is a second
// coding on the same `medium` entry, under `nexus-message-integration`: the same channel stated
// more precisely. Open slicing, so the HL7 kind coding and a partner's codings are unaffected.
// 0..1 because records written before 1.31.0 carry none.
* medium.coding ^slicing.discriminator.type = #value
* medium.coding ^slicing.discriminator.path = "system"
* medium.coding ^slicing.rules = #open
* medium.coding ^slicing.description = "The sending account, by system"
* medium.coding contains integration 0..1 MS
* medium.coding[integration] ^short = "The clinic sending account that carried an outbound delivery"
* medium.coding[integration] ^comment = "The code is the account's id in the clinic service; `display` is the account's name when it was used. Copied from the request's `medium` entry for this channel. Absent on records written before 1.31.0."
* insert MessageIntegrationCoding
* basedOn ^short = "On an outbound delivery: the earlier delivery a resend repeats"
* basedOn ^comment = "On an outbound delivery this narrows R4's meaning: `basedOn` never names a request, only the one earlier outbound delivery a resend repeats (`Communication/<id>`), and nothing else. A first send carries none: the request it was sent from is not stored, so there is nothing to point at. The attempt a resend repeats keeps its own status (typically `not-done`) and is not updated; a chain of resends is read by following `basedOn` back to the first attempt."
* sent 0..1 MS
* sent ^short = "When the message was sent"
* received 0..1 MS
* received ^short = "When the message was received"
// -----------------------------------------
// Payload -- the message content
// -----------------------------------------
* payload 0..* MS
* payload ^short = "The message content"
* payload ^comment = """
Internal chat writes `contentString`. eReferral traffic may carry `contentAttachment` or `contentReference` -- a reader that assumes contentString will silently render an empty message. Handle all three.
For an outbound delivery the payload is what was sent:
- fax: `contentReference` to the DocumentReference sent, as a version-specific reference (`DocumentReference/<id>/_history/<vid>`). This is the documented form: it records the document as it stood when it was faxed, which a later edit does not change.
- SMS: one `contentString`, the text sent.
- email: the body as one `contentString`, as on the request, plus one `contentReference` per attached DocumentReference. The subject line is `topic.text`, not a payload entry.
"""
// EMAIL SUBJECT. R4 defines `topic` as "similar to a subject line in an email", so the subject of an
// outbound email is `topic.text`. Before 1.31.0 the payload rule above put it in a `contentString`,
// where a reader could not tell it from the body.
* topic MS
* topic ^short = "The subject line of an outbound email"
* topic ^comment = "For an outbound email, `topic.text` is the subject line as sent; there are no codings. A request to send an email carries the same text in the `nexus-communication-email-subject` extension on the CommunicationRequest, and the Communication written for the send copies it here. Fax and SMS have no subject and carry no `topic`."
// -----------------------------------------
// Threading -- NOT YET MODELLED, and that is the finding
// -----------------------------------------
* inResponseTo 0..* MS
* inResponseTo ^short = "The message this one replies to"
* inResponseTo only Reference(NexusEmrCoreCommunication)
* inResponseTo ^comment = "⚠ FIRST PASS. The chat panel currently threads by neither `inResponseTo` nor `partOf` -- conversation order is reconstructed from timestamps, which is why concurrent messages can interleave wrongly. Declaring the element here is the first step; deciding whether threads are `inResponseTo` chains or a `partOf` grouping is open."