Overview of Dataverse healthcare APIs
Dataverse healthcare APIs from Microsoft Cloud for Healthcare let you interact with Dataverse using the FHIR (Fast Health Interoperability Resources) standard. The APIs use data integration toolkit maps to transform bundles between FHIR and Dataverse.
These APIs accept FHIR bundles as input parameters. The APIs handle the mapping and transformation of individual FHIR resources and post the resulting records into Dataverse. Authenticate and secure these endpoints as you would with standard Dataverse APIs.
Note
To learn more about standard Dataverse APIs, go to Create and use custom APIs.
Use Dataverse healthcare APIs to:
- Post FHIR-based data directly into Dataverse.
- Synchronize Dataverse with external FHIR services such as Azure Health Data Services.
These APIs combined with Azure Logic Apps constitute Microsoft Cloud for Healthcare's replacement for the retired Azure FHIR sync agent tooling.
You don't need to use the provided logic app to use Dataverse healthcare APIs. You can build your own Logic App, use Power Automate, or develop your own custom code. You don't need to synchronize data with an external FHIR service. You can synchronize with the Azure Health Data Services FHIR endpoints or post data directly into the APIs. The Dataverse healthcare APIs are meant to be a flexible component that can be used for designing your healthcare solutions around Microsoft Cloud for Healthcare.
| Section | Content |
|---|---|
| Dataverse healthcare APIs | Summarizes information about the APIs currently available as part of the Dataverse healthcare APIs. |
| Overview of writeback for Dataverse healthcare APIs | Explains the writeback process for Dataverse healthcare APIs. |
| Configure Dataverse healthcare APIs | Contains steps for configuring the Dataverse healthcare APIs. |
| Configure Azure Logic App with an HTTP trigger | Contains a detailed step-by-step guide for creating your own Logic App that can ingest FHIR data into Dataverse healthcare APIs, Azure Health Data Services, or both. |
| Use the Dataverse healthcare APIs | Summarizes how to invoke and use the Dataverse healthcare APIs, with examples and common usage scenarios. |
| Review Dataverse healthcare API logs | Explains how to review the transaction logs for Dataverse healthcare API activities. |
Dataverse healthcare APIs
Dataverse healthcare APIs currently offer the following APIs:
- Upsert bundle API
- Retrieve bundle API
Upsert bundle API
The upsert bundle API lets you send FHIR bundles to Dataverse and transform them into Dataverse records.
The API supports:
- Ingesting both single and mixed resource bundles. A single resource bundle contains one resource type, while a mixed one contains several.
- Ingesting batch bundle types. For more information, see Supported bundle types.
- Ingesting bundles with Uniform Resource Name (URN) references.
- Referential integrity of FHIR bundles: A resource would be created in Dataverse only if all of its references are resolved.
- Creation of expanded records for each FHIR resource in Dataverse.
- Creation of codeable concepts when they're missing in Dataverse.
- Verbose and localized responses.
The API (msind_UpsertBundle) has two request parameters defined as follows:
| Request parameter | Description |
|---|---|
| msind_JSON | The FHIR bundle that needs to be inserted (required value). |
| msind_BundleTag | A tag that helps in identifying the bundles when parsing the logs in Dataverse (optional value). |
| msind_DisableJITCreate | A tag that provides a bundle-level override of the attribute map value for Enable in JIT Create. Use this optional parameter for migration scenarios or situations where performance is a concern while importing large datasets. |
To learn how to invoke the API and review some common usage scenarios, go to Invoke the upsert bundle API from the web API.
After API invocation, you can expect the following elements in the JSON response:
| Response parameter | Description |
|---|---|
| msind_Status | A Boolean indicating whether the bundle was successfully processed and all valid resources were upserted into Dataverse. |
| msind_StatusDetail | Provides detailed information about the msind_Status value. |
| msind_fhirresourceid | The FHIR ID of the resource in the bundle. If an entry in the result pertains to an expanded record, the value is the FHIR ID of the root resource. |
| msind_fhirresourcetype | The FHIR resource type of the resource in the bundle. If an entry in the result pertains to an expanded record, the value is the FHIR resource type of the root resource. |
| msind_resultingrecordid | The Dataverse ID after the record is upserted. If an entry in the result pertains to an expanded record, the value is the Dataverse ID of the root resource. |
| msind_resultingrecordtype | The name of the Dataverse entity that the record was upserted into. If an entry in the result pertains to an expanded record, the value is the name of the Dataverse entity of the expanded record. |
| msind_requestactionperformed | The type of action performed. To view the expected values and their description, go to Types of request actions performed. |
| msind_requeststatus | The status of the request. To view the expected values and their description, go to Types of request status. |
| msind_requeststatusdetail | Detailed information about the msind_requeststatus value. |
Types of request actions performed
The following table lists the expected values for the msind_requestactionperformed response parameter:
| Value | Description |
|---|---|
| 935000000 | A root resource is created. |
| 935000001 | A root resource already existing in Dataverse is updated. |
| 935000002 | The action was performed on an expanded entity. |
Types of request status
The following table lists the expected values for the msind_requeststatus response parameter:
| Value | Description |
|---|---|
| 935000000 | The resource upsert resulted in a success. |
| 935000001 | The resource upsert resulted in a warning. |
| 935000002 | The resource upsert resulted in an error. |
Supported bundle types
The upsert bundle API currently supports bundles of the type batch and batch-response. To ingest bundles of the types that aren't supported, you first need to change the type of the bundle that you're submitting. If you want to change the bundle type to batch before posting to the APIs, you can use the logic app built-in replace action to change the bundle type. This step processes the bundle as a group of independent actions.
When you change the bundle type to batch, it's important to consider the effect that it might have on your individual scenarios. Changing a transactional bundle to batch could have undesired effects on the data that you're attempting to bring into Dataverse. For more information on the rules for using these bundles, go to HL7 FHIR - Using bundles.
If you submit a bundle of the type batch-response, the Dataverse healthcare API logs resources of the type OperationOutcome with severity value error to the logs. This action allows you to post the bundle to a FHIR server, and pipe the response from the FHIR server to the Dataverse healthcare API. As a result, you can capture all the errors in one place.
Retrieve bundle API
The retrieve bundle API enables you to query Dataverse for a single FHIR resource using the FHIR ID. The API transforms the request and uses the data integration toolkit maps to respond with a FHIR standardized resource.
The API supports:
- Querying for a single record using FHIR ID.
- Verbose and localized logging.
The API (msind_RetrieveBundle) has one request parameter defined as follows:
| Request parameter | Description |
|---|---|
| msind_FHIRQuery | The FHIR query to execute (required value). |
Supported FHIR queries
| Query | Description |
|---|---|
| FHIRResource/FHIRID | The query returns the entire resource along with the expanded entities. |
| FHIRResource/FHIRId?_elements=element_1,element_2,...,element_n | The query returns the elements specified in the query along with any elements marked as FHIR Required on the attribute map. For more information, go to FHIR element search. |
To learn how to invoke the API and review some common usage scenarios, go to Invoke the retrieve bundle API from the web API.
After API invocation, you can see a response containing the status of the complete request, and the detailed status of each resource and its expanded elements.
| Response parameter | Description |
|---|---|
| msind_Status | A Boolean indicating whether the action was successfully processed. |
| msind_StatusDetail | Provides detailed information about the msind_Status value. |
| msind_JSON | FHIR JSON representation. |