Data integration toolkit maps: Examples and use cases

The data integration toolkit provides an extensive collection of default maps built to conform to the HL7 FHIR specification.

The default entity maps and attribute maps deploy as Dataverse records and are highly configurable to accommodate your solution requirements. This article includes some examples associated with using these maps.

For information on how to configure these maps, review Configure entity maps and Configure attribute maps. The Dataverse healthcare APIs, the writeback process, and the virtual health data tables use the same configured maps.

Entity map examples

This section lists some examples of using entity maps.

Example 1: Patient encounter

When you add a patient encounter to a patient's EHR (electronic health records), the entity map provides the transformation rules that the Dataverse healthcare APIs need to transform FHIR into Dataverse records.

1. The entity map msemr_encounter ↔ Encounter connects the Azure FHIR resource Encounter to the Dataverse entity msemr_encounter.

   

2. Data changes in the Encounter resource on the customer's health record system trigger a new message to the Dataverse healthcare APIs. For example, if the Dataverse healthcare API Azure Logic App is deployed using the Healthcare data pipeline template, a new FHIR bundle is posted to the blob storage. The logic app then processes this bundle and posts it to Dataverse via the Dataverse healthcare APIs.

3. The Dataverse healthcare APIs use the msemr_encounter ↔ Encounter entity map. The related attribute maps transform the incoming FHIR resources into their representative records in Dataverse.

Example 2: Patient update in Dataverse and writeback

This example considers a scenario where you update a patient record in Dataverse and want that change to be written back to your EMR (electronic medical records) system via Azure Health Data Services.

1. The data integration toolkit entity map contact ↔ Patient relates the Azure FHIR resource Patient to the Dataverse entity Contact.

   

2. A data change in a patient record in Dataverse triggers the Dataverse writeback plug-in.

3. This Dataverse plug-in sends a message about the changed record to the outbound FHIR endpoint configured in the writeback section of the integration settings.

4. In this example, the FHIR endpoint is configured to post directly to Azure Health Data Services.

5. You may also configure a relay application such as an Azure Logic App or an Azure Function that can post the message to both your EMR service and Azure Health Data Services.

   Note

   We recommend that you keep your patient, physician, managed clinical, and referenced clinical data synchronized with Microsoft Cloud for Healthcare.

For more information on configuring writeback, go to Overview of writeback for Dataverse healthcare APIs.

Attribute map examples

This section includes examples for configuring various types of attribute maps that you might encounter.

Example 1: Simple string existing field

The following example gets a patient's last name value from FHIR to send to Dataverse or updates the lastname attribute value from Dataverse to the family element in FHIR.

`{"s": "$.name[?(@.use=='usual')].family"}`

This mapping assumes that the name value always exists and can be located via the JSONPath defined on the FHIR resource.

Example 2: Existing or nonexisting field

The following example gets or updates the city field of address[0] if it exists. If this update was from Dataverse and address[0] didn't exist in FHIR, it creates an address[0] parent and sets the city value from Dataverse. It also creates a placeholder or default values for other attributes from Dataverse that might be missing in FHIR.

{
    "s": "$.address[0].city",
    "c": {
           "p": "address[0]",
           "a": [
                  {
                    "line": ["x"]
                  },
                  {
                    "city": "%"
                  },
                  {
                    "state": "x"
                  },
                  {
                    "postalCode": "x"
                  },
                  {
                    "country": "x"
                  }
                ]
         }
}

Note

For string values, the value set is the literal string defined in the attribute array, unless it's one of the special character sequences. These special character sequences are replaced with values as follows:

• % - Copy the value of the Dataverse attribute.
• %% - Copy the type of the FHIR reference resource (example, Patient).
• %%% - Copy the type and resource ID of the FHIR reference resource (example, Patient/1234).

Example 3: Patient name

Apply the rules in the previous section and use the following example to update patient name.

{"s": "$.name[?(@use=='official')].given[0]", "c": {"p": "name[0]", "a": [{"use": "official"}, {"family": "x"}, {"given": ["%"]}]} }

• "s" = Extract a FHIR patient's given name to load into Dataverse
• "c" = Create a patient's given name when it doesn't exist in FHIR
• "p" = Parent object of the entry to create
• "a" = Array of parameters to use when creating "c"

Note

The brackets {} contain the expression, while the commas "," separate the expression segments. However, the array brackets [] indicate that the expression contains two or more complete segments.

"s": "$.name[?(@use=='official')].given[0]"

"c": {"p": "name[0]", "a": [{"use": "official"}, {"family": "x"}, {"given": ["%"]}]

Example 4: Codeable concept

Matching FHIR codeable concepts from FHIR to Dataverse is the same as matching JSON string elements. The only difference is that there's an extra level needed to get to the detail.

1. The URL of the extension is http://hl7.org/fhir/StructureDefinition/patient-religion
2. We want to access the valueCodeableConcept element inside this extension entry.
3. We want the first entry in the coding array.
4. We want to map the display to show the information in FHIR that is attached to a coding system.

FHIR resource

JSONPath

{"s": "$.extension[?(@.url=='http://hl7.org/fhir/StructureDefinition/patient-religion')].valueCodeableConcept.coding[0].display"}

Example 5: Map text information

1. The URL of the extension is http://hl7.org/fhir/StructureDefinition/patient-religion
2. We want to access the valueCodeableConcept element inside this extension entry.
3. We want to map the text to show the information given to FHIR by Epic.

FHIR resource

JSONPath

{"s": "$.extension[?(@.url=='http://hl7.org/fhir/StructureDefinition/patient-religion')].valueCodeableConcept.coding[0].text"}

Example 6: Mapped value

For another example, you can create an attribute map for gender. In Dataverse, the attribute name is gendercode.

1. In the entity map for Contact, select + New Update Service Attribute Map.

2. Because gender is a pick list, the Action Type is Mapped Value.

   Gender in Dataverse is a pick list. Because it's also a pick list in FHIR, you map the FHIR pick list values to the Dataverse pick list values.

3. Select FHIR Element Map to add the FHIR element map for gender. In this example, it's a JSON search string that allows you to get to the FHIR element gender.

4. Select Save.

   In the background, the system determines that gender is an option set. You need to map multiple values for this option set.

5. Under Value Maps, enter the Azure FHIR Value to map for the option set. For example, enter male for the Male option (Dataverse value = 1), and enter female for the Female option (Dataverse value = 2).

   Select Save.

   

Example 7: Set default value

In this example, set a default value for value maps.

1. In the entity map for Contact, select + New Update Service Attribute Map.

2. For Attribute Name, select Contact Type (msemr_contacttype).

   Contact Type in Dataverse is an option set. Because you're bringing in patients, you always want the contact type to be the default value.

3. For Action Type, select Set Default Value.

   A FHIR element map isn't needed because you're only setting the default value. In this case, FHIR has no concept of contact type, but Dataverse needs it.

4. Select Save.

5. Under Value Maps, select the first row, and select Edit.

6. In Attribute Value Map, select Patient for the OptionSet Label field.

   The Value field shows the default value for contact type. The Dataverse healthcare API automatically populates the Dataverse value.

   

7. Select Save & Close.

   Under Value Maps, the Dataverse default value is set. Each time the Dataverse healthcare API comes in and creates a patient, it sets the Contact Type field to Patient.

Example 8: Lookup

The following steps provide an example of mapping a Dataverse attribute of the type Lookup.

1. In the entity map for Contact, select + New Update Service Attribute Map.

2. For Attribute Name, select Primary practitioner (msemr_generalpractitioner).

   The Attribute Type of the attribute Primary practitioner is Lookup (a lookup operation to the Contact entity).

3. For Action Type, the only action type is FK Reference (foreign key reference). You need to indicate to the Dataverse healthcare API how to set this lookup.

4. Add the FHIR Element Map value for the primary practitioner.

   

5. For FHIR Resource Reference, select Practitioner.

   In Dataverse, the entity reference for primary practitioner is Contact. The FHIR resource reference is Practitioner.

6. Select Save.

If a Dataverse attribute is of the type lookup, you can only create a map that is a foreign key (FK) reference. To configure the FK reference, specify the FHIR resource to which you're mapping the destination entity.

Example 9: Map codeable concept

The following procedure is an example of mapping a Dataverse attribute of the type codeable concept.

1. Under Map Setup, select Entity Maps.

2. Under Entity Name, select msemr_observation.

3. In related attribute maps, select + New Update Service Attribute Map.

4. For Attribute Name, select Ratio Denominator Code (msemr_valueratiodenominatorcode).

   The Attribute Type of this attribute is Lookup. It's a lookup operation to the msemr_codeableconcept entity, which is a special entity type in the data model. This entity type is handled differently than other entities.

5. For Action Type, the only action type is Codeable Concept.

6. Add the FHIR Element Map value for the attribute.

7. For Codeable Concept Type, select Quantity Unit Code.

   A codeable concept type is similar to a large option set, and every value in the option set has a type. It allows you to group and filter option sets. Notice that the Codeable Concept Type Value field automatically fills in when you select Quantity Unit Code as the codeable concept type. You didn't need to know the option set value for quantity unit code.

   

8. Select Save.

Now, when Dataverse creates an observation, it needs to set the codeable concept. Dataverse finds that codeable concept by searching the tables for all codeable concepts with the type Quantity Unit Code that matches the code value. A codeable concept is made up of a text, a code, and the type. FHIR knows the code and the text, but doesn't know which codeable concept type to pull from.

Current limitations

• Dynamic array insertion or creation positions can't be absolute. The selection is dynamic using JSONPath.
• Value data must be correctly formatted in JSON for fields such as destination attribute UTF-8 strings, JSON UTC dates, and booleans.

Tools

You can use multiple tools to test JSONPath strings, including the following applications:

• JSONPath Online Evaluator
• JSON Escape and Unescape
• JSON Path Extension for Visual Studio Code

For more information about using these tools, go to JSONPath guidance.

Related information

• Overview of data integration toolkit
• Manage FHIR data using data integration toolkit
• Configure attribute maps
• Configure expansion maps