Skip to main content
Version: v0.2.1

Translate a coded field through a value map

Some v2 coded fields hold a code from an HL7 table that the guide maps to a different FHIR code system: route of administration (Table 0162) to the v3 route codes, for example. The message assembly applies those maps for you. To apply one yourself, to a coded element you read from a message, call toFhirCodeableConceptVia with the element and the map.

Translate a code​

import { serializeResource } from "@cosyte/fhir";
import { ROUTE_VALUE_MAP, toFhirCodeableConceptVia } from "@cosyte/transform";

const { value, issues } = toFhirCodeableConceptVia({ identifier: "IM" }, ROUTE_VALUE_MAP);

value === undefined ? undefined : JSON.parse(serializeResource(value)); // => { coding: [{ system: "http://terminology.hl7.org/CodeSystem/v2-0162", code: "IM" }, { system: "http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration", code: "IM", display: "Injection, intramuscular" }] }
issues; // => []

The translation is additive: the original code stays first, in its v2 table's system, and the FHIR code is added after it. Nothing the sender wrote is replaced.

Know which maps ship​

Mapv2 tableField
ROUTE_VALUE_MAP0162RXR-1 route
SITE_VALUE_MAP0550RXR-2 site
APPOINTMENT_TYPE_VALUE_MAP0277SCH-8 appointment type
SUBSTITUTION_VALUE_MAP0161RXO-9 substitution
ALLERGY_CATEGORY_VALUE_MAP0127AL1-2, to AllergyIntolerance.category
ALLERGY_TYPE_VALUE_MAP0127AL1-2, to AllergyIntolerance.type
ALLERGY_CRITICALITY_VALUE_MAP0128AL1-4, to AllergyIntolerance.criticality
ALLERGY_ORIGINAL_CATEGORY_VALUE_MAP0127AL1-2, the original code in the alternate-codes extension
ALLERGY_ORIGINAL_CRITICALITY_VALUE_MAP0128AL1-4, the original code in the alternate-codes extension

Each was transcribed from the guide's published ConceptMap and checked against it. OBR-5 priority is translated during assembly through SERVICE_REQUEST_PRIORITY_MAP, the guide's Table 0485 map, kept as a lookup table rather than a map you pass here.

Handle a code the map leaves out​

A code the guide's map has no target for is not moved to a neighbor. The raw coding is kept, with no system, and the result carries TRANSFORM_CODE_UNMAPPED:

import { ROUTE_VALUE_MAP, toFhirCodeableConceptVia } from "@cosyte/transform";

const { issues } = toFhirCodeableConceptVia({ identifier: "XYZ" }, ROUTE_VALUE_MAP);

issues.map((i) => `${i.code} ${i.v2Location}`); // => ["TRANSFORM_CODE_UNMAPPED CWE.1"]

Handle a code from another coding system​

The map applies only when the element's coding system (CWE-3) is empty or names the map's own table (HL70162 or 0162 for routes). A code sent under any other system is a different code, even when it is spelled the same, so it is carried as sent and not translated:

import { createNamingSystem, ROUTE_VALUE_MAP, toFhirCodeableConceptVia } from "@cosyte/transform";

const { issues } = toFhirCodeableConceptVia(
  { identifier: "IM", nameOfCodingSystem: "99LOCAL" },
  ROUTE_VALUE_MAP,
  { namingSystem: createNamingSystem() },
);

issues.map((i) => i.code); // => ["TRANSFORM_CODE_SYSTEM_UNRESOLVED"]

Seed the naming system with 99LOCAL's URI (Resolve assigning authorities) and the coding gets its system, still untranslated.

What is not translated​

Fields the guide maps into SNOMED CT (RXR-4 method, SCH-7 reason) are carried as they arrive: SNOMED CT content is not bundled. Fields the guide publishes no value map for (TXA-2 document type, RXA-5 vaccine code) are carried as they arrive too.

Reference​