Configure entity maps

Entity maps are at the highest level in the mapping process. You can map one entity concept to multiple FHIR (Fast Health Interoperability Resources) resources. Entity maps help the Dataverse healthcare APIs move data between Dataverse entity records and FHIR resources, and help Dataverse send the correct data to remote FHIR endpoints.

The data integration toolkit provides an extensive collection of default maps built to conform to the HL7 FHIR specification. Entity maps are deployed as Dataverse records and are highly configurable to accommodate your various solution requirements.

To learn more about entity maps and look at usage examples, go to Overview of entity maps and Entity map examples.

Entity map fields

Entity maps map the FHIR resource to a Dataverse entity (table), but each entity map includes more configuration options.

Field name Description
Disable Flag indicating whether the entity map is disabled. If the value is set to True, the Dataverse healthcare API skips the entity map when processing a message for the selected Azure FHIR resource type.
Enable Write Back to FHIR When writeback is enabled, this flag indicates whether the field value should be included when posting FHIR resources to the system.
Azure FHIR Resource A lookup operation to the related FHIR resource type being mapped to the Dataverse table. For example, the Dataverse table Account is mapped to the FHIR resource Organization.
Supported Messages When Enable Write Back to FHIR is set to True, this field indicates what type of operations are supported when posting data back to the FHIR service. Supported values are Create, Update, or both.
Expand Flag indicating whether the entity map is for an expansion table, and not a root level FHIR resource. Each expansion map has the same Azure FHIR resource value, but only one root level entity map can be specified for each Azure FHIR resource.

Manage entity map records

You can perform record level updates to the default entity maps deployed with Microsoft Cloud for Healthcare.

Disable an entity map

If you no longer need to use an entity map included with the data integration toolkit, you can disable it. For example, you might not need the MedicationRequest records synchronized and stored in the EMR (Electronic Medical Record) system.

Important

You can't delete an entity map that's part of the data integration toolkit, because they're solution aware. To delete it, you need to delete the whole solution. We recommend disabling the map, or archiving it.

  1. Under Map Setup, select Entity Maps.

  2. Select the entity that you want to disable.

  3. Select Yes as the value for Disable, and then select Save.

    A screenshot showing how to disable an entity map.

Create an entity map

Creating entity maps makes the data integration toolkit more extensible. For example, if you want to create a new entity map for patients, start by naming the new entity. In this example, the Azure FHIR resource is named Patient and the Dataverse entity is named Contact.

  1. Under Map Setup, select Entity Maps, and then select + New.

  2. For EntityName, select Contact.

  3. For Azure FHIR Resource, type or select Patient.

  4. For the Disable field, select No.

  5. For Enable Write Back to FHIR, select Yes.

    Setting the value to Yes means that changes in Dataverse write back to FHIR. If you select No, FHIR writes all this information into Dataverse, and none of the updates flow back into the FHIR system.

    A screenshot showing a sample entity map creation.

  6. For Supported Messages, select the valid actions for the data to flow back to the FHIR system. You can select Create, or Update, or both.

    • If you select Create, a record is also created in FHIR when a record is created in Dataverse.
    • If you select Update, each record change in Dataverse is also updated in FHIR.

    For this example that uses the Contact entity, select only Update.

    Note

    For a Patient resource or a Contact entity, only the Update action is supported.

  7. Select Save.

The system captures changes in Azure FHIR when the Contact entity is updated.

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

Important

We recommend that you don't create new patients in Dataverse. Always add new patients in your FHIR system, and let the Dataverse healthcare APIs create the corresponding Dataverse records.

Patients are the core resource (entity) in FHIR. Every other resource in FHIR relates to the Patient resource or entity. FHIR systems automatically assign a unique ID when you add a new patient. This ID attribute is read-only. If you try to create a new patient record in Dataverse, Dataverse can't assign a value to the Patient ID attribute in FHIR. So, the Dataverse healthcare APIs can't write the data changes to your FHIR system.

When you add a new patient in your EMR system, the data change flows to the Azure FHIR server, and then to Dataverse. Then, you can add related records, such as encounters, appointments, and observations.