Overview of writeback for Dataverse healthcare APIs
The Dataverse healthcare upsert API facilitates the ingestion of FHIR (Fast Healthcare Interoperability Resources) 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:
- You update 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, you can specify an alternate writeback approach if needed.
- Dataverse sends the FHIR resource request to the defined endpoint.
- The defined endpoint is responsible for processing the posted FHIR resource and sending it to the FHIR API.
- You're 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 assumes 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. We've tested and validated this configuration 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. It also describes 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
Provide the connectivity details for the FHIR endpoint that receives the posted FHIR resources. You can find these configuration values in the data integration toolkit's 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 you enable writeback for the entity map, the administrator can select which events trigger the writeback process, indicated by the Supported Messages 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 extra configuration setting for writeback. Patients can choose to consent or deny their data being updated from the Dataverse application. The Azure FHIR Sync Enabled attribute saves this consent for each patient.
When the value of the Azure FHIR Sync Enabled attribute is set to Yes and the Patient entity map is configured for writeback, any changes to the mapped attributes are 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 details 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 might be incorrect.
Message processed with warnings
The FHIR endpoint might return some warnings or information messages even if the writeback request is processed successfully. The child logs for this warning message 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, you must correctly set the indicator of the Contact Type for writeback to succeed. For example, you must set it 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 only to endpoints that use OAuth authentication.