This page describes how solutions can use CommunicationRequest to control the eHealth Infrastructure automatic creation of FHIR Communication / ehealth-messages.

Content

1 Content
2 Introduction
3 Adding Control of Message Creation
- 3.1 Controlling Message Creation with the Patient as Recipient
- 3.2 Controlling Message Creation with CareTeam as Recipient
4 Scope of the Message Creation Control
- 4.1 Search Algorithms for CommunicationRequest applied in the Infrastructure
- 4.2 Selection algorithm
5 Overriding the Payload and/or Medium
6 Ending a Message Creation Control

Introduction

The eHealth Infrastructure automatically creates FHIR Communication (of profile https://ehealth.sundhed.dk/fhir/StructureDefinition-ehealth-message.html ) in various situations. This is described here: Behind the Scenes | Overview of Communication produced by the Infrastructure.

The solutions can control if and how these FHIR Communication are created through the use of FHIR CommunicationRequest (https://ehealth.sundhed.dk/fhir/StructureDefinition-ehealth-communication-request.html).

In the descriptions below, the terms opt-in and opt-out are used with the following meaning:

Opt-in: Use of CommunicationRequest by a Patient or CareTeam to get a copy of a Communication (profile ehealth-message) where the Patient or CareTeam is not the recipient of the default Communication.
Opt-out: Use of CommunicationRequest by a Patient or CareTeam to suppress the creation of the default Communication to the said Patient or CareTeam.

A CareTeam must be involved in an EpisodeOfCare or CarePlan to opt-in for Communication referring to the EpisodeOfCare and/or CarePlan and/or ServiceRequest.

Adding Control of Message Creation

To control the automatic creation of FHIR Communication, create a CommunicationRequest. In addition to the CommunicationRequest elements described below, certain elements must have specific values depending on the situation in which the Infrastructure automatically creates the Communication. See the subsections below.

CommunicationRequest:

subject = Patient reference
occurrencePeriod.start = start of the period for which the control applies
occurrencePeriod.end = end of the period for which the control applies, if known. Otherwise, it can be left empty.
status = active when control is in effect. Can be set to other values as appropriate (one of draft | active | on-hold | revoked | completed).
doNotPerform = false (or unset) for opt-in or override of medium/payload, true to opt-out (that is, to suppress creation)

CommunicationRequest subject shall not be set for control of message creation regarding:

Automated creation of medium nemsms Communication when Communication with category message and Patient as recipient created
Reminder about appointment

How to set the remaining elements of the CommunicationRequest varies with the situation, see below.

The Communication.category is set depending on the intended use and involved recipients. See the section Introduction on https://ehealth.sundhed.dk/fhir/StructureDefinition-ehealth-message.html for details. When a Communication with category=message is created to do human-human communication, it can be controlled whether to also send a mobile text message (NemSMS) to a Patient recipient as described on https://ehealth.sundhed.dk/fhir/StructureDefinition-ehealth-message.html#automatic-nemsms-notifications. This requires opt-in as it is not the default behavior.

Controlling Message Creation with the Patient as Recipient

The table below describes the various situations in which the automatic creation of FHIR Communication (ehealth-message) takes place. In the table, the columns following the naming pattern Element <some element name> describe what values must be used in a corresponding CommunicationRequest to control the creation.

To apply for FHIR Communication with the Patient as the recipient, add the following to the CommunicationRequest:

recipient = Patient reference
category = <depending on situation>
reasonCode = <depending on situation>
episodeOfCare = <depending on situation>
basedOn = <depending on situation>
priority = <depending on situation>

Situation	Created by Default	Opt-in Supported	Opt-out Supported	Payload and Medium Overridable	Element category	Element reasonCode	Element episodeOfCare	Element basedOn	Element priority

Situation	Created by Default	Opt-in Supported	Opt-out Supported	Payload and Medium Overridable	Element category	Element reasonCode	Element episodeOfCare	Element basedOn	Element priority
Unexpected measurement submitted	No	Yes	No	Yes	`notification`	`UnexpectedMeasuringResolving`		ServiceRequest reference
Missing measurement determined	No	Yes	No	Yes	`notification`	`MissingMeasurementResolving`		ServiceRequest reference
Reminder to submit measurement (about to be created)	Yes	No	Yes	Yes	`advice`	`ReminderSubmitMeasurement`	EpisodeOfCare reference
Communication created by triage (or other infrastructure rules)	No	Yes	No	Yes	`notification`	Depends on rule		ServiceRequest reference	Depends on rule
EpisodeOfCare created	No	Yes	No	Yes	`notification`	`EpisodeOfCareCreated`
EpisodeOfCare changed (in team, status, scheduledStatus or scheduledTeam)	No	Yes	No	Yes	`notification`	`EpisodeOfCareCareTeamChange` , `EpisodeOfCareScheduledCareTeamChange` , `EpisodeOfCareStatusChange` or `EpisodeOfCareScheduledStatusChange`	EpisodeOfCare reference
CarePlan created/changed (in careTeam, status, scheduledStatus or scheduledTeam)	No	Yes	No	Yes	`notification`	`CarePlanCreated`,`CarePlanCareTeamChange` , `CarePlanScheduledCareTeamChange` , `CarePlanStatusChange` or `CarePlanScheduledStatusChange`	EpisodeOfCare reference
Reminder about appointment	Yes	No	Yes	Yes	`advice`	`AppointmentNotification` or `VideoAppointmentNotification`depending on appointment type	EpisodeOfCare reference (optional) If specified, the CommunicationRequest is specific to the Appointment referencing the EpisodeOfCare. See the section on the scope of message creation control below.
Automated creation of `medium` `nemsms` Communication when Communication with category `message` and Patient as `recipient` created	No	Yes	No	Only `medium=nemsms` possible	`message`	Same as ehealth-message (optional) When omitted, it corresponds to a match on all ehealth-message reasonCodes. See the section on the scope of message creation control below.	EpisodeOfCare reference (optional) If specified, the CommunicationRequest is specific to Communication resources referencing the EpisodeOfCare. See the section on scope of message creation control below.

Currently, no infrastructure rules (see Library Resources) cause the creation of Communication. Neither with the Patient or CareTeam as a recipient.

Controlling Message Creation with CareTeam as Recipient

The table below describes the various situations in which the automatic creation of FHIR Communication (ehealth-message) takes place. In the table, the columns following the naming pattern Element <some element name> describe what values must be used in a corresponding CommunicationRequest to control creation.

To apply for FHIR Communication with a CareTeam as the recipient, add the following to the CommunicationRequest:

recipient = CareTeam reference
category = <depending on situation>
reasonCode = <depending on situation>
episodeOfCare = <depending on situation>
basedOn = <depending on situation>
priority = <depending on situation>

Situation	Created by Default	Opt-in Supported	Opt-out Supported	Payload and Medium Overridable	Element category	Element reasonCode	Element episodeOfCare	Element basedOn	Element priority

Situation	Created by Default	Opt-in Supported	Opt-out Supported	Payload and Medium Overridable	Element category	Element reasonCode	Element episodeOfCare	Element basedOn	Element priority
Unexpected measurement submitted	No	Yes	No	No	`notification`	`UnexpectedMeasuringResolving`		ServiceRequest reference
Missing measurement determined	Yes	No	Yes	No	`notification`	`MissingMeasurementResolving`		ServiceRequest reference
Communication created by triage (or other infrastructure rules)	Yes	No	Yes	No	depends on rule	depends on rule		ServiceRequest reference	depends on rule
EpisodeOfCare created	Yes	No	Yes	No	`notification`	`EpisodeOfCareCreated`
EpisodeOfCare changed (in team, status, scheduledStatus or scheduledTeam)	Yes	No	Yes	No	`notification`	`EpisodeOfCareCareTeamChange` , `EpisodeOfCareScheduledCareTeamChange` , `EpisodeOfCareStatusChange` or `EpisodeOfCareScheduledStatusChange`	EpisodeOfCare reference
CarePlan created/changed (in careTeam, status, scheduledStatus or scheduledTeam)	Yes	No	Yes	No	`notification`	`CarePlanCreated`,`CarePlanCareTeamChange` , `CarePlanScheduledCareTeamChange` , `CarePlanStatusChange` or `CarePlanScheduledStatusChange`	EpisodeOfCare reference
Reminder about appointment	No	Yes	No	Only `payload`	`advice`	`AppointmentNotification` or `VideoAppointmentNotification`depending on appointment type	EpisodeOfCare reference (optional) If specified, the CommunicationRequest is specific to the Appointment referencing the EpisodeOfCare. See the section on the scope of message creation control below.

Scope of the Message Creation Control

Search Algorithms for CommunicationRequest applied in the Infrastructure

In general, the different microservices of the Infrastructure perform a single search for CommunicationRequest using the following search parameters:

CommunicationRequest.occurencePeriod covers current datetime at the time of the search
CommunicationRequest.status = active
CommunicationRequest.recipient matches Communication.recipient or would-be recipient (for opt-in)

In addition, search parameters are added depending on the situation as described in the sections below. For some situations, the search algorithm includes multiple searches.

The search algorithm for the situation “Reminder about the appointment”

Additional search parameters:

CommunicationRequest.meta.tag matches Communication.meta.tag (compared for co-existence tags only)

The algorithm entails multiple searches in the following order:

Search for CommunicationRequest resources where both CommunicationRequest.episodeOfCare and CommunicationRequest.reasonCode match that of the Communication. If no results are found continue with the next step.
Search for CommunicationRequest resources where no CommunicationRequest.episodeOfCare is present and CommunicationRequest.reasonCode matches that of the Communication. If no results are found continue with the next step.

The search algorithm for the situation “Automated creation of medium nemsms Communication when Communication with category message and Patient as recipient created”

For most situations, only a fixed set of reasonCodes is considered. However, a few remarks are in place for the situation “Automated creation of medium nemsms…”: When creating Communication/ehealth-message resources it is possible to specify a reasonCode, which provides the reason for the exchange of information. Using CommunicationRequest resources it is possible to opt-in for automatically created notifications about new messages. The set of reasonCodes is dynamic by nature when it comes to ehealth-message, that is, it may expand over time. Therefore it is meaningful to be able to create a CommunicationRequest, which is valid over time (for all or a specific EpisodeOfCare), and not sensitive to the introduction of new reasonCodes. Alternatively, it would be required to create new CommunicationRequest resources when introducing new reasonCodes, which would be rather cumbersome. Therefore, the semantics around CommunicationResource for ehealth-message notifications is slightly different than for other infrastructure events. For ehealth-message notifications (ie. the possibility for an automatically created ehealth-message with category=“notification”, medium=“nemsms”, and reasonCode copied from the original ehealth-message), it is possible to create a CommunicationRequest with no reasonCode provided, which will then logically match all possible ehealth-message reasonCodes (in contrast to other situations).

Additional search parameters:

CommunicationRequest.meta.tag matches Communication.meta.tag (compared for co-existence tags only)

The algorithm entails multiple searches in the following order:

Search for CommunicationRequest resources where both CommunicationRequest.episodeOfCare and CommunicationRequest.reasonCode match that of the Communication. If no results are found continue with the next step.
Search for CommunicationRequest resources where CommunicationRequest.episodeOfCare matches that of the Communication and no CommunicationRequest.reasonCode is present. If no results are found continue with the next step.
Search for CommunicationRequest resources where no CommunicationRequest.episodeOfCare is present and CommunicationRequest.reasonCode matches that of the Communication. If no results are found continue with the next step.
Search for CommunicationRequest resources where no CommunicationRequest.episodeOfCare and no CommunicationRequest.reasonCode are present. If no results are found, default behaviour applies

Search algorithm for situation EpisodeOfCare created

Additional search parameters:

CommunicationRequest.meta.tag matches Communication.meta.tag (compared for co-existence tags only)
The same additional search parameters as for the remaining situations (see below)

Search algorithm for remaining situations

Additional search parameters:

CommunicationRequest.reasonCode matches Communication.reasonCode
CommunicationRequest.category matches Communication.category

Conditional search parameters depending on the situation (see the tables above):

CommunicationRequest.episodeOfCare matches Communication.episodeOfCare
CommunicationRequest.basedOn matches Communication.basedOn

Selection algorithm

When the results of searching by the algorithms described above result in more than one CommunicationRequest, the selection of a single CommunicationRequest is performed as follows (stopping whenever a single CommunicationRequest is left):

If multiple results exist, choose the one with the most recent occurencePeriod.start
If multiple results exist choose those with doNotPerform = true (preference for message suppression)
If multiple results exist choose a random one

Overriding the Payload and/or Medium

Example of CommunicationRequest for overriding payload and medium (adding NemSMS). For overriding the default NemSMS medium, simply leave the CommunicationRequest.medium empty.

{
	"resourceType": "CommunicationRequest",
	"meta": {
		"profile": [
			"http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-communication-request"
		]
	},
	"extension": [
		{
			"url": "http://hl7.org/fhir/StructureDefinition/workflow-episodeOfCare",
			"valueReference": {
				"reference": "https://careplan.local.ehealth.sundhed.dk/fhir/EpisodeOfCare/12992"
			}
		}
	],
	"basedOn": [
		{
			"reference": "https://careplan.local.ehealth.sundhed.dk/fhir/ServiceRequest/67410"
		}
	],
	"status": "active",
	"doNotPerform": false,
	"medium": [
		{
			"coding": [
				{
					"system": "http://ehealth.sundhed.dk/cs/message-medium",
					"code": "nemsms",
					"display": "NemSMS"
				}
			]
		}
	],
	"payload": [
		{
			"contentString": "Payload override"
		}
	],
	"subject": {
		"reference": "https://patient.local.ehealth.sundhed.dk/fhir/Patient/4093"
	},
	"occurrencePeriod": {
		"start": "2023-01-04T13:02:55+01:00"
	},
	"recipient": [
		{
			"reference": "https://organization.local.ehealth.sundhed.dk/fhir/CareTeam/40365"
		}
	],
	"reasonCode": [
		{
			"coding": [
				{
					"system": "http://ehealth.sundhed.dk/cs/task-category",
					"code": "UnexpectedMeasurementResolving",
					"display": "Need resolving of why unexpected measurement was submitted"
				}
			]
		}
	]
}

Ending a Message Creation Control

To remove the effect of a CommunicationRequest, set the CommunicationRequest.status to completed. If the CommunicationRequest uses occurrencePeriod and has no occurrencePeriod.end, it would be consistent to set it to the time of completing the CommunicationRequest.

eHealth Infrastructure Wiki

Controlling Creation of Messages

Content

Introduction

Adding Control of Message Creation

Controlling Message Creation with the Patient as Recipient

Controlling Message Creation with CareTeam as Recipient

Scope of the Message Creation Control

Search Algorithms for CommunicationRequest applied in the Infrastructure

The search algorithm for the situation “Reminder about the appointment”

The search algorithm for the situation “Automated creation of medium nemsms Communication when Communication with category message and Patient as recipient created”

Search algorithm for situation EpisodeOfCare created

Search algorithm for remaining situations

Selection algorithm

Overriding the Payload and/or Medium

Ending a Message Creation Control