Using and Customizing SDA-FHIR DSTU2 Data Transformations
To complete the steps in the sections of this chapter, you must already have created a Foundation namespace. An existing FHIR namespace will serve this purpose, but if you want to create a separate Foundation namespace, see the “Installing and Activating a Foundation Production” chapter of the Health Connect Installation and Migration Guide.
Health Connect supports transformations between SDA objects and FHIR DSTU2 resources using the data transformation language (DTL). This mapping can provide useful functionality in many different use cases, including:
Taking content from an SDA-aware system and providing it to a FHIR DSTU2 system.
Taking content from multiple SDA-aware systems and normalizing it for use or storage in a FHIR DSTU2 system.
Taking content from a FHIR DSTU2 system and providing it to an SDA-aware system.
Because DTL provides one-to-one mapping and certain FHIR resources do not always map one-to-one to SDA objects, Health Connect provides business processes that perform more complex transformations. For example, Health Connect transforms an SDA Medication to the FHIR DSTU2 MedicationDispense, MedicationOrdered, and Medication resources. This is true for the FHIR DSTU2 DiagnosticReport, Medication, Vaccination resources, among others.
Because these transformations are written in the Data Transformation Language (DTL), members of your organization can easily customize them using the DTL editor, which is a visual interface (rather than by having to write code). For more information about the DTL editor, see the Developing DTL Transformations guide.
Configuring Your Production for SDA-FHIR DSTU2 Conversions
To configure an Health Connect FHIR production for SDA-FHIR DSTU2 conversions, the process is:
Log into the Terminal with a role that has the %Admin_Manage:Use privilege.
Go to any Foundation namespace:
set $namespace="FHIRNAMESPACE"Copy code to clipboard
Run the Add method of the HS.HC.Util.Installer.Kit.FHIR.ToSDA class, specifying the name of the FHIR DSTU2 namespace for your production. For example, with the FHIRNAMESPACE namespace, the call is:
do ##class(HS.HC.Util.Installer.Kit.FHIR.ToSDA).Add(,"FHIRNAMESPACE","DSTU2")Copy code to clipboard
For more information, see the section “About HS.HC.Util.Installer.Kit.FHIR.ToSDA.”
Run the Add method of the HS.HC.Util.Installer.Kit.FHIR.FromSDA class, specifying the name of the FHIR DSTU2 namespace for your production. For example, with the FHIR namespace, the call is:
do ##class(HS.HC.Util.Installer.Kit.FHIR.FromSDA).Add(,"FHIRNAMESPACE","DSTU2")Copy code to clipboard
For more information, see the section “About HS.HC.Util.Installer.Kit.FHIR.FromSDA.”
The Add method of the HS.HC.Util.Installer.Kit.FHIR.ToSDA class establishes the infrastructure to support converting data from FHIR DSTU2 format to SDA format. This includes:
Adding a new business service, HS.FHIR.ToSDAService.DSTU2. This service accepts FHIR DSTU2 input.
Creating DTL lookup tables. These provide the mappings for specific field values, including those where there is not a one-to-one mapping from FHIR DSTU2 to SDA.
Initially, the TargetConfigName setting of HS.FHIR.ToSDA.DTL.Process.DSTU2 does not have a value. Set it to the desired value.
The Add method of the HS.HC.Util.Installer.Kit.FHIR.FromSDA class establishes the infrastructure to support converting data from SDA format to FHIR DSTU2 format. This includes:
Adding a new business service, EnsLib.File.PassthroughService. This business host accepts a file containing SDA content in XML format.
Adding a new business process, HS.FHIR.FromSDA.DTL.Transaction.Process. This business host transforms SDA input to FHIR DSTU2 output.
Creating DTL lookup tables. These provide the mappings for specific field values, including those where there is not a one-to-one mapping from SDA to FHIR DSTU2.
Set the value of the File Path setting of the EnsLib.File.PassthroughService business service to specify where it receives its SDA input. Select any directory that you wish to choose for SDA file input.
Set the value of the TargetConfigName setting of HS.FHIR.FromSDA.DTL.Transaction.Process to specify where it should send its FHIR output.
SDA-FHIR DSTU2 Business Hosts
The setup methods create the following business hosts:
This service accepts FHIR input that is sent to the endpoint host:port/csp/healthshare/fhirnamespace/fhirtosda3/dstu2. It routes that input to HS.FHIR.ToSDA.DTL.Process.DSTU2.
The HS.FHIR.ToSDA.DTL.Process.DSTU2 business process:
Accepts a FHIR DSTU2 resource or bundle as input.
Converts the FHIR DSTU2 content to an SDA container.
Forwards the container to the business host specified by the TargetConfigName setting.
Receives the response from the business host.
Returns a FHIR DSTU2 response (based on what it received) to the business host that originally called it.
This is a typical file service, with relevant settings that include:
File Path — The directory on disk from which it retrieves its file input, which is part of the Basic Settings. You must specify a value for this property, as it does not have one by default.
TargetConfigNames — The business host to which it sends its output, which is also part of the Basic Settings. The setup method specifies HS.FHIR.FromSDA.DTL.Transaction.Process as the value of this property.
The output of this business service is content in Ens.StreamContainer format.
The HS.FHIR.FromSDA.DTL.Process business process:
Accepts an SDA container as input and loops through each contained object.
Converts the SDA container to FHIR DSTU2 content, in the form of a FHIR Bundle resource.
Forwards the FHIR DSTU2 content to the business host specified by the TargetConfigName setting.
Receives a response from the business host.
Returns a response (based on what it received) to the business host that originally called it.
The following properties are relevant to the SDA-to-FHIR DSTU2 conversion:
TargetConfigName — The destination to which HS.FHIR.FromSDA.DTL.Transaction.Process sends its output. This is another business host in this production. This property has no initial value.
TransmissionMode — How the business process transmits the FHIR DSTU2 bundle for further processing:
transaction — The default; the business process sends the bundle of resources in a single interaction and the processing succeeds or fails for the whole of the bundle; if processing any single resource fails, processing for the other resources (and the entire bundle) stops.
batch — The business process sends the bundle of resources in a single interaction and each resource is processed independently; if processing any single resource fails, processing for the other resources still proceeds. (This is analogous to the manner in which Health Connect processes an SDA container.)
individual — The business process sends each resource from the bundle separately as its own interaction.
CustomDTLPackage — The class package from which the business process loads any custom data transformations. This package contains only the custom data transformations; if a transformation is not in the package, the business process uses the standard version. You must specify this package before creating any custom data transformations.
FHIRFormat — Whether the content is in XML or JSON format.
FormatFHIROutput — Whether or not content is formatted for readability. If selected, this setting has a performance impact, and as such should be enabled only during development and testing.
A Sample Conversion from SDA to FHIR DSTU2
To explain how Health Connect transforms data, this section walks through a sample of converting sample data from SDA format to FHIR format.
To begin the process, first perform the following setup tasks:
If you have not already done so, create an entry of type HTTP in the Service Registry for the endpoint of an external FHIR repository. You can use a public test FHIR server for this purpose.
Set the value of the ServiceName setting of HS.FHIR.REST.Operation to the name of the Service Registry entry you created in the first step.
Set the value of the File Path setting of the EnsLib.File.PassthroughService business service.
The process to convert SDA to FHIR DSTU2 is as follows:
Place an XML-formatted SDA file in the input directory for EnsLib.File.PassthroughService (as specified by the File Path property). This begins processing.
HS.FHIR.FromSDA.DTL.Transaction.Process processes the SDA:
It converts the SDA container to a FHIR DSTU2 Bundle and converts the supported objects into FHIR resources. It places each FHIR resource in an entry in the bundle, along with a request property, which specifies the action associated with the resource when the bundle is processed.
If the original SDA container had any SDA objects for which there were no transformations available, the HS.FHIR.FromSDA.DTL.Transaction.Process generates warnings for each object. These are visible in the production’s Message Viewer page (Interoperability > View > Messages) and in its Event Log (Interoperability > View > Event Log).
HS.FHIR.REST.Operation returns an HS.Message.FHIR.Response message to HS.FHIR.FromSDA.DTL.Transaction.Process, reporting on the success or failure of the interaction. (Each Bundle entry in the request has a corresponding entry in the response.)
HS.FHIR.FromSDA.DTL.Transaction.Process returns a status of success or failure.
Looking in more detail at the conversion process, the content of the HS.Message.FHIR.Request specifies:
A Type value of Bundle, which specifies that FHIR DSTU2 processing occurs for a group of FHIR resources. (The setting for this value is near the top of the content tab for the message in the message trace.)
An Interaction parameter, whose value is as specified in HS.FHIR.FromSDA.DTL.Transaction.Process.
If TransmissionMode is set to batch or transaction, a Bundle whose type value is batch or transaction.
If TransmissionMode is set to individual, a set of requests each one of which contains a single resource.
Similarly, the content of the HS.Message.FHIR.Response includes:
A Type value of Bundle.
Within the Bundle:
If TransmissionMode was set to batch, a type value of “batch-response”. Each entry in the bundle includes status information about success of the interaction for the resource and any relevant location information regarding the resource (such as, in this example, the location of the resource within the resource repository).
If TransmissionMode was set to transaction, a type value of “transaction-response”. Each entry in the bundle includes status information about success of the interaction for the resource and any relevant location information regarding the resource (such as, in this example, the location of the resource within the resource repository).
If TransmissionMode was set to individual, the response indicates the success or failure of that individual request.
The data of each resource.
Information from the Message Trace
To see the details of the process, view the message trace for processing the SDA container. To see more details about messages, for HS.FHIR.FromSDA.DTL.Transaction.Process set the value of the TraceOperations property to *FULL*.
With trace operations on, the message trace for transforming SDA to FHIR DSTU2 now includes far more detail. It is now visible that, during processing, HS.FHIR.FromSDA.DTL.Transaction.Process creates and modifies a working copy of the SDA. The working copy of the FHIR output temporarily uses contained resources; the final output does not include contained resources.
About the SDA-FHIR DSTU2 Data Lookup Tables
Each transformation has access to the FromSDA and ToSDA data lookup tables, which specify how particular values are mapped between SDA and FHIR DSTU2. A data lookup table contains a list of key-value pairs that may:
Convert codings from one data format to another, such as between single-letter codes for SDA to natural language words for FHIR DSTU2
Standardize or normalize multiple values, such as between multiple, equivalent values in one system to a single code in the other
Perform other mappings
For example, the FromSDAAllergyCategory data lookup table maps multiple possible SDA values, including 414285001, food, Food, and FoodAllergy, to the single FHIR DSTU2 food value.
To view a data lookup table:
In the FHIR namespace, go to the Lookup Tables page (Interoperability > Configure > Data Lookup Tables).
On the Lookup Tables page, select Open, which displays the list of lookup tables.
To view a particular lookup table, click on its name. This displays its page in the portal, which is a set of key-value pairs.
To customize a data lookup table:
In the FHIR namespace, go to the Lookup Tables page (Interoperability > Configure > Data Lookup Tables).
On the Lookup Tables page, select Open, which displays the list of lookup tables.
To customize a particular lookup table, click on its name. This displays its page in the portal, which is a set of key-value pairs.
Click Save As to save the lookup table with a new name.
Save the customized table with the name such as Local.FromSDAAllergyCategory. Customized names always begin with Local., including the period.
Once the customized table has a new name, you can customize an individual key-value pair:
Delete it by clicking the red X to its left.
Modify it by clicking it; enter new values on the right for its Key or Value; and then select Apply on the right.
Click Save to save the customized lookup table.
For more information about lookup tables, see the “Defining Data Lookup Tables” section in the “Defining Other Options for Productions” chapter of Configuring Productions.
Customizing a Transformation from SDA to FHIR DSTU2
This section demonstrates two actions that modify a transformation:
Removing Elements of a Transformation
This section demonstrates removing transformations for three elements:
SDA Race, which is transformed to FHIR DSTU2 us-core-race
SDA EthnicGroup, which is transformed to FHIR DSTU2 us-core-ethnicity
SDA Religion, which is transformed to FHIR DSTU2 us-core-religion
In sample SDA, these appear in a form such as:
<Container> ... <Religion> <Code>PRE</Code> <Description>Christian: Presbyterian</Description> <SDACodingStandard>ReligiousAffiliation</SDACodingStandard> </Religion> <MaritalStatus> <Code>S</Code> <Description>Single</Description> <SDACodingStandard>MaritalStatus</SDACodingStandard> </MaritalStatus> <Gender> <Code>M</Code> <Description>M</Description> </Gender> <Race> <Code>2106-3</Code> <Description>White</Description> <SDACodingStandard>Race & Ethnicity - CDC</SDACodingStandard> </Race> <Races> <Race> <Code>2106-3</Code> <Description>White</Description> <SDACodingStandard>Race & Ethnicity - CDC</SDACodingStandard> </Race> </Races> <EthnicGroup> <Code>Not Hispanic or Latino</Code> <Description>Is Not Hispanic or Latino</Description> </EthnicGroup> ... </Container>
After conversion to FHIR DSTU2, they appear as:
<Patient> <extension url="http://hl7.org/fhir/StructureDefinition/us-core-race"> <valueCodeableConcept> <coding> <system value="urn:oid:2.16.840.1.113883.6.238"/> <code value="2106-3"/> <display value="White"/> </coding> </valueCodeableConcept> </extension> <extension url="http://hl7.org/fhir/StructureDefinition/us-core-ethnicity"> <valueCodeableConcept> <coding> <code value="Not Hispanic or Latino"/> <display value="Is Not Hispanic or Latino"/> </coding> </valueCodeableConcept> </extension> <extension url="http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName"> <valueString value="Rogers"/> </extension> <extension url="http://hl7.org/fhir/StructureDefinition/us-core-religion"> <valueCodeableConcept> <coding> <system value="urn:oid:2.16.840.1.113883.5.1076"/> <code value="PRE"/> <display value="Christian: Presbyterian"/> </coding> </valueCodeableConcept> </extension> <identifier> <type> <coding> <system value="http://hl7.org/fhir/v2/0203"/> <code value="MR"/> <display value="Medical record number"/></coding></type></identifier> </Patient>
To remove a transformation for these elements:
Specify the location from which HS.FHIR.FromSDA.DTL.TransactionProcess loads custom data transformations by setting its CustomDTLPackage property, such as to the User.Custom.FromSDA package.
In the FHIR namespace, go to the DTL editor (Interoperability > Build > Data Transformations).
In the DTL Editor, open the transformation that converts an SDA Patient to the FHIR DSTU2 Patient resource:
At the top of the page, select Open, which displays the Finder Dialog for DTL data transformations.
In the Finder Dialog, select HS > FHIR > DTL > FromSDA > Patient
To create custom data transformation, select Save As from the top of the page, which displays the Save Data Transformation dialog.
In the Save Data Transformation dialog:
From the Package field, enter the name of the custom package location set above; here, this is User.Custom.FromSDA.
In the Description field, enter a description of the modified transformation.
This saves the modified transformation into the custom package; here, this is User.Custom.FromSDA.Patient.
Close the confirmation dialog.
From the left column (HS.SDA3.Patient), select EthnicGroup. This displays the connections between the EthnicGroup (as SDA) and the relevant properties that are part of the Patient FHIR resource.
Click on the connection from EthnicGroup to FHIR DSTU2, which is the green line to the right of the EthnicGroup element:
This both highlights the connection to the resulting FHIR and, below the connections, also highlights the line of code that performs this part of the transformation. The line of code that performs this section of the transformation is part of a block of code that composes the entire transformation, and begins with a line such as:
and ends with lines such as:
set iExtension = iExtension + 1 else endif
In the DTL code that appears at the bottom of the window, these may be roughly from line 126 to line 135.
Delete all the code, from the if to the endif, which removes all the logic that performs the transformation. To do this, click the red X to the left of the if statement. Once you confirm your choice, this removes the entire statement (from the if to the endif) from the transformation.
Perform the analogous actions for Religion and Races().
Save the changes to the transformation by clicking Save button at the top of the page.
Compile the modified data transformation by clicking the Compile button at the top of the page.
Having modified the transformation, the FHIR DSTU2 output based on the same SDA input now includes the following lines:
<Patient> <extension url="http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName"> <valueString value="Rogers"/> </extension> <identifier> <type> <coding> <system value="http://hl7.org/fhir/v2/0203"/> <code value="MR"/> <display value="Medical record number"/></coding></type></identifier> </Patient>
These lines do not include us-core-race, us-core-ethnicity, and us-core-religion, because of the modifications to the transformation.
Modifying the Transformation for a Particular Property
This section demonstrates modifying a transformation for the SDA EncounterType, which is transformed to a property of the Encounter resource. The default SDA-to-FHIR DSTU2 transformation handles three encounter types:
To look at the existing mapping, open the FromSDAEncounterEncounterType transformation according to the instructions in the “About the SDA-FHIR DSTU2 Translation Tables” section.
In SDA, a sample that includes EncounterType is:
... <Encounter> <EncounterNumber>urn:uuid:63e41adf-415a-459d-a803-90484722a896</EncounterNumber> <AdmissionType> <Code>R</Code> <Description>Routine</Description> </AdmissionType> <EncounterType>O</EncounterType> ...
After conversion to FHIR DSTU2, the relevant section of the Encounter resource appears as:
... <resource> <Encounter> <identifier> <use value="official"/> <value value="urn:uuid:63e41adf-415a-459d-a803-90484722a896"/> </identifier> <class value="outpatient"/> <type> <coding> <code value="R"/> <display value="Routine"/> </coding> </type> ...
As an example, this section adds a fourth EncounterType, W, for a visit to a walk-in clinic. It modifies the FromSDAEncounterEncounterType transformation to translate this EncounterType value to the FHIR DSTU2 value, emergency. The process of modifying the transformation involves several actions:
Determine if any change is required in the transformation. For example, if a walk-in visit were treated as an outpatient visit, no change would be required, because the Encounter transformation sets the value of the FHIR to outpatient by default. To confirm this:
Open the Encounter transformation in the DTL Editor (Interoperability > Build > Data Transformations, which opens the DTL Editor).
In the DTL Editor, open the Encounter transformation (Open > HS > FHIR > DTL > FromSDA > Encounter).
On the Source side (HS.SDA3.Encounter), select the EncounterType property and then click on its connection; in the right pane, the Action tab’s Value field holds the code that performs transformation.
Look at the code that sets this value. It uses the HS.FHIR.DTL.Utils.LookupFHIR method, and this method’s third argument specifies the default transformed value, which is outpatient. Hence, if an SDA EncounterType does not have a specified transformation, the Encounter transformation uses the default value. Because the SDA EncounterType transformation is being modified to transform the W in SDA to emergency in FHIR DSTU2, you must modify the FromSDAEncounterEncounterType transformation.
Processing the modified SDA (containing the W encounter) prior to creating a custom transformation result in FHIR DSTU2 output with an outpatient encounter, because this is the default case.
To create a custom version of the FromSDAEncounterEncounterType transformation, make a copy of it:
Go to the Lookup Tables page (Interoperability > Configure > Data Lookup Tables)
Open the FromSDAEncounterEncounterType transformation (select Open, then FromSDAEncounterEncounterType in the Finder Dialog). This displays the FromSDAEncounterEncounterType page with its Lookup Table Viewer pane.
Click Save As, which displays the Lookup Table: Save As dialog.
In that dialog, enter Local.FromSDAEncounterEncounterType as the name of the custom lookup table.
This creates the custom transformation and displays its name in the page’s upper-left tab.Important:
Custom transformations must always have names of the form Local.TransformationName.
Modify the custom transformation by adding a new key-value pair to it in the Lookup Table Viewer pane (on the right):
In the Key field, enter W as the SDA to be transformed.
In the Value field, enter emergency as the resulting FHIR.
Below the Key and Value fields, click Apply.
In the main pane, click Save.
Given the SDA input from above, the modified transformation results in the following text:
... <resource> <Encounter> <identifier> <use value="official"/> <value value="urn:uuid:63e41adf-415a-459d-a803-90484722a896"/> </identifier> <class value="emergency"/> ...
This causes the walk-in visit to be treated as an emergency encounter.