Retrieving Care Plans and Activities

Retrieving a CarePlan and the referenced ServiceRequest activities can be performed by a CarePlan Search on CarePlan id with 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.

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

• occurenceTiming: This is for recurring activities. For example a measurement that should be performed each Monday at 10:00.

The Timing structure can express recurrence in several different ways. There are no hard restrictions on how fields can be used and combined. However there is a recommended subset that the infrastructure understands and can help Patients and Clinicians to follow with reminders, alarms and overview of expected and received measurements.

This spreadsheet contains examples of the timing subset that is supported by the infrastructure.

All recurring regimes should have a Timing.repeat.boundsPeriod specifying the period where the regime is active.

A recurring regime can be resolved to a number of specific times where the activity should be performed. Each of these is referred to as a resolved timing.

Week-based measurement regimes

This type of regime is recommended for any activity that happens at least once pr. week.

Examples:

• Every day between 08:00 - 10:00

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

Week-based measurement regimes consist of a combination of dayOfWeek, timeOfDay, duration, frequency:

• timeOfDay is optional. If it is not specified then the time component of boundPeriod.start is used instead.

• duration is optional. If not specifed then the regime expects activities to be performed at a specific time. 

• frequency is mandatory and specifies the number of times the activity should be performed for each resolved timing.

Frequency based measurement regimes

This type of regime is recommended for activities that happen less frequently than once per week. It can be used to specify more frequent activities, but it is recommended to use the week-based regimes instead in these cases.

Examples:

• Once every 2 weeks

• Once every 10 days

Frequency based measurement regimes consist of: frequency, period, periodUnit, boundsperiod.start, duration.

• period, periodUnit are mandatory and specify the period between each resolved timing.

• frequency is mandatory and specifies the number of times the activity should be performed for each resolved timing.

Each resolved timing will match the pattern: boundsperiod.start + n * period * periodUnit

There are a number of pitfalls to be aware of for the frequency based measurement regime. Especially if the periodUnit is specified in days or hours.

• The boundsPeriod.start determines the starting point. This can make it complex to calculate the exact resolved timing. Example: “Every 10 days counting from January 1st 2020” Should I do this activity on April 27th 2021?

• If the periodUnit is specified in days, each resolved timing will fall on different week-days unless the period is a multiple of 7

• If the periodUnit is specified in hours, each resolved timing will fall on different times unless the period is a divisor or multiple of 24

• If the periodUnit is specified in hours, then timezone and/or summertime may affect the resolved timings.

Example Timing and Resolved Timing

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

• repeat.boundsPeriod.start: 1 January 2020, 08:30:00 CET

• repeat.duration:2

• repeat.durationUnit:h

• repeat.frequency:1

• repeat.dayOfWeek:mon

• repeat.timeOfDay:10:00:00

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

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 examination of the following resources:

• Examined EpisodeOfCare:

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

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

  • EpisodeOfCare.diagnosis.condition.code (at least one if multiple Coding provided) is included in the list of condition Coding given as 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 in regards to 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 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, in order 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 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 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 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, 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.

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 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 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 .