Configure attribute maps

Article
06/08/2023

Note

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

The Data integration toolkit ships default maps built to conform to the HL7 FHIR specification. However, both entity and attribute maps are deployed as Dataverse records, and are highly configurable to accommodate your various solution requirements.

To learn more about attribute maps, go to Overview of attribute maps.

Tip

You can use the Export to Excel option in the command bar to export the mapping information to an excel file. For more information about exporting data from your app to an excel file, go to Export data to Excel.

Attribute map fields

Attribute maps provide the FHIR node to Dataverse field level mapping. They need to account for various different data types.

Field name	Description
Disable	Flag indicating whether the attribute map is disabled. If the value is set to `True`, the Dataverse healthcare API skips the attribute map when processing a FHIR resource for the related entity map.
FHIR Required Attribute	When writeback is enabled, this flag indicates whether the attribute is required when sending data through to the FHIR server.
Update Service Entity Map	Lookup to the parent entity map for the attribute map.
Entity Name	The schema name of the Dataverse table for the parent entity map.
Attribute Name	The schema name of the Dataverse column to which the FHIR values would be mapped. This list changes depending on the entity map selection.
Action Type	The type of value mapping that occurs for the attribute. The following section lists the different action type values: Copy Data: Direct copy of the data without any type of transformation. This action type is primarily used when the data type in both the systems match. Set Default Value: Always set a default value in CDS. This action type is helpful when the attribute is needed but doesn't exist in the source system. Mapped Value: Transform and mapping on the data. This action type is best used when data types don't match, such as with Dataverse choices or Yes or No options. Lookup: Maps FHIR references to Dataverse lookup values. Codeable Concept: Maps a FHIR coding node to a codeable concept lookup in Dataverse. Expand: Maps a FHIR node of the type array to a related expansion table.
FHIR Element Type	Value indicating the data type of the element in the FHIR JSON message.
FHIR Element Map	Field containing the JSONPath query for the specific FHIR node. It includes instructions for how to retrieve the inbound value and how to structure the outbound value for writeback. For more information on this field, go to FHIR element map.
Expansion Entity Map	When you select Expand as the Action Type, this value is a lookup to the related entity map of the type Expansion. For more information on expansion maps, go to Configure expansion maps.
Used in Record Matching	For attribute maps related to expansion entity maps, this field indicates whether the Dataverse field is a key or is part of a composite key that uniquely identifies the record sent to Dataverse. For more information, go to Used in record matching.

FHIR element map

The entity attribute mapping definitions on Microsoft Dataverse contain a FHIR Element Map field. This field defines how to retrieve and send values between Azure Health Data Services FHIR service and FHIR enabled endpoints.

These mapping definitions are contained in a serialized JSON object with entries to support JSONPath selection to retrieve and update existing property values. It also includes definitions to insert new property values that don't already exist in the receiving platform.

JSON object definition

{
    "s": "",
    "c": { 
            "p": "",
            "a": [
                   ""
                 ]
}

where

"s" = A valid JSONPath expression used to select an existing JSON property of the FHIR resource to extract or set values from and to Dataverse.
"c" = JSON property fields used to insert or create JSON properties when the selected path is nonexistent in the resource JSON object.
"p" = The parent JSON property name to create.
"a" = Array of attributes to set on the selected JSON property.

For more details and examples of attribute map configuration, go to Attribute map examples.

Used in record matching

Because child arrays in FHIR JSON messages don't contain unique identifiers like root level FHIR resources, the Dataverse healthcare APIs, writeback process, and virtual health data tables require other criteria to ensure that the correct values are created and updated. The Used in Record Matching field allows you to identify which expansion map attribute should be used to signal uniqueness. This is important for expansion maps and for maintaining data integrity when updating Dataverse records.

To have the Used in Record Matching value set to True, you must have at least one attribute map for an expansion entity map. If more than one attribute map has this field marked as True, the combined list of attribute maps together provide a composite key when creating and updating new expansion level records.

Note

Modifying this field value after a system is live in production can potentially cause data corruption issues when modifying existing records. Ensure that your interoperability team reviews this before making any changes.

Manage attribute map records

The following sections list some common steps for configuring and managing attribute maps. For detailed examples, go to Attribute map examples.

Add an attribute map to an entity map

Open the entity map.
On the General tab under Related Attribute Maps, select + New Update Service Attribute Map.

Disable an attribute map

If you don't need an attribute map for an entity that's included with the Data integration toolkit default maps, you can disable it. For example, for the encounter entity, you might not need to have the attribute on behalf of synchronized and stored in the EMR system.

Under Map Setup, select Attribute Maps.
Select the msemr_encounter entity, and then select Edit.
In Related Attribute Maps, select msemr_onbehalfof, and then select Edit.
Set the value of Disabled to Yes.
Select Save.

Archive an attribute map

You can disable any attribute map, but it would still appear in the Active Update Service Attribute Maps view. To remove an attribute map from this view, you can archive the attribute map.

Open the entity map.
On the General tab, under Related Attribute Maps, select the attribute map.
In the Active Update Service Attribute Maps view header, select Archive.

View archived attribute maps

Open the entity map.
On the General tab, under Related Attribute Maps, select Active Update Service Attribute Maps, and then select Archived Update Service Attribute Maps.

Create a service attribute map

The Contact entity in Dataverse is mapped to the Patient resource in Azure FHIR. You can add attribute maps to the entity map.

Under Map Setup, select Entity Maps.
In the list of entities, select Contact that's mapped to the FHIR resource Patient, and then select Edit.
In Related Attribute Maps, select + New Update Service Attribute Map.
Set the value of FHIR Required Attribute to No.

This setting indicates how data flows back to the configured FHIR endpoint. When a change occurs inside Dataverse for this patient and the FHIR Required Attribute is set to Yes, if the user hasn't populated the attribute, the Dataverse change is saved to Dataverse but wouldn't be posted to the FHIR endpoint. The event is written to the logs.
For Attribute Name, select First Name (firstname).
For Action Type, select Copy Data. This value means that the string data on one system is copied to the other system.
For FHIR Element Map, add the JSON search string that works with the FHIR API. For example, you might add a JSON search string that allows you to get to the FHIR element that is first name.
Select Save. The Value Maps section is now displayed on the same window with the + New Attribute Value Map option. The Contact entity doesn't require a value map because it's a string.
In the entity map for Contact, under Related Attribute Maps, you can now view the attribute map with the name firstname.