Skip to content

Communication Request Profile

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-core-communicationrequest
Statusdraft · 1.33.0
BaseCommunicationRequest (constraint)
SourceFSH · JSON

The request a client submits to send one message by fax, SMS or email: to which recipients, by which channel and sending account, and what to send. It is the input to the message exchange service's $send-message operation, validated against this profile and not stored. Each send is recorded as an outbound-delivery Communication. One channel, or fax with email. Recipients are contained Organizations holding the name and address to use. First pass.

FSH

The authored source of truth: resources/StructureDefinition-nexus-core-communicationrequest.fsh (edit on GitHub). One FSH file may define several related artifacts.

// StructureDefinition-nexus-core-communicationrequest.fsh
//
// The request a client submits to send one message by fax, SMS or email: to whom, by which channel
// and through which of the clinic's sending accounts, and what to send. It is the input to the
// message exchange service's `$send-message` operation: validated against this profile, not stored,
// and nothing refers back to it. Each send it produces is recorded as an outbound-delivery
// Communication (one per recipient per channel), and that Communication is the record of what was
// sent and what happened to it.
//
// ONE MESSAGE, ONE OR TWO CHANNELS. A request is a fax, an SMS or an email, or a fax with an email
// (the one document is faxed to the fax recipients and attached for the email recipients). Any other
// pairing is rejected: an SMS cannot carry the document a fax carries, so pairing it with one would
// send two different messages under one request.
//
// EACH CHANNEL STATES ITS ACCOUNT. A `medium` entry carries two codings: the HL7 ParticipationMode
// kind (`FAXWRIT`, `EMAILWRIT`, `SMSWRIT`) and the clinic sending account that carries it, under
// `nexus-message-integration`. The account is the same channel stated more precisely -- this fax
// account is a way of faxing -- so it sits beside the kind rather than in an extension. The fixed
// `system` of each coding is what tells the two apart. R4 lets the codings in one CodeableConcept
// differ in granularity; an account id is an instance rather than a narrower concept, and a reader
// holding only the account code needs the clinic service to say what it is. Whether an account
// belongs to the tenant and sends that kind is checked by the service, not by this profile.
//
// RECIPIENTS ARE CONTAINED. Each recipient is a contained Organization holding the name and the
// address to use, at most one per channel, and `recipient` is a local reference to it. The chosen
// number or address is copied in rather than read off a stored Practitioner, Organization or
// Patient: the stored record's contact details can change after the send, and the delivery must
// still say where the message went. Each Communication written for a send copies the address into
// its own delivery-address extension and the name into `recipient.display`, so the address used is
// kept on the delivery record. A bare number carries the number as its name, because an
// Organization needs a name. The cost is that a message to a known practitioner or patient is
// addressed, here, to an Organization named for them.
//
// ⚠ FIRST PASS -- draft. Do not treat the shape as a contract until it leaves draft.

Alias: $NexusCoreCommunicationRequest = https://fhir.apps.health/StructureDefinition/nexus-core-communicationrequest

// A request is posted to be sent and is not stored, so it has no lifecycle of its own: it is always
// active. What happened to each send, including a failure, is on its Communication.
Invariant:     nexus-commreq-status
Description:   "A request is active."
Severity:      #error
Expression:    "status = 'active'"

// The medium codes are tested by system AND code, 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 to nexus-commreq-channels,
// nexus-commreq-address-matches-medium and nexus-commreq-channel-has-addressee too.
Invariant:     nexus-commreq-channels
Description:   "One channel, or fax with email."
Severity:      #error
Expression:    "medium.count() = 1 or (medium.count() = 2 and medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'FAXWRIT').exists() and medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'EMAILWRIT').exists())"

Invariant:     nexus-commreq-recipient-contained
Description:   "Every recipient is a contained Organization."
Severity:      #error
Expression:    "recipient.all(reference.startsWith('#'))"

Invariant:     nexus-commreq-recipient-named
Description:   "Every contained Organization has a name and at least one address."
Severity:      #error
Expression:    "contained.all(name.exists() and telecom.exists())"

Invariant:     nexus-commreq-address-matches-medium
Description:   "Every address is for a channel on the request."
Severity:      #error
Expression:    "contained.telecom.all((system = 'fax' and %resource.medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'FAXWRIT').exists()) or (system = 'email' and %resource.medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'EMAILWRIT').exists()) or (system = 'sms' and %resource.medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'SMSWRIT').exists()))"

Invariant:     nexus-commreq-one-address-per-channel
Description:   "A recipient has at most one address per channel."
Severity:      #error
Expression:    "contained.all(telecom.where(system = 'fax').count() <= 1 and telecom.where(system = 'email').count() <= 1 and telecom.where(system = 'sms').count() <= 1)"

Invariant:     nexus-commreq-channel-has-addressee
Description:   "Every channel on the request has at least one address."
Severity:      #error
Expression:    "(medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'FAXWRIT').exists() implies contained.telecom.where(system = 'fax').exists()) and (medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'EMAILWRIT').exists() implies contained.telecom.where(system = 'email').exists()) and (medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'SMSWRIT').exists() implies contained.telecom.where(system = 'sms').exists())"

// `extension.where(url = ...)` rather than the `extension(...)` shorthand, for the TypedFhir subset
// reason given on the Provenance profile.
Invariant:     nexus-commreq-email-subject
Description:   "An email has a subject; nothing else does."
Severity:      #error
Expression:    "medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'EMAILWRIT').exists() = extension.where(url = 'https://fhir.apps.health/StructureDefinition/nexus-communication-email-subject').exists()"

// Version-specific, so the delivery record says exactly which version of the document was faxed.
Invariant:     nexus-commreq-fax-document
Description:   "A fax sends exactly one document, version-specific."
Severity:      #error
Expression:    "medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'FAXWRIT').exists() implies (payload.content.ofType(Reference).count() = 1 and payload.content.ofType(Reference).all(reference.matches('^DocumentReference/[^/]+/_history/[^/]+$')))"

Invariant:     nexus-commreq-email-body
Description:   "An email has at most one body string."
Severity:      #error
Expression:    "medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'EMAILWRIT').exists() implies payload.content.ofType(string).count() <= 1"

Invariant:     nexus-commreq-sms-text
Description:   "An SMS is one string."
Severity:      #error
Expression:    "medium.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode' and code = 'SMSWRIT').exists() implies (payload.count() = 1 and payload.content.ofType(string).exists())"

Profile:        NexusCoreCommunicationRequest
Parent:         CommunicationRequest
Id:             nexus-core-communicationrequest
Title:          "Communication Request Profile"
Description:    "The request a client submits to send one message by fax, SMS or email: to which recipients, by which channel and sending account, and what to send. It is the input to the message exchange service's $send-message operation, validated against this profile and not stored. Each send is recorded as an outbound-delivery Communication. One channel, or fax with email. Recipients are contained Organizations holding the name and address to use. First pass."
* insert UniversalProfile
* ^url = $NexusCoreCommunicationRequest
* ^status = #draft
* ^experimental = false
* insert NoResourceNoteExtension
* obeys nexus-commreq-status
* obeys nexus-commreq-channels
* obeys nexus-commreq-recipient-contained
* obeys nexus-commreq-recipient-named
* obeys nexus-commreq-address-matches-medium
* obeys nexus-commreq-one-address-per-channel
* obeys nexus-commreq-channel-has-addressee
* obeys nexus-commreq-email-subject
* obeys nexus-commreq-fax-document
* obeys nexus-commreq-email-body
* obeys nexus-commreq-sms-text

// THE effective date for this profile: `authoredOn`, the date the request was made, when a sender
// fills it. Kept so a request that carries one dates like any other record; the send operation
// does not read it.
* insert EffectiveDate([[authoredOn]])

// CLOSED TO SMART APPLICATIONS: no smart-exposed declaration, so no scope reaches it. A
// CommunicationRequest is not stored, so there is nothing for the FHIR endpoint to expose: a
// message is sent by posting the request to the message exchange service's `$send-message`
// operation, and the record of each send is an outbound-delivery Communication.

* . ^short      = "Nexus EMR request to send a fax, SMS or email"
* . ^definition = """
The request a client submits to send one message by fax, SMS or email: the recipients and the
address to use for each, the channel and sending account, and what to send. It is the input to the
message exchange service's `$send-message` operation, validated against this profile and not
stored; nothing refers back to it. Each send is recorded as an outbound-delivery Communication, one
per recipient per channel.
"""

// -----------------------------------------
// Email subject -- CommunicationRequest has no `topic`
// -----------------------------------------
* extension contains NexusCommunicationEmailSubject named emailSubject 0..1 MS
* extension[emailSubject] ^short = "The subject line of the email"
* extension[emailSubject] ^comment = "Required when `medium` includes email, absent otherwise (invariant `nexus-commreq-email-subject`). The email's Communication carries the same text as `topic.text`."

* status 1..1 MS
* status ^short = "active"
* status ^comment = "Always `active`: a request is posted to be sent (invariant `nexus-commreq-status`). It is not stored, so it has no lifecycle of its own; the outcome of each send, delivered or failed, is on its Communication."

* requester 0..1
* requester only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or Device)
* requester ^short = "Who asked for the message to be sent"
* requester ^comment = "A Practitioner or PractitionerRole for a person, a Device for a system. Allowed but not must-support: the send operation does not read it. Who sent the message is the authenticated caller."
* authoredOn 0..1
* authoredOn ^short = "When the request was made"
* authoredOn ^comment = "Allowed but not must-support: the send operation does not read it."

* subject 0..1 MS
* subject only Reference(NexusEmrCorePatient)
* subject ^short = "The patient the message is about"
* subject ^comment = "Absent for a message about no patient."

// -----------------------------------------
// Medium -- one entry per channel: the HL7 kind and the sending account
// -----------------------------------------
* medium 1..2 MS
* medium ^short = "One entry per channel: the kind (FAXWRIT | EMAILWRIT | SMSWRIT) and the account that sends it"
* medium ^comment = "One channel, or fax with email (invariant `nexus-commreq-channels`). Each entry carries exactly two codings, told apart by their fixed `system`: the HL7 ParticipationMode kind, and the clinic sending account under `nexus-message-integration`. Each Communication written for a send carries its own channel's entry."
* medium.coding ^slicing.discriminator.type = #value
* medium.coding ^slicing.discriminator.path = "system"
* medium.coding ^slicing.rules = #closed
* medium.coding ^slicing.description = "The channel kind and the sending account, by system"
* medium.coding contains
    kind 1..1 MS and
    integration 1..1 MS
* medium.coding[kind] ^short = "FAXWRIT | EMAILWRIT | SMSWRIT"
* medium.coding[kind].system 1..1
* medium.coding[kind].system = "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode"
* medium.coding[kind].code 1..1
* medium.coding[kind] from NexusCommunicationMediumVS (required)
* medium.coding[integration] ^short = "The clinic sending account that carries this channel"
* medium.coding[integration] ^comment = "The code is the account's id in the clinic service; `display` is the account's name when the request was made."
* insert MessageIntegrationCoding

// -----------------------------------------
// Recipients -- contained, with the address to use
// -----------------------------------------
* contained 1..* MS
* contained only Organization
* contained ^short = "The recipients: one Organization each, with a name and the address to use"
* contained ^comment = "Each holds `name` and `telecom`: at most one address per channel, each for a channel on the request, and every channel has at least one (invariants `nexus-commreq-recipient-named`, `nexus-commreq-one-address-per-channel`, `nexus-commreq-address-matches-medium`, `nexus-commreq-channel-has-addressee`). SMS addresses use `telecom.system` `sms`. A bare number carries the number as its name. The address is copied in, not read off a stored record; each delivery Communication records the address it used in its delivery-address extension."
* recipient 1..* MS
* recipient only Reference(Organization)
* recipient ^short = "A local reference to a contained recipient"
* recipient ^comment = "Always a local reference (`#id`) into `contained` (invariant `nexus-commreq-recipient-contained`); never a stored Practitioner, Organization or Patient."
* recipient.display 1..1 MS

// -----------------------------------------
// Payload -- what to send
// -----------------------------------------
* payload 1..* MS
* payload.content[x] only string or Reference(DocumentReference)
* payload ^short = "What to send"
* payload ^comment = """
- fax: exactly one `contentReference`, version-specific (`DocumentReference/<id>/_history/<vid>`), so the delivery record says which version was faxed (invariant `nexus-commreq-fax-document`).
- SMS: exactly one `contentString`, the text (invariant `nexus-commreq-sms-text`).
- email: at most one `contentString`, the body (invariant `nexus-commreq-email-body`), plus one `contentReference` per attached document. The subject is the `emailSubject` extension.
- fax with email: exactly one `contentReference`, the document, which is faxed and is the email's only attachment; no other document can be attached to the email, because `nexus-commreq-fax-document` counts every `contentReference` on the request. The string is the email body and is never faxed.
"""

// -----------------------------------------
// Not used
// -----------------------------------------
// The sender is the clinic that owns the sending account, so `sender` is not stated separately.
* implicitRules 0..0
* modifierExtension 0..0
* category 0..0
* sender 0..0
* basedOn 0..0
* replaces 0..0
* groupIdentifier 0..0
* statusReason 0..0
* priority 0..0
* doNotPerform 0..0
* about 0..0
* encounter 0..0
* occurrence[x] 0..0
* reasonCode 0..0
* reasonReference 0..0
* note 0..0