This section describes how PKB processes Time Stamp (TS) values in HL7 messages.

Accuracy

PKB supports time components up to and including millisecond accuracy. The time component representing ten-thousandths of a second may be provided, but will be ignored. Note that the ten-thousandths component will be truncated; the remaining time components will not be rounded.

HL7 permits a TS value to be of varying accuracy. For example, it is syntactically valid to provide just the date component (e.g. 20160701) or to provide both the date and time components (e.g. 20160701130506).

If no information has been provided then the value will be treated as absent. If at least the year has been provided then defaults will be applied to any omitted components. Omitted date components will be defaulted to one, omitted time components will be defaulted to zero. However, incomplete components will return an error. For example, it is not permitted to provide a one-digit hour value.

PKB does not store the original accuracy in which a TS value was provided. So a value that had a component defaulted to zero is currently indistinguishable from one that explicitly provided zero.

The table below provides a few illustrative examples.

Time zones and offsets

TS values are treated by PKB as communicating an absolute point in time. We interpret the value you provide as being a fixed point in time, and persist that fixed point in time to the database. As such, every TS value is interpreted within a time zone (or having an offset from UTC). The time zone we use is determined according to the following hierarchy:

• UTC offset provided with value. If the TS value includes an offset from UTC (as permitted by the HL7 specification in +/-ZZZZ format) then PKB will interpret the TS value as being in the specified offset from UTC. PKB recommends that a UTC offset is provided with each value. The meaning is clear, unambiguous and prevents any confusion.

• UTC offset provided with MSH-7. In accordance with the HL7 specification, if an offset from UTC is not provided with a TS value, but an offset from UTC was provided with MSH-7, then the offset in MSH-7 will be used as a default for the message. Although this option is permitted by the HL7 specification, we do not recommend the approach, because it is unlikely that the offset in which the message was sent is the same offset that should be applied to all TS values within the message. By way of example, consider an S12 message sent before daylight savings come into effect, for an appointment scheduled to occur after daylight savings have come into effect.

• Interface default time zone. It is possible to configure an interface default time zone in which PKB will process any TS values that neither include an offset from UTC, nor were provided in a message for which MSH-7 had an offset from UTC. Note: it is only possible to configure a time zone (e.g. "Europe/London"), not an offset from UTC. This can be an easy way to get a connection working, but the limitation of this approach is that your HL7 messages will no longer be self-describing. That is, it is not possible to know how PKB will interpret a TS value within a given message unless you also know the currently configured interface default time zone. This is not a problem per se, but you should be aware that this makes auditing and debugging slightly more difficult. An interface default time zone is not configured for your interface unless specifically agreed. There is no default interface default time zone. Note also that the default is applied at the level of the PKB Organisation, it is not possible to configure different defaults for different PKB Teams.

• Global default time zone. If none of the 3 options above apply, the TS value is assumed to have been provided in UTC.

The benefit of storing TS values as absolute points in time is that they can subsequently be localised to the viewer's time zone. For example, when viewing an appointment in the web interface, the time will be localised to the time zone currently selected by the viewer.

PKB does not store the original time zone/offset in which a TS value is provided. As such, it is not possible to request to see a TS value in the original localisation. Please get in touch if this is a feature you think would be helpful.

Date and time of birth

PID-7 is the HL7 location for providing the date and time of birth of a patient. It is a little unusual, so we've given it a section of its own here.

Since PID-7 is a TS value, it is capable of representing an explicit point in time. This point in time is the patient's time of birth, but PKB does not store this value. There is no "time of birth" attribute on a [[Patient]].

However, PKB does capture a "date of birth". A patient's date of birth is the name of the date on which the patient was born according to the time zone in which they were born. Counter-intuitively, knowing the absolute point in time at which a patient is born is not sufficient to deduce their date of birth. By way of example, imagine you know a person is born right now, as you are reading this. You cannot know their birthday unless you also know where they were born (or more accurately, in which time zone they were born) since the name of the date is dependent upon their location relative to the international date line.

In order to handle this, PKB will extract the date component provided in PID-7 and store this as the "date of birth". The "date of birth" value is the literal value that was provided in PID-7, regardless of which time zone/offset would apply to the full PID-7 value, and ignoring any time components (if provided).

PKB customer sites: deploy | developer | information governance | procurement | manual

© Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.

This API specification and design is licensed under a Creative Commons Attribution 4.0 International License.