Share via

Data integration toolkit maps: Examples and use cases

  • Article

Note

Sync admin for FHIR has now been rebranded as Data integration toolkit.

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 are deployed as Dataverse records and are highly configurable to accommodate your various solution requirements. This article includes some specific examples associated with using these maps.

For information on how to configure these maps, go to Configure entity maps and Configure attribute maps. After configuration, the same maps are used by the Dataverse healthcare APIs, the writeback process, and the virtual health data tables.

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

    A screenshot showing the entity map example for patient 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 Azure Logic App (for the Dataverse healthcare APIs) is deployed using the Healthcare data pipeline template in Microsoft Cloud Solution Center, 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.

    For more information on the Healthcare data pipeline template and logic app configuration, go to Dataverse healthcare APIs: Use Healthcare data pipeline template to deploy Azure Logic Apps.

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

    A screenshot showing the entity map example for patient update in Dataverse.

  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 several examples for configuring various types of attribute maps that you may encounter.

Simple string existing field

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

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

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

Existing or nonexisting field

The following example would get or update the city field of address[0] if it exists. If this update was from Dataverse and address[0] didn't exist in FHIR, it would create an address[0] parent and set 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 is one of the special character sequences. These special character sequences will be 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).

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 [] mean that the expression contains two or more complete segments.

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

and

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

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 A screenshot showing the FHIR codeable concepts.

JSONPath A screenshot showing the JSONPath.

Text example (religion)

  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 A screenshot showing the FHIR codeable concepts for the text example.

JSONPath A screenshot showing the JSONPath for the text example.

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 that is gender.

  4. Select Save.

    Behind the scenes, the system has determined that gender is an option set. There are multiple values that you need to map 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 is 1), and enter female for the Female option (Dataverse value is 2).

    Select Save.

    A screenshot displaying the value maps.

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.

  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 requires Contact Type.

  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.

    A screenshot displaying an example for setting the default value for an attribute map.

  7. Select Save & Close.

    Notice that, 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.

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

    A screenshot showing the FHIR element map value.

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

Map codeable concept

The following procedure is an example of mapping a Dataverse attribute that is a 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 to the msemr_codeableconcept entity, which is a special entity type in the data model that's 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 gives you a way to group and filter option sets. Notice that the Codeable Concept Type Value field was automatically filled in when you selected Quantity Unit Code as the codeable concept type. You didn't need to know the option set value for quantity unit code.

    A screenshot showing an example for codeable concept type.

  8. Select Save.

Now, when Dataverse creates an observation, and it needs to set the codeable concept, it finds that codeable concept by looking at the tables for all codeable concepts that have the type Quantity Unit Code matching the code value that's in the codeable concept. 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

  • No dynamic array insertion or creation positions must be absolute. Selection is dynamic using JSONPath.
  • Value data must be valid 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 tools:

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

See also

What is Microsoft Cloud for Healthcare?
Overview of Data integration toolkit
Manage FHIR data using Data integration toolkit
Configure attribute maps
Configure expansion maps