Retrieving Care Plans and Activities

Retrieving a CarePlan and the referenced ServiceRequest activities can be performed by a CarePlan Search on CarePlan ID with the include of ServiceRequest.

Getting an Overview of Past and Due Activities

In a CarePlan, the comprised activities are each represented as a ServiceRequest. The notion of when an activity shall happen is captured in the ServiceRequest.occurrence element corresponding to a measurement regime (for an activity that produces a measurement). Before describing an operation that provides an overview of what has happened, was supposed to happen and is expected to happen, let’s digress into the concept of resolved timing.

When an Activity is Supposed to Happen - The Notion of Resolved Timing

ServiceRequest.occurrence can be specified as one of three variations:

• occurrenceDateTime: An activity that takes place once on a specified date and time.

• occurrencePeriod: An activity that takes place once in a specified period.

• occurrenceTiming: This is for ad-hoc and recurring activities , respectively.

  • Ad-hoc - with accepted fields: Timing.repeat.count, Timing.repeat.countMax, Timing.repeat.frequency

  • Recurring event - with accepted fields: Timing.repeat.period, Timing.repeat.periodUnit, Timing.repeat.duration, Timing.repeat.durationUnit, Timing.repeat.dayOfWeek, Timing.repeat.timeOfDay

When an activity is supposed to happen varies also:

• occurrenceDateTime: Once, on the specified date and time.

• occurrencePeriod: Once, at some time between occurrencePeriod.start and, if specified, occurrencePeriod.end.

• occurrenceTiming (when specifying ad-hoc): Once or occurrenceTiming.repeat.count at some time between occurrenceTiming.repeat.boundsPeriod.start and, if specified, occurrenceTiming.repeat.boundsPeriod.end.

• occurrenceTiming (when specifying an recurring event): This depends on the Timing construct and is the scope for the description below.

Resolved timing in a recurring event Timing construct

The Timing construct can be resolved to several specific times, each referred to as a resolved timing.

The elements of Timing can be combined to represent activities that occur more frequently (such as every n minutes, every n hours, every n days or weekly) or less frequently (every n weeks, every n months, or every n years). For example:

• Every 45 minutes

• Every 8 hours

• Every day between 08:00 - 10:00

• Every day at 08:00, for a month

• Each Monday and Thursday at 08:00 and 17:00

• Every other Tuesday between 10:00-18:00

• Every three weeks Monday and Tuesday at 00:00

• Every 10 days

• Each month, over the course of a year

Timing expressions supported by the eHealth Infrastructure

The Timing construct allows for a number of complex expressions. In order to simplify, the eHealth infrastructure supports a subset described in the following. This subset is handled in the infrastructures ability to help Patients and Clinicians to follow measurement regimes with reminders, tasks on missing measurements, and when providing an overview of expected and received measurements (see get-patient-procedures further below).

The spreadsheet shown below contains examples of the Timing subset that is supported by the infrastructure.

Example Timing and Resolved Timing

“Once every Monday between 10-12 starting April 1st 2021” can be expressed with the following values in a Timing structure in occurenceTiming:

• repeat.boundsPeriod.start: 1 April 2021, 08:30:00 CET (Thursday)

• repeat.duration:2

• repeat.durationUnit:h

• repeat.frequency:1

• repeat.dayOfWeek:mon

• repeat.timeOfDay:10:00:00

• repeat.period: 1

• repeat.periodUnit: D

In a given time period, this recurring regime will result in several resolved timings. For example, looking at April 2021 this will result in four resolved timings

 🛈 Expandable section with resolved timings for Timing having timeOfDay, dayOfWeek, boundsPeriod.end and period 2 W, introduced after release FUT-I 2024.4, as a consequence of CCR0212: Ensure that timing expressions that can be created in KAM are supported

“Once every Monday between 10-12 starting April 1st 2021, ending on May 6th 2021” can be expressed with the following values in a Timing structure in occurenceTiming:

• repeat.boundsPeriod.start: 1 April 2021, 08:30:00 CET (Thursday)

• repeat.boundsPeriod.end: 6 May 2021, 08:30:00 CET

• repeat.duration:2

• repeat.durationUnit:h

• repeat.frequency:1

• repeat.dayOfWeek:mon

• repeat.timeOfDay:10:00:00

• repeat.period: 2

• repeat.periodUnit: Wk

The first resolved timing is not in the current week (March 29th - April 4th) because March 29th occurs before boundsPeriod.start. Therefore, the next Monday falls within boundsPeriod.

 🛈 Expandable section with resolved timings for Timing having multiple day of weeks, introduced after release FUT-I 2024.4, as a consequence of CCR0212: Ensure that timing expressions that can be created in KAM are supported

“Once every Monday and Thursday between 10-12 starting April 5th 2021, until April 25th 2021” can be expressed with the following values in a Timing structure in occurenceTiming:

• repeat.boundsPeriod.start: 5 April 2021, 18:00:00 CET (Monday)

• repeat.boundsPeriod.end: 25 April 2021, 11:00:00 CET (Sunday)

• repeat.duration:2

• repeat.durationUnit:h

• repeat.frequency:1

• repeat.dayOfWeek:mon, thu

• repeat.timeOfDay:10:00:00

• repeat.period: 1

• repeat.periodUnit: D

If multiple days of the week are specified, the first resolved timing will occur on any day from those specified that falls within or overlaps with the boundsPeriod. In this case, the first resolved timing is on a Thursday and not on a Monday.

 🛈 Expandable section with overlapping resolved timing, introduced after release FUT-I 2024.4, as a consequence of CCR0212: Ensure that timing expressions that can be created in KAM are supported

Overlapping resolved timings

Timing occurrences that overlap with the boundsPeriod, such as those starting before boundsPeriod.start and ending within the boundsPeriod, or starting within the boundsPeriod, but ending after boundsPeriod.end, are included after being adjusted to fit within the boundsPeriod.

For example:

“Once every Monday between 10-12 starting April 5th 2021, until April 26th 2021” can be expressed with the following values in a Timing structure in occurenceTiming:

• repeat.boundsPeriod.start: 5 April 2021, 11:00:00 CET

• repeat.boundsPeriod.end: 26 April 2021, 11:00:00 CET

• repeat.duration:2

• repeat.durationUnit:h

• repeat.frequency:1

• repeat.dayOfWeek:mon

• repeat.timeOfDay:10:00:00

Resolved timings are:

Monday 5 April, 2021 11:00 (adjusted to Timing.repeat.boundsPeriod.start) – Monday 5 April, 2021 12:00 CEST
Monday 12 April, 2021 10:00 – Monday 12 April, 2021 12:00 CEST
Monday 19 April, 2021 10:00 – Monday 19 April, 2021 12:00 CEST
Monday 26 April, 2021 10:00 – Monday 26 April 2021 11:00 CEST (adjusted to Timing.repeat.boundsPeriod.end)

• When duration is extended, we examine both backwards and forwards to retrieve all occurrences that overlap with the Timing.repeat.boundsPeriod. Overlapping occurrences are adjusted to fit entirely within Timing.repeat.boundsPeriod and will align with the bounds. (Refer to the last examples provided, for example Every 14 days at 00:00, with a duration of 5 days, in the attached file at https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/edit-v2/1661665301#Supported-timing-expressions )

Getting an Overview with get-patient-procedures

With the operation get-patient-procedures, a user can retrieve an overview of what measurements a Patient has submitted, was supposed to submit, and is expected to submit for a given period of time.

The operation get-patient-procedures can be used to see what is planned in the future. For example during the next week. It can also be used to see what was submitted in the past, and if it matches what was planned and if any measurements are still missing. The operation can evaluate past submissions for the last 30 days. Setting the start date to earlier than 30 days ago will result in an error.

EpisodeOfCare, CarePlan, and ServiceRequest resources examined

The operation get-patient-procedures is based on an examination of the following resources:

• Examined EpisodeOfCare:

  • EpisodeOfCare.patient must match the Patient reference given as a parameter

  • Either the EpisodeOfCare.id is included in the list of EpisodeOfCare references given as a possible parameter, or

  • EpisodeOfCare.diagnosis.condition.code (at least one if multiple Coding provided) is included in the list of condition Coding given as a possible parameter

• Examined CarePlan:

  • CarePlan.workflow-episodeOfCare must reference one of the examined EpisodeOfCare

• Examined ServiceRequest:

  • Must be referenced from examined CarePlan

The operation get-patient-procedures uses effective status to determine whether a ServiceRequest is active at a given time. As described in https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/2524872705/Using+EpisodeOfCare+CarePlan+s+and+ServiceRequest+s#Determining-the-ServiceRequest-Effective-Status, the effective status of a ServiceRequest is determined by examining the ServiceRequest alongside the status of the referenced EpisodeOfCare and the CarePlan that references the ServiceRequest. A ServiceRequest is determined to be effectively active if all three resources (EpisodeOfCare, CarePlan and ServiceRequest) have status active at the given time. Effective status can be determined both historically and for periods in the future, by using the statusHistory and statusSchedule elements of the resources.

get-patient-procedures produces output for each resolved timing of the ServiceRequest, where the ServiceRequest is determined to have effective status active during the resolved timing. The period for which the ServiceRequest has effective status active shall have at least partial overlap, that is, it does not have to completely overlap the resolved timing. Resolved timings which originate from the same ServiceRequest are evaluated separately regarding the effective status of the ServiceRequest.

Extra measurements

The operation get-patient-procedures can be called with an optional parameter: ‘extra=true’ that results in additional returned rows for ServiceRequests where the Patient may submit extra measurements outside the resolved timing slots.

An ‘extra’ row will be returned if there is an overlap between the search period and the measurement regime period. Resolved/unresolved measurement regimes can result in returned ‘extra’ rows while Ad hoc measurement regimes cannot (since the Patient may already submit at any time for this type).

When an ‘extra’ measurement is submitted, it shall be marked accordingly by setting the measurement (Observation, QuestionnaireResponse or Media) resolvedTiming.type element to extra. These 'extra' measurements will not be counted in TotalSubmitted and SubmittedTimely in the output of get-patient-procedures.

In addition to the above-mentioned criteria, the ServiceRequest must also have effective status which is either active or on-hold at any given time during the search period, to be added to the output as extra. Unlike the usual way of determining effective status, the EpisodeOfCare, CarePlan and ServiceRequest are not required to have the same status at the same time as long as the status is either active or on-hold. An output row for extra measurement can occur even if the ServiceRequest did not result in any Resolved/unresolved measurement row.

How to interpret output from get-patient-procedures

The output contains rows (encoded in parameters) for each matching (see get-patient-procedures) and active ServiceRequest with resolved timings overlapping with the requested period.

• CarePlan: Reference to the CarePlan that the ServiceRequest belongs to.

• ServiceRequest: Reference to the ServiceRequest.

• ServiceRequestVersionId: The version of the ServiceRequest (version specified at the time of submit-measurement or the current version (for expected activities)).

• Activity: Description of the planned activity.

• ResolvedTimingStart: A planned start time for the activity in the requested period.

• ResolvedTimingEnd: A planned end time for the activity in the requested period. May be identical to the start if no duration is specified in the measurement regime.

• TotalSubmitted: The number of measurements already submitted for this ServiceRequest and resolved timing.

• SubmittedTimely: The number of measurements where the measurement time matches the resolved timing.

• TimingType:

  • Resolved: a measurement regime that is supported by the infrastructure and where resolved timing and requested number of measurements can be calculated.

  • Unresolved: a measurement regime that the infrastructure cannot resolve to resolved timing. Resolved Timing Start, and end submitted timely and Occurrences requested will be empty.

  • Adhoc: A ServiceRequest without a measurement regime or a measurement regime stating ad-hoc.

  • Extra: The Patient may submit extra measurements for the ServiceRequest outside the resolved timing slots.

• OccurencesRequested: Expected number of measurements.

If measurements are submitted for older versions of a ServiceRequest, then a row will be added with the number of submitted measurements. Furthermore, for older versions of ServiceRequests, the occurrenceRequested-value is set based on that exact serviceRequestVersion.

Example output:

• Item_1: A weight ServiceRequest with a single resolved timing and 1 measurement planned. Currently, none submitted

• Item_2: An old version of an oxygen saturation ServiceRequest of type Unresolved. One measurement was submitted for this version, but the infrastructure cannot determine if it was timely or how many were requested.

• Item_3: Current version of an oxygen saturation ServiceRequest where the measurement regime has been updated so it can be resolved. 2 measurements were requested and already submitted, but one of them was not on time.

• Item_4: Same ServiceRequest as item_3, but a different resolved time. 2 measurements are requested but none submitted yet.

• Item_5: A height ServiceRequest with an ad-hoc measurement regime. One measurement was submitted.

• item_6: An old version of a blood pressure ServiceRequest of type Resolved. One measurement was requested and one measurement was submitted, however not timely according to the ResolvedTiming on the measurement itself.

• Item_7: An old version of a blood pressure ServiceRequest of type Resolved. One measurement was requested and one measurement was submitted timely according to the ResolvedTiming on the measurement itself.

• Item_8: Current version of a blood pressure ServiceRequest updated with new ResolvedTimingStart and ResolvedTimingEnd on the measurement regime. One measurement was submitted for this version, however not on time.

• Item_9: Row indicating that the Patient may submit extra measurements for the ServiceRequest outside the resolved timing slots.

Preparing and Submitting Measurements

See Preparing and Submitting Measurements .