HL7 Value Transformers

Transformers convert a raw HL7 string value into a typed or structured output. They are used in two contexts:

• Automatically by the transformation registry, based on the resolved HL7 field type (e.g. NM → toNumber)
• Explicitly via the pipe syntax in template expressions: {{PID-8|toGender}}

Transformers can be chained — they are applied left to right, each receiving the output of the previous one: {{PID-3|toNumber|default:0}}

Template Transformers

These transformers are available in the pipe syntax ({{field|transformer}}).

toGender / hl7Gender

Maps an HL7 gender code to a FHIR AdministrativeGender value.

Input	Output
M	male
F	female
O, A	other
U, N	unknown
(unknown)	unknown

Example: {{PID-8|toGender}}

note

hl7Gender is a legacy alias for toGender and will be removed in a future version. Use toGender in new configurations.

toDateTime / hl7DateTime

Converts an HL7 timestamp (YYYYMMDDHHMMSS) to an ISO 8601 instant. Partial timestamps are supported — missing time components default to 00.

Input	Output
20240115143000	2024-01-15T14:30:00Z
20240115	2024-01-15T00:00:00Z
Value shorter than 8 characters	undefined

Example: {{PID-7|toDateTime}}

note

hl7DateTime is a legacy alias for toDateTime and will be removed in a future version.

note

Due to the Dynamic Type Detection this will also work: {{PID-7}}

toDate / hl7Date

Converts an HL7 date or timestamp to a FHIR date string (YYYY-MM-DD). Any time component is stripped.

Input	Output
20240115	2024-01-15
20240115143000	2024-01-15

Example: {{PID-7|toDate}}

note

hl7Date is a legacy alias for toDate and will be removed in a future version.

toPatientClass / hl7PatientClass

Maps an HL7 patient class code to a FHIR v3-ActCode value.

Input	Output	Meaning
I, R, B	IMP	Inpatient
O, C, N, U	AMB	Ambulatory
E	EMER	Emergency
P	PRENC	Pre-admission
(unknown)	AMB	Fallback

Example: {{PV1-2|toPatientClass}}

note

hl7PatientClass is a legacy alias for toPatientClass and will be removed in a future version.

toBoolean

Converts common truthy/falsy string representations to a native boolean.

Input	Output
Y, YES, TRUE, 1, T	true
N, NO, FALSE, 0, F	false
(anything else)	undefined

Example: {{OBX-5|toBoolean}}

toNumber

Parses a string to a number. Handles both . and , as decimal separators.

Input	Output
"98.6"	98.6
"98,6"	98.6
"" / " "	undefined
Non-numeric string	undefined

Example: {{OBX-5|toNumber}}

uppercase / lowercase / trim

Simple string utilities.

Transformer	Effect
uppercase	Converts the value to upper case
lowercase	Converts the value to lower case
trim	Removes leading and trailing whitespace

Example: {{PID-3|trim|uppercase}}

default

Returns a fallback value when the input is null, undefined, or an empty string. The fallback is passed as an argument after :.

Example: {{PID-3|default:unknown}} - {{OBX-5|toNumber|default:0}}

If no argument is given, "unknown" is used as the default fallback.

Chaining with default

Place default at the end of the chain so it only kicks in when all previous transformers returned nothing.

Internal-only Transformers

The following transformers are used internally by the transformation registry and are not available in the pipe syntax.

toHumanName

Parses an HL7 XPN field into a FHIR HumanName object.

Format: familyName^givenName^secondName^suffix^prefix
Result: "Smith^John^A^Jr^Dr" → { family: "Smith", given: ["John", "A"], suffix: ["Jr"], prefix: ["Dr"] }

note

Use {{PID-5}} without a pipe transformer — the registry applies toHumanName automatically when the field type is XPN. To map individual sub-fields instead, use explicit paths: {{PID-5-1}}, {{PID-5-2}}.

toAddress

Parses an HL7 XAD field into a FHIR Address object.

Format: street^other^city^state^postalCode^country
Result: "123 Main St^^Springfield^IL^62701^USA" → { line: ["123 Main St"], city: "Springfield", state: "IL", postalCode: "62701", country: "USA" }

note

Use {{PID-11}} to get the whole object, or map sub-fields individually: {{PID-11-3}} for city, {{PID-11-4}} for postal code, etc.

toCoded

Parses an HL7 CE/CWE field into a FHIR coding object.

Format: code^display^system
Result: "LA6576-8^Positive^http://loinc.org" → { code: "LA6576-8", display: "Positive", system: "http://loinc.org" }

toPhone

Strips all non-numeric characters from a phone number, keeping only digits and a leading +.
Result: "(0800) 123-456" → "0800123456"

toTime

Converts an HL7 time (HHMMSS) to HH:MM:SS. Pads missing seconds with 00.
Result: "101030" → "10:10:30" "1010" → "10:10:00"

sanitizeString

Trims whitespace and removes all ASCII control characters (Unicode \u0000–\u001F). Always runs as the first step in the internal pipeline before type-specific transformers.