Overview of Dataverse healthcare APIs

Article
10/27/2023

The Dataverse healthcare APIs are a full product offering from Microsoft Cloud for Healthcare that enables you to interact with Dataverse by using the FHIR standard. The APIs use the Data integration toolkit maps to transform the bundles between FHIR and Dataverse.

These APIs are implemented as Dataverse APIs designed to accept FHIR bundles as input parameters. The APIs handle the mapping and transformation of individual FHIR resources and post the resulting records into Dataverse. You can authenticate to and secure these endpoints as you would with the standard Dataverse APIs.

Note

To read more about standard Dataverse APIs, go to Create and use custom APIs.

The Dataverse healthcare APIs can be used 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 Azure FHIR sync agent tooling that has been retired.

Important

Effective October 2023, Azure FHIR Sync Agent has been officially retired. It won't be included in the Data integration toolkit and won't be supported as a Microsoft Cloud for Healthcare solution.

Using the provided logic app isn't a requirement for using the Dataverse healthcare APIs. You can build your own Azure Logic App, use Power Automate, or develop your own custom code. There's also no requirement to synchronize data with an external FHIR service. You can synchronize with 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 that are 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 to ingest FHIR data into Dataverse healthcare APIs, Azure Health Data Services, or both.
Use Healthcare data pipeline template to deploy Azure Logic Apps	Provides a step-by-step guide for using a template to deploy a group of Logic Apps that orchestrate ingestion of FHIR bundles into Dataverse healthcare APIs and Azure Health Data Services
Use the Dataverse healthcare APIs	Summarizes how to invoke and use the Dataverse healthcare APIs, with some 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

The following APIs are currently available as part of the Dataverse healthcare APIs:

Upsert bundle API
Retrieve bundle API

Upsert bundle API

The upsert bundle API enables sending FHIR bundles to Dataverse and transforming them into Dataverse records.

The API currently supports the following capabilities:

Ingestion of both single and mixed resource bundles. A single resource bundle contains only one resource type, whereas a mixed one contains several resource types.
Ingestion of batch bundle types. For more information, go to Supported bundle types.
Ingestion of bundles with Uniform Resource Name (URN) reference.
Ensuring the 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 upsert bundle 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).

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 has been 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 has been created.
935000001	A root resource already existing in Dataverse has been 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 only bundles of the type batch and batch-response. If you're attempting to ingest bundles of the types that aren't supported, you need to change the type on 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 would process the bundle as a group of independent actions.

When you change the bundle type to batch, it's important to carefully 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 currently supports the following capabilities:

Querying for a single record using FHIR ID.
Verbose and localized logging.

The retrieve bundle 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.

Note

Future Dataverse healthcare API releases will include investments for retrieving additional FHIR resources and additional filtering capabilities.

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.

For information on how to configure the Dataverse healthcare APIs, go to Configure Dataverse healthcare APIs.