PKB is currently performing a gap analysis between our own entity definitions in our Data Model and those of the FHIR data model. This is highlighting some discrepancies that we will need to resolve before the corresponding data can be returned from the FHIR API, and hence any discrepancies are blockers for the GDE timeline view project.
This document captures specifically the discrepancies for the Appointment entity, along with the proposed changes to resolve those discrepancies.
This document is not intended to be a full specification. It does not capture all the required mappings for the Appointment entity, just those that are needed for the timeline view.
Double square bracket notation is used to refer to the PKB Data Model. For example, [[Appointment]] is used to specifically refer to PKB’s concept of an appointment entity, as defined here.
The proposed changes are divided into 2 parts: the changes required for GDE (which require more immediate agreement) and other changes we might make in the future but which do not block development of the FHIR API.
The table below shows the proposed end state. Entries in red are different from our current behaviour. Below the table each difference is addressed in more detail.
Currently: PKB already has [[Appointment.Type]] in our Data Model. However, we only store the type code and type coding system.
For data received via HL7, we populate the type code from SCH-8.1 and the type coding system from SCH-8.3.
For manually created appointments, we populate the type code from the value entered into the single input field.
Proposed change (GDE): Upgrade the HL7 handling so that full coding information is stored from SCH-8. This would be implemented using the same approach we have taken previously for allergies, diagnoses and medications. Specifically, we would upgrade [[Appointment.Type]] to be of type CodeableConcept, allowing all 6 components of SCH-8 to be stored, rather than just the 2 we currently capture.
Proposed change (future): Upgrade the UI to display the full information stored in [[Appointment.Type]] since it will now be a full CodeableConcept. Reconsider best approach for allowing manual entry of this field, if permitted at all.
Notes: The FHIR HL7 v2 mappings do not seem to cover all the fields we are interested in. Suggest we continue by simply mapping the HL7 v2 “Appointment type” directly to the FHIR “appointmentType”. The datatypes and field names match.
Currently: PKB already has [[Appointment.Subject]] in our Data Model. However, this is just a single textual value, not a full CodeableConcept. In addition, we have never clarified whether semantically this value is:
A one line description of the appointment
The reason for the appointment
This is causing confusion, in particular because FHIR treats these as 2 different things (description, reason). Our current handling:
For data received via HL7, we populate the value from SCH-7.2.
For manually created appointments, we also accept a single textual value (currently labelled in the UI as “Name of appointment”).
Proposed change (GDE):
Confirm the “Subject” value as meaning “Reason”.
Rename “Subject” to “Reason” in our Data Model.
Upgrade [[Appointment.Reason]] to be of type CodeableConcept
Upgrade the HL7 handling so that all 6 components of SCH-7 are captured, rather than just SCH-7.2. This would be implemented using the same approach we have taken previously for allergies, diagnoses and medications.
Proposed change (future): Upgrade the UI to display the full information stored in [[Appointment.Reason]] since it will now be a full CodeableConcept. Reconsider best approach for allowing manual entry of this field, if permitted at all.
Notes: As for appointmentType. In addition, note that by deciding to confirm the existing “Subject” values as semantically meaning “Reason” values, there will be no one line description value available for any existing appointments.
Currently: PKB does not currently track a one-line description for Appointments. We do have [[Appointment.Subject]], and this will store values entered into the “Name of appointment” field in the web UI, but as above this value is proposed to be clarified as mapping to Appointment.reason, which in FHIR is semantically distinct from Appointment.description.
Proposed change (GDE):
Introduce a new attribute into our Data Model called [[Appointment.Description]]
Modify the “Name of appointment” field in the web UI to be labelled as “Description” and have it populate [[Appointment.Description]] rather than [[Appointment.Subject]] (Subject will be renamed to Reason)
Proposed change (future): There is no obvious HL7 v2 mapping into this description. Currently, the SCH-7.2 (reason text) is used to populate Subject, and this value is what is shown in the Appointment list (typically Appointment lists are the primary use of a one line “description” field). However, by formally splitting the description from the reason, we will no longer have any mapping from an SIU message into Appointment.description. Options:
Design the UI such that description can remain optional without causing a poor user experience.
Expand the HL7 API to accept this value. For example, we could accept a dedicated NTE segment, identified by a specific code value in NTE-4 to indicate the corresponding NTE-3 should be used for the appointment description.
Leave the HL7 API unmodified, but apply some conditional logic to try to automatically determine a best-fit value.
Notes: We should consider what to show in appointment listings for data which does not have a description (this will include all data up to the point of implementing this change). Suggest this can be handled by careful UI design.
Currently: PKB already tracks a multi-line free text value. This value is currently stored in [[Appointment.Description]].
Proposed change (GDE):
Rename this to be [[Appointment.Comment]]
Proposed change (future): None.
Notes: None.
Specific feedback on the following points would be helpful and is welcomed from customers:
Do you have any use cases that would be impeded by the proposed mappings?
Do you typically have coded data sets for an appointment reason in SCH-7? If yes, what sort of information does it contain, e.g. a specific clinical code relating to the service being performed? Or a more general administrative category such as “check-up”?
Do you typically have coded data sets for an appointment type in SCH-8? If yes, what sort of information does it contain, e.g. a specific clinical code relating to the service being performed? Or a more general administrative category such as “check-up”?
Do you typically use additional codes relating to either the service or service category? Where do these appear in your SIU messages?
What information would you typically expect to see in a one-line description of an appointment, as might appear in an appointment list? Where would that information be included typically in your SIU messages? Is it in one specific field or could it reasonably be derived from multiple fields in a predetermined order?