Publication Build: This will be filled in by the publication tooling

Guidance

Design Decisions

These design decisions have guided the mapping process. 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.

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

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

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

• ECP provides data to CPRS.
• vx130 extracts data that is used in the Clinical Data Warehouse and to support integration with Millennium.
• VPR extracts data for use in the VA Data Integration Framework (VDIF) and for exchange in VHIE and JHIE.
• 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.

• Persistence Facade model Write capabilities

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 cases where a semantic match does not include a syntactic match.
   • 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 “focal” FHIR resource. If no such property exists, this guidance may propose maps to “ancillary” FHIR resources.
   • Recommended
     • 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.
     • 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.
       • Create one Observation profile for each of these elements, or a general Observation profile with a value set for the codes? Each code may have a different value set for resulting values. These differences might be expressed as FHIR “slices,” but this would require some kind of bundle to collect and assert the slices.
     • 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. [Or Data Absent Reason extension in Provenance: is there a criterion for this decision?]
     • DetectedIssue resources are designed to support drug checks and other decision support functions.
   • 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 more significant than data persistence. This is not the case for this project.
4. 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.

Terminology mapping approach

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

Note: if there is no standard translation, then no separate .coding element should be instantiated.

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.

Extensions

Maps will use existing Core elements where possible, expanding the solution space where necessary as follows:

1. US Core, with extensions
2. FHIR Core
3. FHIR Core extensions (including preadopt R5 elements)
4. VA extensions

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.

FHIR design decisons

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

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

Terminology System Identifiers

Codes used in VistA must assert code systems, which also require URIs. These hierarchies, however, are not specific to FHIR:

http://va.gov/terminology/vistaDefinedTerms
http://va.gov/terminology/vistaDefinedElements

These subhierarchies support definition of artifacts specific to VistA fields. E.g., vaccines not given are recorded in VistA file 9000010.11, field .01, so the codes in that field have this generated system uri:

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

Similarly, elements in VistA that are to be represented as coded Observations need a code and system for the question. In these cases, we use VistA itself as the system, the field number as the code:

 "code": {
     {
        "system": "http://va.gov/terminology/vistaDefinedElements",
        "code": "2-.301",
		"display": "SERVICE CONNECTED?"
      }
  },

Identifiers

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 can describe 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 system boundaries, such as VistA implementations.

Each VistA implementation has an assigned facility code, corresponding to the "Sta3n" of its primary medical center. Interfaces that consolidate data from across VAMCs use these codes 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:

"identifier" : [{
	"system" : "urn:oid:2.16.840.1.113883.4.349.508",
	"value" : "12345"
}],

Note that the VAST (VHA Site Tracking) department, charged by VHA DIRECTIVE 1044, maintains a list of OIDs for VA locations, and the OIDs for VAMCs can be used to identify VistA instances. 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" : [{
	"system" : "urn:oid:2.16.840.1.113883.4.349.7.508.430",
	"value" : "12345"
}],

We do not currently know of a service that can provide up-to-date VAST assignments based on facility code. We also observe that we need these OIDs to identify systems, whereas the VAST OIDs are defined as locations of care. For these reasons, we recommend using the first approach rather than the VAST approach, at least in the interim.

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 and the VAMC Sta3n as 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" } ''' And Locations are part of their VAMC: ''' "partOf": { "identifier": "urn:oid:2.16.840.1.113883.4.349.508", "display": "Atlanta VA Health Care System" } '''

Other identifiers

For other VistA-assigned identifiers, the system must specify both the scope of the system assigning the identifier (the VAMC, identified by Sta3n) and the semantic scope of the thing identified. 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" : [{
	"system" : "http://va.gov/identifiers/508/52-.01",
	"value" : "3603899"
}],

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 names "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/