Overview of writeback for Dataverse healthcare APIs
The Dataverse healthcare upsert API facilitates the ingestion of FHIR data into Dataverse. After data is available in Dataverse, users can update the new records, such as updating patient demographic information. The Dataverse healthcare APIs writeback solution allows these changes to be posted back to the originating FHIR server.
The solution approach offers some extensibility to the writeback process. The writeback configuration can also target an alternate endpoint if users need to inject custom logic into this process. For example, a custom Azure Logic App can be targeted for the outbound message that performs further processing or routing. This alternate outbound endpoint must support authentication via OAuth 2.0 using a client ID and client secret.
The following diagram outlines the overall writeback process:
The standard processing steps are as follows:
- The user updates a record in Dataverse.
- Dataverse evaluates the change, and composes a new FHIR resource that is posted to the FHIR API endpoint.
- The FHIR endpoint processes the FHIR resource and returns the operation outcome response to Dataverse.
- Dataverse logs the operational outcomes to the Data integration toolkit logs. The administrator can review any failures here.
For extensibility, users can specify an alternate writeback approach if needed.
- Dataverse sends the FHIR resource request to the user defined endpoint.
- The user defined endpoint is responsible for processing the posted FHIR resource and sending it to the FHIR API.
- The user is responsible for logging the operational outcomes, so that the administrator can review any failures while sending data to the custom endpoint.
Note
The current version of Dataverse healthcare APIs and the writeback process assume that a FHIR service is available for creation and validation of the outbound FHIR resource. This setup is required for both writing directly to the FHIR service or to an alternate outbound endpoint. It ensures integrity of the outbound FHIR resource when a writeback event occurs. This configuration has been tested and validated against an Azure Health Data Services FHIR service.
A FHIR Provenance record is also posted to the FHIR endpoint when the writeback event is processed. The provenance resource tracks information about the activity that created, revised, deleted, or signed a version of a resource, describing the entities and agents involved. You can use this information to form assessments about its quality, reliability, or trustworthiness. It also provides pointers for where to go to further investigate the origins of the resource and the information in it.
For more information on FHIR provenance, go to FHIR Resource Provenance.
Enable writeback
Enabling the writeback process includes the following three primary steps:
Provide connectivity details
The first step to configure writeback is providing the connectivity details for the FHIR endpoint that receives the posted FHIR resources. You can find these configuration values in the Data integration toolkit Integration settings section.
For more information on these settings, go to Configure integration settings.
Update entity maps
After providing connectivity details, the next step is to update the entity maps that control which FHIR resources should participate in the writeback process.
The writeback plug-ins use the same entity maps configured for the upsert API. Each entity map can include an attribute titled Enable writeback to FHIR. When this attribute value is set to Yes, the writeback plug-ins post updates for the selected Dataverse table to the FHIR endpoint. This process allows for granular, table-by-table control over what data should be written back to the FHIR endpoint.
After writeback is enabled for the entity map, the administrator can choose which events will trigger the writeback process, indicated by the Supported Messages form field. The writeback solution currently supports Create and Update messages.
For more information on how to configure the entity maps, go to Configure entity maps.
Apply patient consent
Patient resources include an additional configuration setting for writeback. Patients can choose to consent or deny their data being updated from the Dataverse application. This consent is saved for each patient in the Azure FHIR Sync Enabled attribute.
When the value of the Azure FHIR Sync Enabled attribute is set to Yes, and if the Patient entity map is configured for writeback, any changes for attributes that have been mapped would be posted to the FHIR endpoint. Otherwise, the writeback plug-ins ignore the patient record changes.
Common warnings and error scenarios
Warnings and exceptions that might occur during the writeback process are logged to the Data integration toolkit logs. For more information about the logs, go to Review Dataverse healthcare API logs.
Invalid configuration settings
If the connectivity settings provided in the integration settings section are incorrect, the writeback process logs an exception and stops processing. For example, the Application/Client ID or the Client Secret values could be incorrect.
Message processed with warnings
The FHIR endpoint could return some warnings or information messages even if the writeback request is processed successfully. The child logs for this warning message would contain more details for administrators to review.
FHIR provenance errors
Any exception related to the creation of the FHIR provenance record is logged with a general exception along with the details returned by the FHIR endpoint.
Missing required attributes
The writeback processing for expansion maps requires a reference to the parent record. If the parent link attribute value is missing, the writeback process logs an exception and stops processing.
Invalid contact type
For contact records in Dataverse, the indicator of the Contact Type must be set correctly for writeback to succeed. For example, they must be set to either Patient or Practitioner. If this value isn't present, the writeback process logs an exception and stops processing.
Limitations
The writeback solution currently has the following limitations:
- Outbound formatting: The writeback solution doesn't support outbound formatting. The process currently posts the FHIR resource representing the changes for the updated FHIR resource in Dataverse.
- Authentication: The writeback solution currently supports posting to endpoints that only support OAuth authentication.
See also
What is Microsoft Cloud for Healthcare? Overview of Data integration toolkit Overview of Dataverse healthcare APIs Configure Dataverse healthcare APIs Review Dataverse healthcare API logs