Skip to content

Communication Profile

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-emr-core-communication
Statusdraft (experimental) · 1.33.0
BaseCommunication (constraint)
SourceFSH · 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.

Overview

Handbook: Conversation Threading

The narrative treatment -- what this is for, why it is shaped this way, and how it is used.

Nexus EMR Core Communication Profile

Overview

The Nexus EMR Core Communication profile covers a message, usually about a patient. Three genuinely different populations share this resource type, and the profile models each rather than pretending they are one thing: internal staff chat about a patient, an operational read/write surface inside the EMR; eReferral correspondence exchanged with external partners, where the shape is the partner's rather than this IG's; and outbound delivery, one fax, SMS or email sent to one recipient through a delivery service (see Outbound delivery, below). category is what tells them apart, and readers should scope on it -- the populations have different authorities over their content.

The profile is #draft and experimental = true, and that marking should be taken literally. It is a first pass, committing to a skeleton, the category discriminator, and the constraints that keep internal chat readable. It is now reachable by a SMART on FHIR app for read, search, create and update: the profile declares smart-exposed -- this guide's positive flag for app reachability -- and the server capability statement lists it. Deletion is not granted; a message that should not have been sent is withdrawn through its own status, never removed.

THE effective date is sent, falling back to received. A message with neither is undatable and cannot join any date-driven chart surface.

What is settled

  • status (1..1). 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.
  • identifier (0..*, system and value each 1..1 when present). 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. Carry it. The warning-severity communication-has-raw-identifier invariant that used to nudge for it was removed in 1.21.0, so nothing checks it.
  • subject (0..1, NexusEmrCorePatient) is optional per R4 but should be carried for chat about a patient. A message with no subject cannot be scoped into a chart, and cannot be filtered out of one either, which is the access-control consequence.
  • sender (0..1) may be a Practitioner, PractitionerRole, Patient, Organization or AppDevice -- Organization covers a partner system on inbound traffic, Device covers system-generated messages. recipient (0..*) spans the same set plus CareTeam.
  • payload (0..*) varies by population. Internal chat writes contentString; eReferral traffic may carry contentAttachment or contentReference. Handle all three -- a reader assuming contentString renders an empty message instead of failing visibly.

Category is bound extensible

category is 0..* with a warning-severity invariant (communication-has-category) recommending its presence, because without it the populations are indistinguishable and a chat query can surface partner correspondence into a panel never designed for it.

It is bound extensible to nexus-communication-category, which includes every HL7 communication-category code (staff chat writes notification) and this guide's outbound-delivery. Extensible rather than required because the pass-through boundary -- which elements an external partner may set freely -- is not settled, and a partner-supplied category must stay conformant. Readers must still tolerate text-only categories, and must not treat an unrecognized category as invalid.

Migration of message history from heritage EMRs is also open. Heritage systems model messaging as local tables with their own threading, read state and routing, and nothing currently maps them into this resource. If that history is ever migrated it becomes a third population, and this element is where the distinction would live -- which is what anyone binding a value set here has to resolve first.

Outbound delivery

A Communication carrying outbound-delivery from nexus-communication-category records one fax, SMS or email sent to one recipient through a delivery service. It is not chat: a chat surface that scopes on category must exclude it.

  • medium: exactly one, from nexus-communication-medium (FAXWRIT, EMAILWRIT or SMSWRIT). Invariant nexus-communication-outbound-medium. Beside it, an integration coding under nexus-message-integration names the clinic sending account that carried it (absent on records written before 1.31.0).
  • The address actually used: the nexus-communication-delivery-address extension, exactly one (invariant nexus-communication-outbound-delivery-address). recipient carries the recipient's name as display (the number, for a bare number) and no reference.
  • identifier: the delivery service's own id, under that service's system (nexus-ringcentral-message-id, nexus-srfax-fax-id, nexus-sendgrid-message-id).
  • Fax pages transmitted: nexus-communication-page-count, as the delivery service reports it.
  • status is the delivery lifecycle; the mapping from each delivery state to a status, and what sent and received mean, is in the comment on status in the element details.
  • A resend is a new Communication whose basedOn names the attempt it repeats. On an outbound delivery basedOn means that and nothing else; a first send carries none.
  • payload: for a fax, a version-specific reference to the DocumentReference sent (DocumentReference/<id>/_history/<vid>); for an SMS, the text; for an email, the body as text or a document reference, plus one reference per attached DocumentReference; the email's subject is topic.text.
  • sender is the clinic Organization; the account that carried the message is the integration coding in medium. subject is the patient the message concerns, and is absent for a message about no patient.

A message is sent by posting a CommunicationRequest to the message exchange service's $send-message operation: the recipients and the address to use for each, the channel and sending account, and what to send. The request is not stored and nothing refers back to it. Each send is recorded as one Communication per recipient per channel, and that Communication is the record of what was sent.

Do not build on threading yet

inResponseTo is declared (0..*, NexusEmrCoreCommunication) but conversation structure is not settled. Order is currently reconstructed from timestamps, which cannot separate messages sent concurrently, and whether a conversation is an inResponseTo chain or a partOf grouping is undecided -- as is whether internal chat belongs on Communication at all rather than on a non-clinical transport. Declaring the element is the first step, not the contract: treat thread structure read from either element as advisory, and do not persist a derived conversation graph expecting it to stay valid.

Terminology bindings

Path Strength Value set
Communication.category extensible Communication Category Value Set
Communication.medium preferred Communication Medium Value Set