External Data Maps

SanteDB 3.0 allows for developers to specify external data maps which can be used in their project to import data that is alien to SanteDB. These definition files are located in the alien/ directory of your applet.

In Visual Studio Code, you can use an XML editing plugin and bind the ForeignDataMap.xsd schema to your file to obtain auto-complete information via the `

<?xml-model href="../.ref/schema/ForeignDataMap.xsd" 
   type="application/xml" 
   schematypens="http://www.w3.org/2001/XMLSchema"?>

General Structure

A single data map definition may contain multiple <map> elements. These maps generate a transaction bundle which is translated and imported. The overall structure of a map file is illustrated below.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="../.ref/schema/ForeignDataMap.xsd" type="application/xml" 
     schematypens="http://www.w3.org/2001/XMLSchema"?>
<ForeignDataMap xmlns="http://santedb.org/import">
    <id>00000000-0000-0000-0000-000000000000</id>
    <name>My Foreign Data Mapping</name>
    <description>This does some things with a file</description>
    <creationTime />
    <maps>
        <map>
            <resource type="Type1"/>
                <when>
                    <source />
                    <value />
                </when>
                <maps>
                    <map required="true|false" replace="true|false" whenTargetMissing="Error|Warning|Information">
                        <source>Field_Name</source>
                        <when>
                           <value/>
                        </when>
                        <fixed when="?">Value to fix</fixed>
                        <transform transformer="name">
                            <args />
                        </transform>
                        <target>targetHDSIPath</target>
                    </map>
                </maps>
                <existing>
                    <where>id=$output.id</where>
                </existing>
            </resource>
            <resource type="Type2" />
        </map>
    </maps>
</ForeignDataMap>

Resource Maps

A single <map> element can contain one or more resources. Each <map> is translated into a transaction bundle, meaning that if any of the translated resources have an issue with persistence then none of the resources are committed.

The resource map has three instructions:

• when - Which is evaluated against the input data to determine whether the resource map applies to the data (for example - if creating a Place to support a birthplace)

• maps - Which are a series of mappings which translate the input data to an output structure.

• existing - Which is used to query the database to determine whether the data already exists in the database.

For example, consider an input source in CSV such as:

id,fname,gname,age,mother,father,town,province,birth_facility_type,birth_facility
"A1023","SMITH","BOB",34,"SALLY SMITH","ROGER SMITH","Sometown","Ontario","HOSPITAL", "Good Hospital"

Conditional Resource Mapping

The <when> is used to control whether the mapping instructions are applied to the input data. The when structure is evaluated against an input field with one or more values. For example to create a Place when the value in birth_facility_type is HOSPITAL or CLINIC:

<resource type="Place">
    <when>
        <source>birth_facility_type</source>
        <value>HOSPITAL</value>
        <value>CLINIC</value>
    </when>

Field Mapping

Fields are mapped against a source, a fixed value, or a programmatic transform.

Simple Mapping

The simplest mapping is when a value in a source field is directly copied to a target. The target is expressed as an HDSI path. For example, to map the fname field in the input to the given name:

<resource type="Patient">
    ...
    <maps>
       <map required="true" replace="true">
           <source>fname</source>
           <target>name[OfficialRecord].component[Given].value</target>
       </map>
       ...

Fixed Value

A map can also be sourced from a fixed value - this is useful when you want to set a fixed value to a field such as a typeCode, or an address part. For example, to fix the country of the patient's address to CA:

<resource type="Patient">
    ...
    <maps>
       <map>
          <fixed>CA</fixed>
          <target>address[HomeAddress].component[Country].value</target>
       </map>

Fixed values can also be assigned based on a when condition. For example, to select a different class code based on a number in a source column:

<maps>
    <map>
        <source>birth_facility_type</source>
        <fixed when="HOSPITAL">fc....</fixed>
        <fixed when"CLINIC">ea.....</fixed>
        <target>typeComcept</target>
    </map>

Transforming Values

Values can be transformed from their source into other forms using one of the built-in transformers avaialble. Transformed values are applied against their input value, for example - to look-up the birthplace based on the facility name only when the type of a HOSPITAL or CLINIC:

<map>
   <source>birth_facility</source>
   <when>
      <source>birth_facility_type</source>
      <value>HOSPITAL</value>
      <value>CLINIC</value>
   </when>
   <transform transformer="EntityLookup">
      <args>
         <string>Place</string>
         <string>classConcept=ff34dfa7-c6d3-4f8b-bc9f-14bcdc13ba6c&amp;name.component.value=$input</string>
      </args>
   </transform>
   <target>relationship[Birthplace].target</target>
</map>

The transformers available are:

Transformer	Arguments	Description
EntityLookup	Entity Type Lookup Expression Value Expression	Queries the persistence layer for the first argument type using the lookup expression procided. Field values can be accessed as HDSI variables such as $fname or $gname , or the $input variable can be used for the current input column.
CamelCase		Converts the current $input to CamelCase. For example nurse practitioner specialist will be transformed to NursePractitionerSpecialist
AgeCalculation		Calculates a date time based on a number which represents the age of the object at a particular time.
Expression	Expression String	Executes a C# expression where each input field is a $variable . This can be used to perform mathematical operations.
NoCase	Case Selection	Converts the input lower case when the argument is l or upper case when the argument is u
Prefix	Prefix Text	Prepends the input value with the argument supplied.
ReferenceTermLookup	Code System	Performs a reference term lookup against the input value in a standardized code system.
EpochToDate	Truncation Method	When a column is represented in as a unix epoch - this will convert the value to a proper date and time.