Janus - Local Development build (v0.1.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Mapping service

Introduction

This service uses the Mapping Engine to facilitate data conversion between various formats commonly used in the healthcare sector. This solution makes it possible to easily transform information from XML, JSON, CSV, or HL7v2 files into standard formats such as FHIR® or CSV. This makes it easier to connect and integrate applications, ensuring smooth and consistent data flow between systems.

Supported formats, profiles and transformation

The Mapping Engine supports a variety of input and output formats to accommodate diverse integration needs in healthcare systems.

Formats

• FHIR R4: Healthcare interoperability standard for exchanging healthcare information electronically

⚠️ Note: Currently, only conversions to FHIR R4 format are fully supported. Support for FHIR R5 is planned for the future.

• HL7v2: Legacy healthcare messaging standard widely used for clinical data exchange
• JSON: Lightweight data interchange format built on key-value pairs and nested structures
• CSV: Simple text format that stores tabular data in comma-separated fields
• XML: Markup language that defines rules for encoding documents in a format both human and machine-readable

Profiles

The Mapping Engine supports transformations to specific implementation profiles, allowing data to be formatted according to specialized requirements beyond the base standards.

⚠️ Note: While the Mapping Engine can transform data to match structures required by various profiles, it does not perform validation against these profile specifications. The responsibility for ensuring compliance with profile constraints lies with the implementer. Additional validation tools should be used to verify that transformed data conforms to target specifications.

Supported transformation

The following table indicates which data formats are supported as input sources and/or transformation targets by the Mapping Engine:

Format	Input	Target
FHIR R4	✓	✓
HL7v2	✓	✗
JSON	✓	✓
CSV	✓	✓
XML	✓	✗

Supported Datatype Transformations

The Mapping Engine implements a subset of the FHIR StructureMap transform operations to facilitate data conversion between different formats and types. These transformations are particularly useful when source and target data structures require type conversion.

Create Operation

The create transform operation instantiates new FHIR elements or resources.

Operation	Parameters	Result Type	Description
create	Type name (optional)	Varies based on created type	Creates a new instance of the specified type. If no type is specified, attempts to determine type from context. For resources, performs additional initialization

Copy Operation

The copy transform operation simply copies a value from source to target without modification.

Operation	Parameters	Result Type	Description
copy	Source value	Same as source	Copies the source value exactly to the target without type conversion

Evaluate Operation

The evaluate operation evaluates FHIRPath expressions to transform data.

Operation	Parameters	Result Type	Description
evaluate	1. Context object 2. FHIRPath expression	Varies based on expression	Execute the supplied FHIRPath expression and use the value returned by that

Truncate Operation

The truncate operation limits a string to a specified length.

Operation	Parameters	Result Type	Description
truncate	1. Source string 2. Maximum length	StringType	Truncates the source string to the specified maximum length and returns as a FHIR StringType

Cast Operations

The cast transform operation is a key function that converts source values to specific target types. When using StructureMap rules, the cast operation can be invoked to ensure that data is properly typed according to the target requirements.

The following table details the supported cast operations in the current implementation:

Source Type	Target Types	Description
String	string, text	Converts input to a FHIR StringType
String	id	Converts input to a FHIR IdType
String	integer	Converts string representation of a number to a FHIR IntegerType
String	decimal	Converts string representation of a decimal number to a FHIR DecimalType
String	boolean	Converts string representation of a boolean ("true"/"false") to a FHIR BooleanType
String	date	Converts string representation of a date to a FHIR DateType
String	dateTime	Converts string representation of a datetime to a FHIR DateTimeType
String	time	Converts string representation of a time to a FHIR TimeType

Append Operations

The append transform operation combines multiple string values into a single concatenated string.

The following table details how the append operation functions:

Operation	Parameters	Result Type	Description
append	Multiple string parameters	StringType	Concatenates all parameter strings into a single string and returns a FHIR StringType

Translate Operation

The translate operation performs concept translation using ConceptMaps.

Operation	Parameters	Result Type	Description
translate	1. Source coding/code 2. ConceptMap URL 3. Field to return (optional)	Coding or specific field	Translates a code using the specified ConceptMap and returns either the entire Coding or a specific field if requested

Reference Operations

The following table details the operations for handling references between resources:

Operation	Parameters	Result Type	Description
reference	Resource (as parameter)	Reference	Creates a FHIR Reference to the provided resource using its type and id (generates UUID if no id present)

UUID Operation

The uuid operation generates a random UUID for use as an identifier.

Operation	Parameters	Result Type	Description
uuid	None	IdType	Generates a random UUID as a FHIR IdType

Pointer Operation

The pointer operation creates a URI reference to a resource.

Operation	Parameters	Result Type	Description
pointer	Resource (as parameter)	UriType	Creates a URI reference to the provided resource in the format "urn:uuid:[id]"

Coding Operations

The Mapping Engine supports two operations for creating coded concepts:

Operation	Parameters	Result Type	Description
cc	1. System URI 2. Code 3. Display (optional)	CodeableConcept	Creates a FHIR CodeableConcept containing a Coding with the specified system, code, and optional display
c	1. System URI 2. Code 3. Display (optional)	Coding	Creates a FHIR Coding with the specified system, code, and optional display

Date Operations

The dateOp transform operation provides specialized date parsing and formatting capabilities. This operation allows for handling various date formats and converting them to appropriate FHIR date types.

The following table details the supported date operations in the current implementation:

Operation	Parameters	Result Type	Description
dateOp	Source date string, Format pattern	DateTimeType	First attempts to parse as a datetime value using the specified format pattern (e.g., "yyyy-MM-dd HH:mm:ss"). If successful, returns a FHIR DateTimeType.
dateOp	Source date string, Format pattern	DateType	If datetime parsing fails, attempts to parse as a date-only value using the same format pattern (e.g., "yyyy-MM-dd"). If successful, returns a FHIR DateType.