Skip to main content
Previous sectionNext section

Using and Customizing SDA-FHIR STU3 Data Transformations

Overview of the SDA-FHIR STU3 Transformations

Important:

To complete the steps in the sections of this chapter, you must already have created a Foundation namespace. See the “Installing and Activating a Foundation Production” chapter of the Health Connect Installation and Migration Guide.

Health Connect SDA-FHIR STU3 transformations are comprised of Data Transformation Language (DTL) code, which is generated from field-to-field mapping definitions. To invoke the transformations on SDA or FHIR STU3 data, you can use business processes in a production or use the SDA-FHIR STU3 Transformation API.

To view field-level information on the transformation mappings:

  1. Log in to the Management Portal as a user with the %Ens_EDISchemaAnnotations role.

  2. Navigate to Health —> FHIRnamespace.

  3. Expand the Schema Documentation menu option and click FHIR Annotations.

  4. On this page, you can view information on FHIR STU3 –> SDA or SDA –> FHIR STU3 mappings.

    • For example, if you wanted to see how the FHIR STU3 CarePlan resource and its elements map into SDA, choose CarePlan in the FHIR3 By Name dropdown list. The resulting table will show you the elements of the STU3 CarePlan resource in the FHIR3 Source column. The SDA3 mapping is shown in the SDA3 Target column.

    • The Help and FAQ buttons provide guidance on using and interpreting the elements of the FHIR Annotations user interface.

SDA-FHIR STU3 Transformations: Mapping Conventions

Field-to-Field Mappings

Most mappings are field-to-field: The mapping finds a data value in a source field and assign that value to a target field.

Conditional Mappings

Some field-to-field mappings are applied conditionally. The DTL <if> element controls this in the code. The FHIR Annotations show the label Condition to Set this Field when they present this information.

Literal Values

Among the defined mappings are mappings of literal values to target fields. One purpose of these mappings is to provide values for required target fields when the source object definition contains no fields that could provide the data required by the target.

Often, mappings of this type are defined conditionally, to be used only when needed.

Mapping Single to List

When the source is single but the target is a list, transformations map the source item to the first entry in a target list that contains only one entry. This feature is handled automatically during code generation for transformations. Single to List does not require special attention in the mapping definitions.

Mapping List to Single (Values)

When the source field is a list of values, and the target field is a single value, the transformations concatenate the list of values into a single value, separating each value from the list with a semicolon and space.

Mapping List to Single (Objects)

For SDA to FHIR STU3: when the incoming SDA is a list of objects, and FHIR STU3 has one object, the mapping table contains two mapping entries for the source list field:

  • One mapping maps the source list field to the target single field. The transformation generated from this mapping simply places the first list entry into the target field.

  • The other mapping maps the source list field to the target FHIR extension that contains the full list of objects. The FHIR extension URL is the full source field name, including the resource name, but using all-lowercase text separated by hyphens.

For FHIR STU3 to SDA: when the incoming FHIR STU3 has a list of objects, and SDA has one object, the transformation uses the first STU3 object and drops all the others.

Mapping SDA CodeTableDetail to a FHIR Code

Transformations map an SDA CodeTableDetail (or one of its subclasses) to a FHIR coded object such as Coding or CodeableConcept as follows:

  1. The Code value is mapped to the code field.

  2. The Description is mapped to the display field.

  3. If there is an OriginalText field, it is mapped to the text field.

Mapping Coded Values to FHIR using Lookup Tables

The mapping consults a lookup table to find the entry that maps code values from the source schema (SDA or FHIR STU3) to code values in the target schema (FHIR STU3 or FHIR DSTU2) for this mapping.

If the mapping cannot find the lookup table, or cannot find a matching entry in the lookup table and it has a non-empty default value defined, it applies its default value to the code field. Otherwise, the target receives no value from this mapping.

If the mapping is SDA to FHIR, and the source field contains a non-empty value, then by convention there are two mapping entries for this source field. Both entries execute under the same Condition to Set this Field:

  • One entry does the lookup to retrieve the value to assign to the target field.

  • The other stores the original source field value in a string-valued FHIR extension.

In either case, if there is a Description or OriginalText along with the Code value, it is mapped to FHIR where applicable.

Mapping a FHIR Code to SDA CodeTableDetail

When a FHIR STU3 primitive code or coded object such as Coding or CodeableConcept does not use a lookup to transform the code value from STU3 to SDA, it is transformed to SDA CodeTableDetail (or one of its subclasses) as follows:

  • CodeableConcept.text is transformed to HS.SDA3.CodeTableTranslated.OriginalText

  • CodeableConcept.coding.display (or Coding.display) is transformed to HS.SDA3.CodeTableDetail.Description

  • CodeableConcept.coding.code (or Coding.code, or simply code) is transformed to HS.SDA3.CodeTableDetail.Code

  • GetCodeforURI of CodeableConcept.coding.system (or Coding.system) is transformed to HS.SDA3.CodeTableDetail.SDACodingStandard

  • CodeableConcept.coding.version (or Coding.version) to HS.SDA3.CodeTableDetail.CodeSystemVersionId

Mapping FHIR Coded Values to SDA using Lookup Tables

If you want a mapping to use a code lookup table for FHIR to SDA, the mapping table contains two mapping entries for the source field:

  • One of the two entries consults a lookup table to find the entry that maps a FHIR STU3 code value to an SDA Code.

  • The other mapping entry in the pair takes over when the lookup table entry is unavailable or does not provide a match. It maps the source FHIR code value (unchanged) into an SDA CodeTableDetail object, as described above. That is, if the FHIR code was inside a Coding or CodeableConcept object, the FHIR code, display, system, version, and text values all are mapped appropriately into SDA CodeTableDetail fields.

Mapping String Values to Numeric Values

When the target is FHIR, and a string value is mapped to a numeric value, the string may contain non-numeric text such as units of measurement or instructions. To handle this, there are two mapping entries for the source list field:

  • One of the two entries always assigns the source string value to a FHIR extension that consists of one string-valued field.

  • The other mapping entry tests the source string value to see if it is numeric. If so, it maps this numeric value to the target numeric field.

Multi-Part Literal Values for FHIR Code Objects

For some FHIR target fields that are Coding or CodeableConcept objects, a set of mappings from literal values forms a multi-part value that is assigned to the field when needed. The full set of fields that such an object can contain are: code, system, display, text, version, and userSelected.

Where this is the case, the DTL annotation element for the code field explains that this code resides within a Coding or CodeableConcept object that is receiving a multi-part literal value. The FHIR Annotations show that the set of literal value mappings relating to this code all have the same value in the Condition to Set this Field.

FHIR Bundle Handling

When transforming FHIR STU3 to SDA:

  • Information about containment relationships is reflected in the FHIR Annotations for the Bundle resource.

  • If a resource referenced by ID within the incoming STU3 bundle is not present in the bundle, transformation of the bundle continues. After processing the complete bundle, the transformation code sends an alert to the event log for the active namespace. The alert message identifies each missing resource and indicates that its data will not appear in the SDA data that results from this transformation.

When transforming SDA to FHIR STU3, if the outgoing STU3 bundle contains some resources that did not pass validation, the transformation code sends an alert to the event log for the active namespace. The alert message describes the validation issues.

FHIR Extensions

FHIR extensions for STU3 are available; the URL prefix for them is http://intersystems.com/fhir/extn/.

Support for SDA Fields with no Place In the STU3 Schema

When the target of a transformation is FHIR STU3, one or more SDA source data fields may have no home in the target schema. In that case, transformations map the data to a FHIR STU3 extension: the URL is the full source field name, including the resource name, but using all-lowercase text separated by hyphens.

An extension like this consists of a single string-valued field that holds the SDA data.

The URL prefix in this case is http://intersystems.com/fhir/extn/sda3/lib.

For example:

  • SDA full path name listing class and property: HS.SDA3.Administration:AdministeredAmount

  • Extension name: administration-administered-amount

  • Full URL for the FHIR extension: http://www.intersystems.com/fhir/extn/sda3/lib/administration-administered-amount

Support for SDA CustomPairs

The transformations support the legacy CustomPairs property in SDA classes of type HS.SDA3.SuperClass.

CustomPairs is a collection of objects of type HS.SDA3.NVPairs, each of which has two properties, Name and Value. When the transformation code encounters this property in customer SDA data, and the target is FHIR, the collection is mapped to a FHIR extension that contains a Parameters resource. This Parameters resource is a collection of paired fields: name and valueString.

In the example below, the customized SDA Encounter object has an SDA CustomPairs collection with three members, each with the name PlanOfCareInstructionsText:

{     
   "resourceType": "Encounter",    
   "contained":          
       [             
           {                 
                "resourceType": "Parameters",                 
                "id": "63",                 
                "parameter":                      
                    [                         
                         {                             
                              "name": "PlanOfCareInstructionsText",                             
                              "valueString": "Doctor recommends at least 30 minutes of exercise per 
                                              day"                         
                         },                         
                         {                             
                              "name": "PlanOfCareInstructionsText",   
                              "valueString": "Use sports heart rate monitor to aid in monitoring effort 
                                              level"                         
                         },                         
                         {                             
                              "name": "PlanOfCareInstructionsText",                             
                              "valueString": "Read \"South Beach Diet\""                         
                         }                     
                    ]             
           }         
        ],     
   "extension":          
       [             
           {                 
                "url": "http://intersystems.com/fhir/extn/sda3/lib/encounter-custom-pairs",                 
                "valueReference":                      
                    {                         
                         "reference": "#63"                     
                    }             
           }         
        ],     
   "id": "914"
}

Configuring Your Production for SDA-FHIR STU3 Conversions

Health Connect comes with built-in business processes that handle SDA-FHIR STU3 conversions. You can add them to your existing FHIR production programmatically using the InterSystems Terminal. Instructions for using the Terminal and descriptions of the business hosts added to the production are found in:

FHIR STU3 to SDA Conversions

To configure your existing FHIR production to handle FHIR STU3 to SDA conversions, do the following:

  1. Make sure you have already installed a FHIR production. For instructions on installing a new FHIR production, see Installing and Configuring a FHIR Production .

  2. Log into the Terminal with a role that has the %Admin_Manage:Use privilege.

  3. Go to any Foundation namespace, for example, the namespace that contains your FHIR production:

    set $namespace="FHIRNAMESPACE"
    Copy code to clipboard
  4. Enter:

    do ##class(HS.HC.Util.Installer.Kit.FHIR.FHIRToSDA3).Add(,"FHIRNAMESPACE")
    Copy code to clipboard

    Where FHIRNAMESPACE is the namespace where you installed your FHIR production.

As part of this setup procedure, Health Connect:

The Add method does not create a default business service designed to accept FHIR STU3 and send it to HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process for transformation into SDA3. If you do not need to accept FHIR STU3 for any other reason except transforming it to SDA3, you can modify the HS.FHIR.Service.STU3 business service that was created when you first installed the FHIR production. In this case, change the TargetConfigName setting of HS.FHIR.Service.STU3 to point to HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process. Otherwise, if you are already HS.FHIR.Service.STU3 for other reasons, you must create a new business service that sends the FHIR STU3 data to HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process. In this case, you must also create a CSP app for the endpoint and add an entry in FHIR CSP Config to tie the new CSP app to the new business service.

About HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process

HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process is the built-in business process that converts FHIR STU3 data into SDA format. It:

  • Accepts a FHIR STU3 resource or bundle as input.

  • Converts the FHIR STU3 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 STU3 response (based on what it received) to the business host that originally called it.

Important:

Initially, the TargetConfigName setting of HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process does not have a value. Set it to specify where the SDA output should be sent.

Messages

The request message from a business host to HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process is HS.Message.FHIR.Request.

The response message from HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process is HS.Message.FHIR.Response.

Settings

Settings of HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process that influence FHIR to SDA conversions include:

  • TargetConfigName — Specifies the business host where the XMLMessage that includes the SDA3 stream is sent after it is transformed from FHIR STU3 by the DTL transformation. This setting is located in the Basic Settings section of the Settings tab in the Production Configuration window.

  • CallbackClass — Specifies the class that is used for the callback object that is invoked during the DTL transformation process. If left blank, the class HS.FHIR.DTL.Util.API.HC.Callback.Default.<FHIRVersion>ToSDA3 is used at run time, where <FHIRVersion> is derived from the FHIRVersion property of the incoming FHIR request message. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • OutputToQuickStream — By default, the output of HS.FHIR.DTL.Util.HC.FHIR.SDA3.Process is an HS.Message.XMLMessage object that contains the SDA3 stream produced by the DTL transformation. If this setting is checked, the SDA3 stream is placed in a separate HS.SDA3.QuickStream object, and the QuickStreamID of the QuickStream object is placed in the AdditionalInfoItem property of the XMLMessage. If this setting is not selected, the SDA3 stream is placed in the ContentStream property of the XMLMessage. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

SDA to FHIR STU3 Conversions

To configure your existing FHIR production to handle SDA to FHIR STU3 conversions, do the following:

  1. Make sure you have already installed a FHIR production. For instructions on installing a new FHIR production, see Installing and Configuring a FHIR Production .

  2. Log into the Terminal with a role that has the %Admin_Manage:Use privilege.

  3. Go to any Foundation namespace, for example, the namespace that contains your FHIR production:

    set $namespace="FHIRNAMESPACE"
    Copy code to clipboard
  4. Enter:

    do ##class(HS.HC.Util.Installer.Kit.FHIR.SDA3ToFHIR).Add(,"FHIRNAMESPACE","STU3")
    Copy code to clipboard

    Where FHIRNAMESPACE is the namespace where you installed your FHIR production.

As part of the setup procedure, Health Connect:

About EnsLib.File.PassthroughService

This business service is a typical file service that accepts SDA file input and sends it to HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process so it can be transformed into FHIR STU3. Relevant settings include:

  • File Path — The directory on disk from which it retrieves its file input. You must specify a value for this property, as it does not have one by default. This setting is located in the Basic Settings section of the Settings tab in the Production Configuration window.

  • TargetConfigNames — The business host to which it sends its output. The setup method specifies HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process as the value of this property. This setting is located in the Basic Settings section of the Settings tab in the Production Configuration window.

The output of this business service is content in Ens.StreamContainer format.

About HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process

The HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process business process:

  • Accepts an SDA container as input and loops through each contained object.

  • Converts the SDA container to FHIR STU3 content, in the form of a FHIR Bundle resource.

  • Forwards the FHIR STU3 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.

Important:

Set the value of the TargetConfigName setting of HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process. to specify where it should send its FHIR output.

Messages

The request message to HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process is either Ens.Container or HS.Message.XMLMessage.

There is no response message from HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process. It returns a success or failure status instead.

Settings

Settings of HS.FHIR.DTL.Util.HC.SDA3.FHIR.Process that influence SDA to FHIR conversions include:

  • TargetConfigName — Specifies the business host to which HS.FHIR.FromSDA.DTL.Transaction.Process sends its output. This setting is located in the Basic Settings section of the Settings tab in the Production Configuration window.

  • FHIRVersion — Specifies the version of the FHIR output. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • TransmissionMode — Specifies how the business process transmits the FHIR STU3 bundle for further processing:

    • transaction — 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. This is the default.

    • 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.

    This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • FullTransactionResponse — If selected, the FHIR request message that this process sends is created with a "PREFER"header value set to "return=representation". Per the FHIR spec, this header indicates to a FHIR server that every created or updated resource should be returned in its entirety as it is saved (i.e., with any modifications applied by the server). Whether the server actually does this depends on the server. In general, this setting should be left unchecked except during debugging or if the FHIR client has a specific need to receive back the created/updated resources, as requesting this information is likely to increase response time from the FHIR server. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • FHIRFormat — Specifies whether the content is in XML or JSON format. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • FormatFHIROutput — Specifies 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. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • CallbackClass — Specifies the class that is used for the callback object that is invoked during the DTL transformation process. If left blank, the class HS.FHIR.DTL.Util.API.HC.Callback.Default.SDA3To<FHIRVersion> is used at run time, where <FHIRVersion> is derived from the FHIRVersion property of the incoming FHIR request message. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • ValidResourceRequired — If selected, the FHIR that is generated by the SDA3–to-FHIR DTL transformation must be valid FHIR. If it fails validation, then it will not be forwarded. Regardless of the value of this setting, validation failures will be logged in the Event Log as alert messages. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

  • OutputToQuickStream — If selected, the FHIR payload sent by this business process is placed in an HS.SDA3.QuickStream object, and the id of the QuickStream object is place in the QuickStreamId property of the request message. If left unselected, the FHIR output from the transformation is placed in the Payload property of the request message. This setting is located in the Additional Settings section of the Settings tab in the Production Configuration window.

Using the SDA-FHIR STU3 Transformation API

To invoke the SDA-FHIR STU3 transformations directly without using the built-in business processes, use the method calls in the SDA-FHIR STU3 Transformation API. The method calls are available within HSLIB or your FHIR namespace.

Transforming SDA to FHIR STU3

To transform SDA to STU3, use the following class methods of HS.FHIR.DTL.Util.API.HC.Transform:

  • SDA3ToSTU3Stream(container, Output bundle As %Stream.Object, bundleType As %String, format As %String, callbackObject As HS.FHIR.DTL.Util.API.HC.Callback.Abstract.SDA3ToSTU3 = "", Output validationErrors As HS.Types.FHIR.Errors)

    Parameters:

  • SDA3ToSTU3Object(container, Output bundle As HS.FHIR.DTL.vSTU3.Model.Resource.Bundle, bundleType As %String, format As %String, callbackObject As HS.FHIR.DTL.Util.API.HC.Callback.Abstract.SDA3ToSTU3 = "", Output validationErrors As HS.Types.FHIR.Errors)

    Parameters:

The default behaviors for both methods are as follows:

  • The incoming stream or object is broken down into individual streamlets, which are in turn transformed into STU3 resources.

  • UUIDs are generated and assigned as resource IDs, and each resource ID added to a resourceIds object property for later lookups. This behavior can be overridden: see the class documentation for HS.FHIR.DTL.Util.API.HC.Callback.Abstract.SDA3ToSTU3:AssignResourceID().

  • If you override AssignResourceID(), you may also have to override GetIdByIdentifer() and GetPatientId(), both of which use the resourceIds property.

  • The methods do not modify incoming URLs at all by default. This behavior can be overridden with the GetURLPrefix() method: for example, if you are posting to a specific repository, you can provide the URL prefix for the repository.

  • Resources will contain references to other resources regardless of the mechanism used to assign IDs.

  • Patient and Encounter references will be added to all available resources using the Patient and Encounter streamlets. Encounter references can be made successfully only if the EncounterNumber fields in the SDA streamlets are used. If they are empty, no references will be generated.

  • Anything that does not have a true destination in FHIR will be mapped to a FHIR extension.

  • In the case of shared resources such as Organization, Practitioner, or Medication, a hash of the first 32 kilobytes of each resource is added to a hash table. Each subsequent shared resource is checked for duplication by searching the hash table for a direct match. If a match is found, the resource will be marked as a duplicate. This behavior can be overridden: see the class documentation for HS.FHIR.DTL.Util.API.HC.Callback.Abstract.SDA3ToSTU3:IsDuplicate().

  • The Bundle will be validated at the end of the transformation and any errors saved in the validationErrors output. The Bundle will be returned whether or not there are errors: it is up to your implementation to check for and handle errors before the Bundle is used.

Transforming FHIR STU3 to SDA

To transform STU3 to SDA, use the following class methods of HS.FHIR.DTL.Util.API.HC.Transform:

  • STU3ToSDA3Stream(bundle, Output container As %Stream.Object, callbackObject As HS.FHIR.DTL.Util.API.HC.Callback.Abstract.STU3ToSDA3 = "")

    Parameters:

  • STU3ToSDA3Object(bundle, Output container As HS.SDA3.Container, callbackObject As HS.FHIR.DTL.Util.API.HC.Callback.Abstract.STU3ToSDA3 = "")

    Parameters:

The default behaviors for both methods are as follows:

  • An incoming FHIR STU3 Bundle is broken down into individual resources, and those resources transformed into SDA3 streamlets.

  • When a reference is encountered in a resource and the referenced field has a mapping, the Bundle will be searched for that resource. If the resource cannot be found, an alert will be logged in the event log. If no existing transform handles the referenced resource type and the SDA3 target destination, it will be dropped. It may well be a valid reference, just not one that SDA3 supports.

  • When a mapping is transforming a reference to an object and:

    • A subtransformation exists but the referenced resource has no values for any of the elements with mappings, or

    • There is no subtransformation from the referenced resource type to the datatype in the SDA3 object

    then no object will be created in the SDA streamlet.

  • The EncounterNumber field on an Encounter streamlet will be populated starting at 1 and incremented for each encounter that is processed. Any subsequent resources that reference that Encounter resource, when transformed to SDA3, will perform a lookup based on the resource ID and will find the encounter number it should use. The assignment of encounter numbers can be overridden with HS.FHIR.DTL.Util.API.HC.Callback.Abstract.STU3ToSDA3:AssignEncounterNumber().

  • Similar to encounter numbers, ExternalID values for HealthConcern and Goal resources are populated starting at 1 by default. This behavior can be overridden with HS.FHIR.DTL.Util.API.HC.Callback.Abstract.STU3ToSDA3:AssignExternalId().

  • The value of Container:SendingFacility is set as follows: if a reference to the patient’s managing Organization exists and the organization is in the Bundle, it is used. Otherwise, the patient identifiers are searched for an MRN with an assigning authority, and that assigning authority is used. If neither of these items is found, the string FHIR is used.

  • SDA3 extensions are not used. If a field does not exist in SDA3, the content will be dropped.

  • If a Bundle comes in without a Patient resource, an error will be logged and nothing will be returned. Other than that, no validation will be performed on the container. It will simply be returned as is.

Customizing an SDA-FHIR STU3 Transformation

Each SDA to FHIR STU3 transformation and FHIR STU3 to SDA transformation corresponds to a Data Transformation Language (DTL) class that performs the transformation. These DTL classes can be customized using the DTL Editor or by editing the code directly.

You customize an SDA-FHIR STU3 transformation within a specific namespace, not for the entire instance, so you can have different customizations in each namespace. If you want multiple namespaces to have the same customized transformations, you must repeat the customization process for each namespace.

Defining Package for Customizations

Before customizing SDA-FHIR STU3 transformations, you need to specify a single package for all customized classes. InterSystems recommends naming the class package: HS.Local.FHIR.DTL . To define the package for customized classes:

  1. Open the InterSystems Terminal.

  2. Change to the namespace of the FHIR production. For example, enter:

    set $namespace="fhirNamepace"
    Copy code to clipboard

    Where fhirNamespace is the FHIR production’s namespace.

  3. To check the current setting for the custom DTL class package, enter:

    Write ##class(HS.FHIR.DTL.Util.API.ExecDefinition).GetCustomDTLPackage()
    Copy code to clipboard
  4. If you need to define a new custom DTL package, enter:

    Set status = ##class(HS.FHIR.DTL.Util.API.ExecDefinition).SetCustomDTLPackage("HS.Local.FHIR.DTL")
    Copy code to clipboard

    Where HS.Local.FHIR.DTL is the recommended name for the new custom DTL package.

  5. To verify that defining the DTL package was successful, enter:

    Write status
    Copy code to clipboard

    The response should be: 1 .

Naming the Customized Transformation

Before customizing the transformation, you must name it based on the standard DTL class name that you are customizing. To determine the required name for your customized class:

  1. Open the Management Portal and navigate to the FHIR namespace.

  2. Select Interoperability > List > Data Transformations from the Home page.

  3. Find the name of the transformation that you want to customize. Transformations from SDA to FHIR STU3 are prefixed with HS.FHIR.DTL.SDA3.vSTU3 . Transformations from FHIR STU3 to SDA are prefixed with HS.FHIR.DTL.vSTU3.SDA3 .

  4. Double-click the name of the transformation you want to customize to open it in the DTL Editor.

  5. Open the InterSystems Terminal.

  6. To obtain the required name for the customized DTL class, enter the following in the Terminal:

    Write ##class(HS.FHIR.DTL.Util.API.ExecDefinition).PreviewDTLCustomClass("<standard_class_name>")
    Copy code to clipboard

    Where <standard_class_name> is the full name of the transformation that you are customizing, including packages. It is the name of the transformation that you have open in the DTL Editor. You can view the name on the Transform tab, but do not include the .dtl extension.

  7. Be sure to make note of the response in the Terminal. You need to give your customized DTL class this name.

  8. In the DTL Editor, click Save As .

  9. In the Package field, enter the package from the name of the customized DTL class that appeared in the Terminal. For example, if the customized class name in the Terminal was HS.Local.FHIR.DTL.SDA3.vSTU3.Address.Address , then enter HS.Local.FHIR.DTL.SDA3.vSTU3.Address (without the actual class name).

  10. In the Name field, enter the name of the customized class. For example, if the customized class name in the Terminal was HS.Local.FHIR.DTL.SDA3.vSTU3.Address.Address , then enter Address .

  11. Enter a description and click OK .

Editing the Customized Transformation

Once you have saved the customized transformation with a new name, you can use the DTL Editor to edit it. The following resources can help you get started with the DTL Editor:

Note:

You can also edit the DTL code directly by opening the transformation class in Studio.

Copying Custom Class to Mirror Members

If your environment uses mirroring and the package of your customizations resides in a non-mirrored database, you must copy the customized DTL class to the custom package on each mirror member. For example, if you defined the package for customized classes as HS.Local.FHIR.DTL , then you must copy the customized DTL class to HS.Local.FHIR.DTL on each mirror member because HS.Local resides in the HSCUSTOM namespace, which is not mirrored. If your custom package resides in a mirrored database, no further action is required.

Customizing FHIR STU3 Transformation Lookup Tables

You can customize the lookup tables that are used by FHIR STU3 DTL transformations. These lookup tables are defined in a JSON file called Lookup.json . You can use a Terminal utility to modify a lookup table or you can edit a custom version of Lookup.json directly.

Using the Terminal Utility to Customize a Lookup Table

Health Connect comes with a utility that leads you through the process of customizing a lookup table.

To run the customization utility:

  1. Open the InterSystems Terminal.

  2. To change to the FHIR namespace, enter:

    set $namespace="fhirnamespace"
    Copy code to clipboard

    where fhirnamepace is the FHIR STU3 namespace you have created.

  3. To start the utility, enter:

    do ##class(HS.FHIR.DTL.Util.API.LookupTable).EditLookupTable()
    Copy code to clipboard
  4. Enter the Mapping Source for the lookup table you are customizing. For example, if you are customizing a lookup table that maps values from SDA3 to STU3, enter SDA3 .

  5. Enter the Mapping Target for the lookup table you are customizing. If you selected SDA3 for the Mapping Source in the previous step, STU3 is selected automatically and you can skip to the next step.

  6. Enter the number that corresponds to Mapping Source Value Set in the lookup table you want to customize.

  7. If only one lookup table with the Mapping Source Value Set exists, the Mapping Target Value Set is selected automatically and you can skip to the next step. If not, enter the number that corresponds to the Mapping Target Value Set you want to customize.

  8. Select the code-to-code mapping you want to edit. If you want to add a new code-to-code mapping in the lookup table, enter + .

  9. If you are editing the target value of a code-to-code mapping, enter the new target value for the mapping.

    If you want to edit the source value of the code-to-code mapping, you must enter - to delete the entire code-to-code mapping, then re-run the utility to add a new mapping with the correct source and target values.

Editing Lookup.json to Customize a Lookup Table

You can customize lookup tables by adding, deleting, or editing key/value pairs in a JSON file that contains all of the lookup tables used by transformations. Before beginning, you must make a custom copy of Lookup.json and put it into a special directory.

Creating Custom Lookup.json File

To create a custom JSON file that will be used by transformations when accessing lookup tables:

  1. Navigate to <install-dir>\dev\fhir\lookup , where <install-dir> is the directory where you installed Health Connect.

  2. If it does not already exist, create a new directory called custom .

  3. Navigate to the custom directory.

  4. If it does not already exist, create a new directory that is the name of your FHIR namespace in all capital letters. For example, if the namespace that contains your FHIR STU3 production is called fhirnamespace , create a directory called FHIRNAMESPACE .

  5. Copy Lookup.json from the <install-dir>\dev\fhir\lookup directory to the new <install-dir>\dev\fhir\lookup\custom\<NAMESPACE> directory.

    You can now begin to edit the lookup tables in the new copy of Lookup.json .

Editing Custom Lookup.json File

To begin customizing a lookup table, you must gather four pieces of information:

  • Mapping Source

  • Mapping Target

  • Mapping Source Value Set

  • Mapping Target Value Set

These values can be found in the FHIR Annotations in the Management Portal. To access these values:

  1. Open the Management Portal and navigate to your FHIR namespace.

  2. From the Home page, select Health > Schema Documentation > FHIR Annotations .

  3. In the first drop-down list, select the type of transformation that contains the lookup table you are customizing. Choices are FHIR3 —>FHIR2 , FHIR3—>SDA3 , and SDA3 —>FHIR3 .

    Make note of the Mapping Source and Mapping Target. The first interface format in the transformation pair is the Mapping Source. The second interface format is the Mapping Target. For example, if you select FHIR3—>SDA3 , vSTU3 is the Mapping Source and SDA3 is the Mapping Target.

  4. Click the View <transformation> Lookup Tables button, where the full name of the button depends on which transformation pair you selected.

  5. Using the View Lookup Tables dialog, use the drop-down lists to note the Mapping Source Value Set and Mapping Target Value Set. The Mapping Source Value Set is the name in the left-hand drop-down list. The Mapping Target Value Set is the name in the right-hand drop-down list.

Now that you have the Mapping Source, Mapping Target, Mapping Source Value Set, and Mapping Target Value Set, you can edit a lookup table by adding, deleting, or editing the appropriate key/value pair in the custom Lookup.json file.

The top-level key/value pair in Lookup.json corresponds to the Mapping Source to Mapping Target relationship. For example, a lookup table used by SDA3 to FHIR STU3 transformations looks like:

"SDA3" : {
    "vSTU3" : {
Copy code to clipboard

The next level of key/value pairs corresponds to the Mapping Source Value Set to the Mapping Target Value Set. Search for the correct lookup table by finding the corresponding key/value pair. For example:

"HS.SDA3.Alert:Status" : 
    {"event-status" : {
Copy code to clipboard

Once you have located the lookup table, you can add, delete, or edit the key/value pairs that correspond to the code-to-code mappings.

"A":"in-progress",
"C":"unknown",
"I":"aborted",
"INT":"completed"
Copy code to clipboard