fhir-transformation-engine

# FHIR Transformer Specification

## Introduction

This document describes a portable transformation engine 
that can be used to convert different kinds of source 
material into a FHIR repository. 

## Components 

The conversion engine has the following parts:

* Javascript Engine 
* FHIR Mapping Language Engine
* Liquid Template Engine (processes JSON, XML, HTML or Markdown) 
* Terminology and other conversion services 


## Conversion process

When the host application or context initiates a conversion, the 
engine calls (via configuration) a javascript routine with this
signature:

    function convert(engine, object, api) {
    }

Parameters:

* _engine_: an object that makes engine services available to the script - see below for documentation
* _object_: the source object being converted - see below for documentation and specifications
* _api_: provides direct access to the FHIR database, authorised as a appropriate. See below for documentation
* There is no return value 

The convert function is responsible for the logic of breaking up the content of the 
incoming object, matching it to existing resources, and either merging updated information into
the existing resources, or creating new resources. 

The javascript code has to coordinate the overall conversion process, and handling the 
matching and committing against the FHIR repository. Actual mapping from the source content
to FHIR resources can be done in several different ways:

* Just writing the code in javscript - this is the least efficient way to express the conversion, but it is the most rebust
* Using the FHIR Mapping language - this is an efficient way to perform complex conversions, but not very good at managing merging the update with an existing resource
* Using a liquid template (or a set of them) - this is the easiest way to perform simple conversions, but is not useable for managing merging

The source uses the engine routines to launch non-js conversions.

## Engine

This object exposes the following routines:

### convertUri

    function convertUri(value, type)

Converts between FHIR URIs and v3 OIDs or V2 table 0396 code

Parameters:
* _value_: The existing identifier namespace to convert from
* _type_:  The type to return - one of uri, oid, or v2 
* _returns_: The specifed value if available, else null

This look up is based on naming systems and/or magically known comparisons

### convertQty

    function convertQty(value, srcUnit, tgtUnit);

Converts a quantity from one unit to another (using UCUM)

* _srcCode_: The value to translate from (a decimal; can be a string if the string implicity converts to a number)
* _srcUnit_: The UCUM unit for the value
* _tgtUnit_:  The UCUM unit to return the value in
* _returns_: The converted value as a decimal, or null if there is none

Conversion is done consistently with the definitions in UCUM

### convertCode

    function convertCode(srcCode, srcSystem, tgtSystem); 

Parameters:
* _srcCode_: The code to translate from
* _srcSystem_: The URI of the system to translate from
* _tgtSystem_:  The URI of the system to translate to
* _returns_: The code in the target system, or null if there is none

This is a call to the [$translate operation](http://hl7.org/fhir/conceptmap-operation-translate.html).


## FHIR API Object

### read 

    function read(type, id)

Performs a [read interaction](http://hl7.org/fhir/http.html#read). Parameters:
* _type_: The type of resource to search
* _id_: the id of the resource to fetch
* _returns_: an array of resources, in the order returned by the server

### search

    function search(type, params)

Performs a [search interaction](http://hl7.org/fhir/http.html#search). Parameters:
* _type_: The type of resource to fetch 
* _params_: the parameters string for the search
* _returns_: an array of resources, in the order returned by the server

### create

    function create(resource)

Performs a [create interaction](http://hl7.org/fhir/http.html#create). Parameters:
* _resource_: The FHIR Resource to commit to the server
* _returns_: the created resource, with id populated

### update

    function update(resource)

Performs a [create interaction](http://hl7.org/fhir/http.html#create). Parameters:
* _resource_: The FHIR Resource to commit to the server, with id populated
* _returns_: the created resource, with id populated

### delete

    function delete(type, id)

Performs a [create interaction](http://hl7.org/fhir/http.html#create). Parameters:
* _type_: The type of resource to delete
* _id_: the id of the resource to delete
* _returns_: a boolean if the resource was deleted


## Source Object 

An object that represents the incoming content that is to be processed 
into the FHIR repository 

The following types are currently defined:
* HL7 V2 Object
* CDA Document

## HL7 V2 Message

This is an object that has properties and functions as defined in
the [V2 model in the FHIRPath spec](http://hl7.org/fhirpath/2018Sep/index.html#hl7v2)

## CDA Document

This is an object that has properties and functions as defined in
the [the CDA logical Model](https://build.fhir.org/ig/HL7/fhir-cda/)