US Veterans Health Administration FHIR Map Set Implementation Guide - Downloaded Version 1.9.0 See the Directory of published versions

FHIR Design Patterns

Overview

We document foundational assumptions and design decisions that we have developed over time. They are documented here to clarify why the maps were done the way they were and to support consensus across the enterprise.

Principles

This guide follows two key principles:

1. The purpose of FHIR is to support interoperability. Every effort should be made to ensure that data will be comprehensible to receivers, including, to the extent possible, receivers without “out-of-band” communication channels to settle integration issues.

   Implications Where possible, FHIR properties should be used in preference to extensions. Tactics for doing so, in order:

   • Using FHIR Core properties
   • Using commonly recognized extensions that already exist
   • Using elements from future releases of FHIR reproduced as extensions
   • Creating new extensions and publishing them to support external comprehension

Extensions, where necessary, should include full documentation. A publicly available Implementation Guide, identified with a URL, is the best way to expose these designs; other tools may be necessary in the interim.

1. Health record semantics must be preserved. If FHIR is unable to support required patient information, extensions must be used.

   Implication There will be cases where required FHIR values will be included in addition to more precise values in VA extensions; viz., status values.

Maps will prioritize target elements in this order:

1. US Core, with extensions
2. FHIR Core
3. FHIR Core extensions (including FHIR Cross-Version Extensions package for FHIR R4 from FHIR R5)
4. VA extensions

Profiling Concept

International Core FHIR resources are under-specified to support a variety of communities of support. Large communities can constrain those resources with profiles to support more specific expectations. This profiling can be repeated any number of times to constrain data to increasingly narrow expectations for increasingly specialized uses.

This Implementation Guide (IG) follows the US Core. The design supports the ability of implementers to create more specialized guides that will inherit the mappings from this guide without further effort.

Version

These maps follow FHIR US Core R5 (https://hl7.org/fhir/us/core/STU5.0.1/) where possible. Where profiles follow US Core guidance, they assert that conformance in the meta.profile element.

Migration to later versions will be undertaken per the specification of the enterprise FHIR version by the CIDMO Knowledge-Based Systems, Standards & Terminology division.

Environment

At this time, FHIR is used to surface record data in various interfaces; it is not used to write patient data into the VistA record.

The data is not stored in the FHIR information model; rather, VistA data is collected into a FHIR "facade" for presentation to partners. This IG serves to coordinate various implementation teams' assumptions about how that should be done consistently.

There are several interfaces providing access to patient record data, primarily held in VistA.

• CPRS pulls data from VistA via RPCs, primarily.
• vx130 extracts data that is used in the Clinical Data Warehouse and to support integration with Millennium.
• Clinical Data Warehouse (CDW) is an analysis tool, but it supports basic patient-view cases.
• Virtual Patient Record (VPR) extracts data for use in the VA Data Integration Framework (VDIF) and for exchange in VHIE and JHIE.
• Veterans Data Integration and Federation Enterprise Platform (VDIF, or VDIF-EP) is an Intersystems-supported integration hub
• Health Data Repository (HDR)
• VIA

Rather than provide maps to each of these tools, we map VistA elements to FHIR. Implementers taking data from any of these interfaces should work with the interface owner to determine how that interface exposes the elements. Our maps do document interface element names where interfaces provide this document in a computable form.

Mapping approach

Element maps will use the following approaches, in order:

1. Where FHIR has fields that support VistA semantics directly, they will be mapped.
   • E.g., ADVERSE REACTION REPORTING - DATE/TIME OF EVENT (OBSERVATION) (120.85-.01) => AllergyIntolerance.reaction.onset
2. Terminology maps will support lexical matches where possible and semantic matches where appropriate.
   • E.g., Allergy mechanisms “A” and “P” (“allergy” and “pharmacologic”) are mapped to FHIR “allergy” and “intolerance” (“Allergy” and “Intolerance”).
3. First choice will be properties belonging to the domain FHIR resource (e.g., AllergyIntolerance, Patient). If no such property exists in the domain resource, this guidance may propose maps to “ancillary” FHIR resources.
   • Recommended
     • Observations capture information about patients and devices. They support rich metadata and complex nested structures. Several patient properties (including those concerning service history) imply nesting.
       • The Military Service History IG uses this approach for service episodes.
     • Provenance resources are designed for capturing record management data; they are recommended where VistA captures this information, but the core FHIR resources do not. Provenance requires both a time and an agent; if one of these is not available, an extension on the base resource must be used. Note that support for Provenance in the ecosystem is thin.
     • DetectedIssue resources are designed to support drug checks and other decision support functions.
     • Encounters can be used to provide common context for different resources, when, e.g., a VistA record tracks patient location.
       • E.g., a VistA order contains information about the clinic or hospital where a medication was ordered (NON-VERIFIED ORDERS-APPOINTMENT DATE/TIME). FHIR MedicationRequest has no such property. It may, however, include a related Encounter resource, and this resource may record a location.

• Not recommended - The AuditEvent resource is designed for capturing record management data. Unlike Provenance, it can capture events that do not modify data, and its use cases are typically assumed to involve security and other system administration duties. - Questionnaires are typically to solicit information, and they can be used when the form of presentation is more significant than data persistence. This is not the case for this project.
  1. Where FHIR fields do not support VistA semantics, extensions are recommended.
  • Where available, we will adopt existing extensions.
    • E.g., us-core-race
  • Where no extensions exist, and future releases do (viz., for AMPL maps using STU3), we will pre-adopt properties.
    • E.g., 52.41-25 (PENDING OUTPATIENT ORDERS - PRIORITY) to http://hl7.org/fhir/4.0/StructureDefinition/extension-MedicationOrder.priority
  • Where neither of these is possible, we will create VA extensions
    • E.g., PATIENT ALLERGIES - OBSERVED/HISTORICAL (120.8-6) => http://va.gov/fhir/StructureDefinition/allergyintolerance-reactionObservationMode

Containment and reference

Maps don't specify whether a referenced resource should be instantiated independently or as contained. It is expected that most resources will be independent. The less information a resource contains (e.g., a location name with no other information), or the less likely it is to be queried for independently (e.g., a service location in a patient record api), the more sense it may make to embed that information directly in the primary resource.

Identifiers

Uniform Resource Identifiers

Different implementers may implement a variety of endpoints; these are subject to tactical constraints and are not addressed here. Definitional artifacts, however, require consistent definitional uris. For these artifacts, we define the VA FHIR definitional endpoint:

http://va.gov/fhir/

This root supports definition canonical URIs for VA FHIR artifacts, e.g.,

http://va.gov/fhir/StructureDefinition/MyAllergyintoleranceProfile
http://va.gov/fhir/ConceptMap/CMVFallergyActive
http://va.gov/fhir/ValueSet/VSVallergyActive

These terms use the CM and VS abbreviations for ConceptMap and ValueSet, and the VF abbreviation for VistA-to-FHIR in the ConceptMap pattern.

Their status as "canonical" (or their form) may vary as the VA standards hosting architecture evolves.

CDA compatibility

Where VA CDA implemenations use OIDs as identifiers, we follow that pattern to facilitate integration between CDA and FHIR.

VHIE uses the VA OID originally created to identify the VA for NHIN (2.16.840.1.113883.4.349) as author and custodian ID, and as scope (root) for document ID, patient ID, and clinic IDs. This will be used likewise in FHIR for these purposes: to identify the VA as an organization and to scope patient Integration Control Numbers (ICNs - the VA enterprise medical record identifier).

A second OID appears in VHIE CDA documents: 2.16.840.1.113883.6.233. This OID was registered for the VA itself, but it is used in VHIE as the code system for codes defined in VHAT. We we will also use this OID for this purpose.

Identifier systems

The FHIR identifier data type specifies a property for the 'system' - the assigner of the identifier and therefore the context in which the identifier is meaningful. The systems in the following patterns vary for this reason.

Note that in cases where the value is an OID or a URL, the system would be "urn:ietf:rfc:3986", but it is not required.

Information system

Each VistA implementation has an assigned facility code, corresponding to the "Station" of its primary medical center. (There are cases where one "station" supports multiple Medical Centers.) Interfaces that consolidate data from across the VA use these 3-digit integers to distinguish records that may have non-unique local identifiers in their respective VistA implementations:

• VIA as the {assigningFacility} element
• VPR as the code attribute within {facility} element
• CDW as the 'sta3n' column

The simplest way these codes can be used to define namespaces within the VA namespace is by adding a node to the base OID, which can then scope the (otherwise not reliably unique) identifier:

Patients

Patient identifers are VA ICNs scoped by the VA OID:

"identifier" : [{
	"system" : "urn:oid:2.16.840.1.113883.4.349",
	"value" : "1015128742V345328"
}],

This pattern can be used for any identifier unique in the scope of the VA enterprise.

We do not at this time have access to Oracle Health or DoD EDI-PI identifiers.

Organizations

This OID identifies the VA as an organization:

"identifier" : [{
	"value" : "urn:oid:2.16.840.1.113883.4.349"
}],

It can also be used as a root to scope elements defined by the VA at the enterprise level.

VA clinics are an example. Because VHIE had used this OID to scope clinic identifiers, we do the same, with a type indicating this is the Station Number (from file 4, field 99):

"identifier" : [{
	"type": {"text" : "STATION NUMBER"},
  "system" : "urn:oid:2.16.840.1.113883.4.349",
  "value" : "757GC"
}],

VAST (VHA Site Tracking)

Note that the VAST (VHA Site Tracking) department, charged by VHA DIRECTIVE 1044, maintains a list of OIDs for VA locations. These OIDs are usually produced by concatenating the base OID with the VISN, the sta3n, and the index of the row of the spreadsheet in which they appear, but in 62 of 1737 rows of that spreadsheet, values are hard-coded, presumably due to prior assignment.

Example: VAMC 508 is in VISN 7, and it appears in row 430 of the spreadsheet:

"identifier" : [{
	"value" : "urn:oid:2.16.840.1.113883.4.349.7.508.430"
}],

Our use cases to date do not require location identification, as distinct from service provider, so our maps do not include these identifiers at this time.

Organizational Parts

Plan-Net lists partOf as a must-support property for organizations and locations. It does not specify whether this relationship is intended to represent a global container (e.g., the VA), a proximal container (e.g., the building in which a clinic is located), or some intermediate value (e.g., VAMC or VISN). Until we have business owners with specific requirements, we adopt the service (the Department of Veterans Affairs) as the target of Organization.partOf. We have no requirements for the target of Location.partOf. We have no requirement at this time to instantiate target resources for these references.

Organizations are part of the VA:

  "partOf": {
    "identifier": "urn:oid:2.16.840.1.113883.4.349",
    "display": "Department of Veterans Affairs"
  }

Records

Records reproduced from VistA as FHIR resources may pull information from several files, but all from one implementation of VistA ("sta3n"). The whole resource, then can assert a provenance of that system by identifying it in the resource's meta.source property: http://va.gov/fhir/sid/sta3n/{sta3n}.

  "meta": {
    "source": "http://va.gov/fhir/sid/sta3n/520"
  },

More specifically, any item represented as a row in a database can be identified by its primary key, and VistA objects are often represented by the key of the file, the internal entry number (IEN). In order for such an identifier to be unambiguous, we need to know both the file and the station. As a result, any time an IEN is used as an identifier, both file and station are required in the identifier system: http://va.gov/fhir/sid/sta3n/{sta3n}/{file}. This allergy identifer tells you both the VistA instance and file that define it:

"identifier" : [{
  "system" : "http://va.gov/fhir/sid/sta3n/520/120.8",
  "value" : "18457"
}],

For other (non-IEN) VistA-assigned identifiers, the system must specify not only the station and file, but the field. Following the terminology system approach assigned below, the file and field numbers are sufficient to provide this scope.

E.g., for a Prescription (file 52) Rx# (field .01) under the Atlanta VAMC (508):

"identifier" : [{
 	"type": {"text" : ""}
	"system" : "http://va.gov/fhir/sid/508/52-.01",
	"value" : "3603899"
}],

Summary

Terminology

Terminology mapping approach

Elements of type CodeableConcept should always include the VistA text in the .text property. No .coding element should be populated unless there is a code: don't repeat the .text in .coding.display. That is for the standard-defined display text.

We follow the guidance below for situations defined by the FHIR constraint (across the top) and VistA content (left column).

Terminology design in VistA

Note that in some cases, the VistA file structure is quite complex, and we do not reproduce it exhaustively. Ethnicity, for instance, is field 2-6 ETHNICITY INFORMATION, which points to file 2.06 ETHNICITY INFORMATION, which contains field .01 ETHNICITY INFORMATION, which points to file 10.2 ETHNICITY, which contains the values. If this guide is ever enhanced to support automated transformations, it will be necessary to articulate all of those steps, but for human readers it suffices to map 2-6 to the FHIR property – in this case, the complex extension property Patient.extension[http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity].extension[ombCategory].

There are also cases where the VistA property contains a VA unique identifier (VUID) - a code from the Veterans Health Administration Terminology (VHAT), which interfaces such as CPRS and SDA then de-reference using a service such as Collaborative Terminology Tooling Data Management (CTTDM). This service design is also outside the scope of this guide.

Terminology System Identifiers

Where elements use codes from standard systems, those systems should be identified in .system with their canonical URIs.

Codes with defined systems and published system URIs will use those URIs. Note that we use the OID 2.16.840.1.113883.6.233 for VHAT codes (VUIDs), as described above.

Codes defined in VistA must also assert code systems, which also require URIs. We define two conventions, one for coded values in VistA and one for encoding questions from VistA.

VistA elements used as question or property codes in Observation.code will have the form {fileNumber-fieldNumber}. Their system is http://va.gov/fhir/CodeSystem/vistaDefinedElements.

  "code": {
    "coding": [
      {
        "system": "http://va.gov/fhir/CodeSystem/vistaDefinedElements",
        "code": "2-.361",
        "display": "PRIMARY ELIGIBILITY CODE"
      }
    ]
  },

Observation.valueCodeableConcept codes and other coded values will have a system defined by the same {fileNumber-fieldNumber} pattern, this time in the system rather than the value.

"valueCodeableConcept": {
    "coding": [
    {
      "system": "http://va.gov/fhir/CodeSystem/VistA2-.361",
      "code": "NSC",
      "display": "NON-SERVICE CONNECTED"      }
    ]
  },

This is an example of a pointer to code file: this element points to file 8 (ELIGIBILITY CODE), which is a code file. Other configurations include VistA files with elements of type "SET", which constrains values to an list enumerated in the dictionary. This is the case for Immunization reactions:

 "valueCodeableConcept": {
    "coding": [
     {
        "system": "http://va.gov/fhir/CodeSystem/VistA9000010.11-.06",
        "display": "RASH OR ITCHING"
        "code": "5"
      }
    ],
    "text": "RASH OR ITCHING"
  },

Sometimes, the code is from a lookup table, and the table itself is the system: this allows the system to be used in any number of fields calling the table. Immunization, for instance, uses a CVX code table. When the CVX code is looked up, the system is the national CVX system, i.e., "http://hl7.org/fhir/sid/cvx". But that table also contains VA-defined values for historically recorded values for which the precise CVX is not known (e.g., "INFLUENZA (HISTORICAL)") and for vaccines not given (e.g., "INFLUENZA REFUSED/DECLINED (HISTORICAL)"). This value will be mapped to the CVX (required for immunization in US Core, but with the non-done status), and it will also contain the value from that file:

 "vaccineCode": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/sid/cvx",
        "code": "88",
    "display": "influenza virus vaccine, unspecified formulation"
      },
     {
        "system": "http://va.gov/fhir/CodeSystem/VistA9999999.14",
        "code": "REFUSED FLU (HISTORICAL)"
      }
    ],
    "text": "REFUSED FLU (HISTORICAL)"
  },

In a previous edition of this IG, a desire to create URIs to support use in any context, not specific to FHIR, led to the specification of these paths for VistA-defined elements and terms.

http://va.gov/fhir/CodeSystem//VistA{file}-{field} alias: http://va.gov/terminology/vistaDefinedTerms/{file}-{field}
http://va.gov/fhir/CodeSystem/vistaDefinedElements alias: http://va.gov/terminology/vistaDefinedElements

Experience with the publication machinery makes it preferable to follow the convention, gradually becoming a standard.

Summary

| Terminology | code | system | | —– | —– | —– | | Standard | {as specified by standard} | {as specified by standard} | | VistA Enterprise | {as specified by VistA} | http://va.gov/fhir/CodeSystem/{file}-{field} | | VistA Local | {as specified by instance} | http://va.gov/fhir/CodeSystem/{Sta3n}Sta3n{file}-{field} |

Extensions

As noted above, extensions will be created only when all other design options have failed.

VA extensions will be necessary for more specialized use cases where VA processes require data not anticipated by FHIR core to be in the 80% of most common elements. Where it is necessary to create new extensions to express VA-defined semantics, the extension name should represent the context of the requirement, rather than any particular implementation technology. E.g., the VA pharmacy-specific prescription status, which is more granular than the standard FHIR status, is named medicationrequest-pharmacyOrderStatus.

Observation patterns

The FHIR Observation resource contains a code property and a value property. This supports question/answer patterns such as Labs or Vitals, where the answer may be a quantity that is meaningless without knowing what is being quantified, which is stated in the code.

Sometimes, a VistA field answers a question that is implicit in a field name, such as "AGENT ORANGE EXPOS. INDICATED?" In these cases, we take the field name as the question code. There are many elements in the Patient file (2) that fit this description. To define the codeSystem for these cases, see Terminology System Identifiers, above.

VistA also contains a set of values called Health Factors that support extending the semantic model of VistA by adding new codes to a file rather than new elements to a data model. Some of these factors serve as question codes that can be paired with answers, such as "packs smoked per day". In this case, we follow the question/answer pattern as above, though we prefer to map the Health Factor to a standard, such as SNOMED CT. (In these cases, the axis would be Obervable Entity, or possibly Evaluation Procedure).

For many Health Factors, the factor entails a complete semantic statement, independent of a question or context. These codes can be mapped to SNOMED CT findings or situations. US Core provides a pattern for recording findings in FHIR by assigning a generic "category" question that can accomodate these finding codes without affecting their meaning. The Smoking Status profile demonstrates this pattern: it uses a broad LOINC "smoking status" question code, and it specifies values from the SNOMED CT finding axis, such as "smoker" or "former smoker". Those findings mean the same thing whether they are accompanied by that question code or not.

Codings and CodeableConcepts

• Codings SHALL always contain the source VistA Term or Entry alongside the required FHIR Coding. Terminology Mapping is defined in mapParameters and results in ValueSet and ConceptMaps.

ValueSets and ConceptMaps

• ValueSets are named "VS{termmapname}" for the (required) FHIR values
• ValueSets are named "VS{termmapname}-vista" for the VistA values
• ConceptMaps are named "CM{termmapname}"

Slices

• Use slicenames from the profiles
• All slices defined by the mappings are prefixed with "va-"

StructureDefinition (Profiles)

All elements with a VistA mapping …

• … are marked must-support S
• … slices are added when used
• … extensions are added when used
• … optionally have 1 or more CDW mappings
• … optionally have 1 or more VPR mappings
• … can have a terminology mapping expressed as a ValueSet and a ConceptMap
• … can have a transform (e.g. string to boolean) expressed as a ValueSet and a ConceptMap using the 11179-permitted-value-conceptmap extension
• … reference types are constrained when defined as part of the mappings
• … fixed value unless there is a case

StructureDefinition (VA Extensions)

Defined in this IG using namespace http://va.gov/fhir/StructureDefinition/