eHealth Infrastructure
2.3.0 - release

eHealth Infrastructure - Local Development build (v2.3.0). See the Directory of published versions

Resource Profile: ehealth-message

Official URL: http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-message Version: 2.3.0
Active as of 2022-09-27 Computable Name: ehealth-message

Introduction

An ehealth-message defines written communication and comes in four flavours depending on the “category” of the message:

  • Message: For sending messages from Patients, CareTeams (Practitioners), and Devices to Patients or CareTeams. Messages may not be sent between Patients or between Practitioners. When sending a message to a CareTeam, it is possible to narrow the recipient to be of a certain role. This is done by setting the “restriction-category” extension to a specific role value.
  • Notification: For sending notification from Practitioners to Patients. These are usually text-based, and may have a temporal validity attached (see “period” extension) to indicate at which point a notification is no longer valid. When sent, a notification may no longer be updated by the sender.
  • Advise: Advise is much like notifications. They may also have a validity period, but they can be seen as reminders caused by a planned event, eg. a measurement or online meeting which is to take place.
  • Note: For personal notes (written by a Patient or Practitioner), which may be shared with a CareTeam. A personal note must be created with sender=recipient. In case a personal note wants to be shared with a CareTeam, the CareTeam must be referred by the recipientCareTeam extension, and the receiver deleted (both can take place in the same PATCH operation). A personal note may be updated by the sender, but not by the recipient.

An ehealth-message may refer related resources (eg. Device, CarePlan, Appointment etc) using the “about” field, no matter which category it is. Different instances of ehealth-message may be logically organized into “threads” by assigning the same thread-id in the provided extension. Similarly, they may be organized in a group (eg. group messages) by assigning the same group-id in that extension. The message subject may be provided in the title extension, and an optional priority may be provided in the ehealth-priority extension.

Remarks about status and administrative-status

The ehealth-message profile contains two status fields:

  • status:
    • For notes (category=’note’) the status field has no restrictions or implications
    • For messages (category=’message’) the following status transitions rules are in effect:
      • A message is considered “not yet sent” when it has one of the following status and can freely transition from one to another: ‘preparation’, ‘on-hold’, ‘not-done’, ‘entered-in-error’
      • A message is considered “being sent” when created or patched into status ‘in-progress’ and cannot be patched further or deleted by the sender
        • The server will automatically transition a message from ‘in-progress’ to ‘completed’ when it has been sent successfully (happens immediately for non-NemSMS mediums and is reflected in the returned resource)
        • The server will automatically transition a message from ‘in-progress’ to ‘stopped’ if it could not be sent (currently only happens if a NemSMS could not be sent)
      • The client can never create or patch a message into status ‘completed’ or ‘stopped’
      • The sender cannot patch, only delete messages with status ‘stopped’
      • The sender cannot patch or delete messages with status ‘completed’
      • The recipient can patch /received and administrative-status on messages with status ‘completed’
  • administrative-status (extension): Makes it possible for the message recipient to indicate the state of a message. A message may hold an administrative status that defines the last action the recipient took on the message in question. At first, the message has administrative-status “activate”. The recipient may mark the message as read by setting administrative-status “read”. If the recipient considers the message a sort of “task”, the message may also be updated with administrative-status “complete” when the task is done, or “reactivate” if the task was not complete anyway.

Fields with auto-assigned values

Some fields are filled in automatically on message creation, eg. if a sound default value makes sense. These fields are:

  • Field “sent”: If message state is set to “in-progress” on creation, then the “sent” field will be assigned current date/time.
  • Extension “restriction-category”: If not set by the caller, it will be set to value “None”
  • Extension “thread-id”: In case a thread-id is not set by the client, it will be generated server-side (random UUID) at message creation.

Search parameters

The following custom search parameters may be used when searching for ehealth-message instances:

  • administrativeStatus: Specify the desired administrative status using system and code (eg. “http://ehealth.sundhed.dk/cs/administrative-status” and “read”)
  • careTeamRecipient: Specify an absolute reference to the CareTeam which must be message recipient
  • careTeamSender: Specify an absolute reference to the CareTeam which must be message sender
  • communicationCategory: Specify the desired category using system and code (eg. “http://ehealth.sundhed.dk/message-category/” and “message”)
  • period: Use a date-type search to filter messages that must conform to temporal constraints (eg. notifications that are only valid until a specific point in time)
  • threadId: Specify the logical “thread id” used to correlate messages
  • restrictionCategory: Specify the desired restriction category using system and code (eg. “http://ehealth.sundhed.dk/cs/restriction-category” and “measurement-monitoring”)
  • episodeOfCare: Specify the desired episodeOfCare reference (provided in extension http://hl7.org/fhir/StructureDefinition/workflow-episodeOfCare)

Scope and Usage

In the eHealth Infrastructure the ehealth-message resource is used in conjunction with the following resources:

  • Patient
    • As sender or recipient of a message
  • Practitioner
    • As sender/recipient of a message (only when category is “note”)
  • Device
    • As sender of an ehealth-message (as a result of automatic processing/triage)
  • CareTeam
    • As sender or recipient using the extensions senderCareTeam/recipientCareTeam, respectively

General rules

The following rules apply for the ehealth-message profile:

  • If medium.code is eboks or nemsms, the recipient must be of type Patient
  • Only one of sender or extension senderCareTeam may be filled in
  • Only one of recipient or extension recipientCareTeam may be filled in
  • Medium ‘nemsms’ may only be used if the Patient allows reception of NemSMS (has telecom with value ‘NemSMS’). In that case, a NemSMS message will be sent to the Patient.

NemSMS Notifications

The Patient service will forward ehealth-messages to the public danish NemSMS service given the following conditions:

  • message.medium.code is ‘nemsms’ (defined in http://ehealth.sundhed.dk/cs/message-medium)
  • message.status is ‘in-progress’

The message is forwarded asynchronously. To track the progress of the NemSMS, the status and statusReason code is used:

  • Initially, a NemSMS is sent like any other message by setting the status to ‘in-progress’. The status will remain ‘in-progress’ while the NemSMS is being dispatched.
  • If the NemSMS dispatch is successful, status is updated to ‘completed’ by the server.
  • If the NemSMS dispatch fails, status is updated to ‘stopped’ by the server and statusReason is set to either ‘system-error’ or ‘recipient-unavailable’ (defined in http://hl7.org/fhir/R4/valueset-communication-not-done-reason.html)
    • A message.note.text may be added to the message which can contain further information about the reason for dispatch failure in case of ‘system-error’

Automatic NemSMS Notifications

The Patient service will generate NemSMS ehealth-messages, notifying the recipient that they have received a message, given the following conditions:

  • message.medium.code is not ‘nemsms’
  • message.status is ‘completed’
  • message.category is ‘message’ (defined in http://ehealth.sundhed.dk/cs/message-category)
  • message.recipient is a Patient reference
  • patient.telecom contains ContactPoint ‘NemSMS’

The Patient service will generate NemSMS ehealth-messages, notifying patients that they have an appointment or video appointment scheduled for de following day, given the following conditions:

  • appointment.start is current day + 1 day
  • appointment.participant contains one Patient reference
  • patient.telecom contains ContactPoint ‘NemSMS’

Update rules

An ehealth-message may not have its category changed, eg. from ‘note’ to ‘message’.
An ehealth-message may be PATCH updated on paths complying with the regular expressions below (provided that security and status transition rules are obeyed)

  • /implicitRules.*
  • /contained.*
  • /recipient.*
  • /definition.*
  • /basedOn.*
  • /partOf.*
  • /topic.*
  • /about.*
  • /context.*
  • /received.*
  • /reasonCode.*
  • /reasonReference.*
  • /payload.*
  • /note.*
  • /status.*
  • /extension.*

Usage:

Formal Views of Profile Content

Description of Profiles, Differentials, Snapshots and how the different presentations work.

This structure is derived from Communication

Summary

Mandatory: 4 elements (3 nested mandatory elements)
Must-Support: 1 element

Structures

This structure refers to these other structures:

Extensions

This structure refers to these extensions:

Slices

This structure defines the following Slices:

  • The element Communication.category is sliced based on the value of value:coding.system
  • The element Communication.medium is sliced based on the value of value:coding.system
  • The element Communication.payload.content[x] is sliced based on the value of type:$this (Closed)

 

Other representations of profile: CSV, Excel, Schematron

Terminology Bindings

PathConformanceValueSet
Communication.languagepreferredCommonLanguages
Max Binding: AllLanguages
Communication.statusrequiredEventStatus
Communication.statusReasonexampleCommunicationNotDoneReason
Communication.categoryexampleCommunicationCategory
Communication.category:DkTmCategoryexampleCommunicationCategory
Communication.category:DkTmCategory.coding.coderequiredMessageCategory
Communication.priorityrequiredRequestPriority
Communication.mediumexampleParticipationMode
Communication.medium:DkTmMediumexampleParticipationMode
Communication.medium:DkTmMedium.coding.coderequiredMessageMedium
Communication.topicexampleCommunicationTopic
Communication.reasonCoderequiredeHealth Message Reason Code

Constraints

IdGradePathDetailsRequirements
nemsms-invarianterrorCommunicationIf communication resource is a NemSMS payload cannot exceed 160
: medium.coding.where(code = 'nemsms').exists() implies payload.contentString.length() <= 160
note-invarianterrorCommunicationCategory note invariant
: category.coding.code = 'note' implies (sender.reference = recipient.reference) or (recipient.reference.exists().not() and extension.where(url = 'http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-recipientCareTeam').valueReference.exists())
notification-invarianterrorCommunicationCategory notification invariant
: category.coding.code = 'notification' implies recipient.reference.contains('Patient/') and ( sender.reference.contains('Practitioner/') or extension.where(url = 'http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-senderCareTeam').valueReference.exists())
message-invarianterrorCommunicationCategory message invariant
: category.coding.code = 'message' implies (recipient.reference.contains('Patient/') and ( sender.reference.contains('Device/') or contained.ofType(Device).where('#' + id = %resource.sender.reference).empty().not() or extension.where(url = 'http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-senderCareTeam').valueReference.exists())) or (( extension.where(url = 'http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-recipientCareTeam').valueReference.exists()) and (sender.reference.contains('Patient/') or sender.reference.contains('Device/'))) or (extension.where(url = 'http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-recipientCareTeam').valueReference.exists() and extension.where(url = 'http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-senderCareTeam').valueReference.exists() )