Mapping from KITH XML to FHIR (R4)

Introduction

Pasientens Prøvesvar receives diagnostic reports in the KITH Labsvar XML format (helsedirektoratet.no). These are mapped to the FHIR R4 format (hl7.org), and made available via the Pasientens Prøvesvar API. This document describes the mapping between the two formats.

How to Read This Document

This document contains a number of tables showing how values are mapped from KITH to FHIR. Most mappings are straight-forward and are categorized by where they are mapped from in KITH:

• Mapping table for Message
• Mapping table for ServReport
• Mapping table for ServReq
• Mapping table for Patient (including InfItem)
• Mapping table for AnalysedSubject
• Mapping table for ResultItem
• Mapping table for HCP

Other mappings are less straight-forward and are documented with extra details:

• Handling of Requester, ServProvider, RelServProv, ResponsibleHcp
• Non-straightforward date mappings
• Mapping to DiagnosticReport.category (main subject area)
• Mapping to Observation.category (subject area)
• Mapping to DiagnosticReport.status
• Mapping to Observation.status
• Mapping to Observation.meta.tag
• Summary of FHIR extensions used

Special Notation

Special notation is used to refer to a single array element or a subset of an array when there can be more than one element present: ResourceName.PropertyName[filter]. This notation by itself does not describe how many such items may exist, but the cardinality of mapped items is the same as in KITH unless otherwise specified.

Examples:

• DiagnosticReport.identifier[system="MsgId"]
  • Refers to any Identifier in the DiagnosticReport.identifier array whose system property equals MsgId.
• ServiceRequest.extension[url="*/nilar-payment-category"]
  • Refers to any Extension in the ServiceRequest.extension array whose url property ends with /nilar-payment-category.
• DiagnosticReport.extension[url="*/nilar-comment" AND valueCodeableConcept exists]
  • Refers to any Extension in the DiagnosticReport.extension array whose url property ends with /nilar-comment and which has a valueCodeableConcept property.

Feedback

If you have feedback on this document, it can be sent to nilar@nhn.no.

KITH Labsvar v1.3 and v1.4

The mapping is based off of KITH Labsvar v1.4, though we do accept reports using v1.3 as well. The changes from v1.3 to v1.4 are minor and in most cases of no consequence, though in some cases the report is rejected:

Links

• See Pasientens Prøvesvar's FHIR profile (github.io) for details on the FHIR objects exposed by the API.
• See Endpoints for details on the available API endpoints.
• See API Examples for further examles.

Mapping Overview

Message

ServReport

DiagnosticReport.extension[
  url="*/nilar-comment" AND
  valueAnnotation exists]

DiagnosticReport.extension[
  url="*/nilar-comment" AND
  valueCodeableConcept exists]

ServReq

ServiceRequest
  .extension[url="*/nilar-payment-category"]

ServiceRequest
  .identifier[system="ServReqIdByServProvider"]

ServiceRequest
  .extension[url="*/nilar-reservation"]

ServReq.ReasonAsText
  .Heading

ServiceRequest.reasonCode
  .coding
  [system="urn:oid:2.16.578.1.12.4.1.1.8231"]

ServReq.ReasonAsText
  .TextResultValue

ServReq.ReasonAsText
  .TextCode

ServiceRequest.reasonCode
  .coding[system=(other)]

serviceRequest.extension[url="*/nilar-comment"]
  .valueCodeableConcept
  .coding
  [system="urn:oid:2.16.578.1.12.4.1.1.8234"]

ServReq.Comment
.TextResultValue

serviceRequest.extension[url="*/nilar-comment"]
  .valueCodeableConcept.text

serviceRequest.extension[url="*/nilar-comment"]
  .valueCodeableConcept
  .coding[system=(other)]

Patient

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-inf-item-description"]

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-comment"]

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-inf-item-coded-description"]

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-inf-item-type"]

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-inf-item-start"]

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-inf-item-end"]

DiagnosticReport.extension[url="*/nilar-inf-item"]
  .extension[url="*/nilar-inf-item-org-date"]

AnalysedSubject

AnalysedSubject.CollectedSample
  .CollectedDate

AnalysedSubject.CollectedSample
  .CollectorComment

Specimen.collection.extention[
  url="*/nilar-comment" AND
  valueAnnotation exists]

AnalysedSubject.CollectedSample
  .CollectorCommentCoded

Specimen.collection.extention[
  url="*/nilar-comment" AND
  valueCodeableConcept exists]

Specimen.collection
  .extension[url="*/nilar-study-product-type"]

AnalysedSubject.CollectedStudyProduct
  .ProducedDate

AnalysedSubject.CollectedStudyProduct
  .RefRelatedProd

Specimen.collection
  .extension[url="*/nilar-study-product-ref"]

Specimen.extension[url="*/nilar-pretreatment"]
  .valueCodeableConcept.coding

AnalysedSubject.Pretreatment
  .TextResultValue

Specimen.extension[url="*/nilar-pretreatment"]
  .valueCodeableConcept.text

ResultItem

Observation.valueCodeableConcept
  .coding[system="urn:oid:2.16.578.1.12.4.1.1.8243"]

ResultItem.TextResult
  .TextResultValue

Observation.valueCodeableConcept
.coding[system=(other)]

Observation.valueCodeableConcept
  .coding[system="http://unitsofmeasure.org"]

ResultItem.NumResult
  .ArithmeticComp

ResultItem.NumResult
  .NumResultValue.V

ResultItem.NumResult
  .NumResultValue.U

Observation
  .extension[url="*/nilar-investigation-date"]

Observation
  .extension[url="*/nilar-related-observation-ref"]

Observation
  .extension[url="*/nilar-status-changed-date"]

Observation
  .extension[url="*/nilar-medical-validation-date"]

Health Care Providers

The KITH Labsvar document may include various health care providers, each with their own role. Their mappings to FHIR follow a fallback strategy which may merge info on two such entities into a single PractitionerRole, (for instance if one is missing an organization):

Fallback Strategy Table

*) The above FHIR properties are references only. See using includes on how to include the referenced PractitionerRole objects.

Mapped Properties

HCP

Date Mappings

There are several dates in both KITH Labsvar and in FHIR. Most are mapped where it is deemed natural, but especially effectiveDateTime is derived in a somewhat complex fashion.

AnalysedSubject.CollectedSample
  .CollectedDate

AnalysedSubject.CollectedStudyProduct
  .ProducedDate

Remarks on effectiveDateTime

• Observation.effectiveDateTime may be mapped to from multiple candidates:
  • Primary candidates are CollectedDate or ProducedDate under any AnalysedSubject referenced by this ResultItem or by any ResultItem sharing the same top-level ResultItem as this one. The oldest date is picked if it exists.
  • If there exists exactly one AnalysedSubject in the report, its CollectedDate or ProducedDate are primary candidates even if the AnalysedSubject isn't referenced by the ResultItem.
  • Secondary candidates are InvDate of this ResultItem or of any ResultItem sharing the same top-level ResultItem as this one. The oldest date is picked if it exists.
  • If all above dates are missing, ServReport.IssueDate is used.
• DiagnosticReport.effectiveDateTime is mapped to from the oldest Observation.effectiveDateTime.
  • If no Observations exist (e.g. cancelled report), ServReport.IssueDate is used.

Mapping to DiagnosticReport.category (Main Subject Area)

DiagnosticReport.category is the main subject area of the entire report and can have the following possible three values from code system 8202 (helsedirektoratet.no):

• BLD - Bildediagnostikk (Imaging diagnostics)
• LAB - Laboratoriemedisin (Laboratory medicine)
• PAT - Patologi (Pathology)

The value is not explicitly present in the KITH Labsvar XML, so it is derived based on the value of ServReport.MsgDescr.V. If it cannot be determined because AN - Annet (other) is used (not recommended), Message.Type.V is a backup source. See table below:

Mapping to Observation.category (Subject Area)

Observation.category is the subject area of the specific result and can have values from code system 8202 (helsedirektoratet.no). An attempt is made to determine the appropriate category based on what is found in ResultItem.Investigation.Id:

• If ResultItem.Investigation.Id.S = 7280 (or the equivalent OID), then Id.V is an NLK code (helsedirektoratet.no):
  • Observation.category will be set to what is under primært fagområde (primary subject area) associated with the specific NLK code at Id.V.
• If ResultItem.Investigation.Id.S = 7270 (or the equivalent OID), then Id.V is an NCRP code (helsedirektoratet.no):
  • Observation.category will be set if Id.V has 6 characters: It's set to NUK - Nukleærmedisin if the 6th and last character is N or T, and RAD - Radiologi otherwise.
• If ResultItem.Investigation.Id.S = 7210 or 8219 (or their equivalent OID):
  • Observation.category will be set to PAT - Patologi.

Mapping to DiagnosticReport.status

DiagnosticReport.status is set to one of the codes from the DiagnosticReportStatus (hl7.org) value set.

Pasientens Prøvevsar uses the following subset of the DiagnosticReportStatus codes:

Mapping Table

DiagnosticReport.status is derived from a combination of the following properties in the KITH Labsvar XML:

• Message.ServReport.ServType: Code system 7309 (helsedirektoratet.no)
• Message.ServReport.Status: Code system 7306 (helsedirektoratet.no)

Mapping to Observation.status

Observation.status is set to one of the codes from the ObservationStatus (hl7.org) value set.

Pasientens Prøvevsar uses the following subset of the ObservationStatus codes:

Mapping Table

Observation.status is derived from a combination of the following properties in the KITH Labsvar XML:

• ResultItem.ServType: Code system 8270 (helsedirektoratet.no)
• ResultItem.StatusInvestigation: Code system 8245 (helsedirektoratet.no)

The table contains Norwegian because the defined display names for the given code values are in Norwegian.

Mapping to Observation.meta.tag

To make searching easier, top-level Observations (i.e. Observations that are referenced directly under DiagnosticReport.result) will have tags added to them from the following places:

• ResultItem.TextResult.Heading for the corresponding ResultItem or for any nested ResultItems under it.
• ResultItem.TextResult.TextCode for the corresponding ResultItem or for any nested ResultItems under it.
• ResultItem.Investigation.Id for the corresponding ResultItem or for any nested ResultItems under it.

In other words, a copy of the above codes from any (possibly nested) ResultItem will be available at Observation.meta.tag on the associated top-level Observation. This is in addition to their primary mapping (see the mapping table for ResultItem).

Summary of FHIR Extensions

Various FHIR resources may have an extension property containing a number of Extension objects. Pasientens Prøvesvar uses such extensions where the FHIR resource doesn't have another property available to map to. All our extensions have an url property on the form "http://nhn.no/fhir/nilar/StructureDefinition/<extension name>", where <extension name> is a string of lowercase letters and dashes. Here is a list of extensions used by Pasientens Prøvesvar:

Note: The nilar-comment extension may have different data types (Annotation or CodeableConcept or string) depending on where it is mapped from.

Note: The nilar-inf-item extension itself has no value property and simply serves as a grouping of related extensions nested under it.

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

CollectedSample
  .CollectorCommentCoded

Reference
  (DiagnosticReport)

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

DiagnosticReport.extension
  [url="*/nilar-inf-item"]

CollectedStudyProduct
  .RefRelatedProd