Configure attribute maps
The data integration toolkit includes default maps that conform to the HL7 FHIR specification. Both entity and attribute maps are deployed as Dataverse records and are highly configurable to meet your solution requirements.
To learn more about attribute maps, see Overview of attribute maps.
Tip
Use the Export to Excel option in the command bar to export the mapping information to an Excel file. For more information, see 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 it processes a FHIR resource for the related entity map. |
| Enable Writeback to FHIR | When writeback is enabled, this flag indicates whether the attribute is included in the outbound payload. The default value for this field is Yes. |
| 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 | A lookup operation 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 for the attribute. Following are the supported 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 Dataverse. This action type is helpful when the attribute is needed but doesn't exist in the source system. Mapped Value: Transform and map 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, see FHIR element map. |
| Expansion Entity Map | When you select Expand as the Action Type, this value is a lookup operation to the related entity map of the type Expansion. For more information on expansion maps, see 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, see Used in record matching. |
| Enable in JIT Create | When the Dataverse healthcare APIs process a FHIR resource for ingestion, the resource might reference a record that doesn't exist in Dataverse. For example, an Encounter could reference a Practitioner record that isn't yet created in Dataverse. When you enable the Enable in JIT Create (JIT: Just-in-time) field, the API processor contacts the FHIR service for the missing resource and creates the Dataverse record before proceeding. Before you enable this field, configure writeback, include the configuration for your FHIR service, and make sure you enable any related entity and attribute maps. |
FHIR element map
The entity attribute mapping definitions on 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 information and examples of attribute map configuration, see Attribute map examples.
Used in record matching
Child arrays in FHIR JSON messages don't contain unique identifiers like root level FHIR resources. Because of this characteristic, 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 field 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 common steps for configuring and managing attribute maps. For detailed examples, see 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 included with the default data integration toolkit maps, disable it. For example, you might not need to sync and store the on behalf of attribute in the EMR system for the encounter entity.
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 the field 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. To add attribute maps to this entity map:
Under Map Setup, select Entity Maps.
In the list of entities, select the Contact entity 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 in Dataverse for this patient and the FHIR Required Attribute is set to Yes, you must populate the attribute. If you don't populate the attribute, the 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 copies 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, which is the 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.
