Use the Dataverse healthcare APIs

Article
06/08/2023

The Dataverse healthcare APIs contain custom-built API endpoints that allow you to exchange FHIR data with Microsoft Cloud for Healthcare. This article explains how to use the Dataverse healthcare upsert and retrieve bundle APIs and also covers some common usage scenarios.

For more information about these APIs, go to Overview of Dataverse healthcare APIs.

Invoke the upsert bundle API from the web API

The upsert bundle API schema name is msind_UpsertBundle. It has two request parameters and can be invoked as follows:

POST [Organization URI]/api/data/v9.1/msind_UpsertBundle 
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8 

{
  "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).>"
}

The response contains the status of the complete request, and the detailed status of each resource and its expanded elements.

{
    "msind_Status": "<A Boolean indicating whether the bundle was successfully processed and all valid resources were upserted into Dataverse.>",
    "msind_StatusDetail": "<Provides information about the msind_Status value.>",
    "msind_Results": [
        {
            "msind_fhirresourceid": "<The FHIR ID of the resource in the bundle. If an entry in the result pertains to an expanded record, the value will be 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 will be 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 will be 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 will be the name of the Dataverse entity of the expanded record.>",
            "msind_requestactionperformed": "<The type of action performed.>",
            "msind_requeststatus": "<The status of the request.>",
            "msind_requeststatusdetail": "<Detailed information about the msind_requeststatus value.>"
        ]
    }
}

For detailed information about the msind_requestactionperformed and msind_requeststatus parameters along with their expected values, go to Types of request actions performed and Types of request status.

Common warnings and error scenarios

This section lists some of the commonly seen warnings and errors while using the upsert bundle API.

Entity map is disabled

By default, all the entity maps shipped by Microsoft Cloud for Healthcare are disabled. When you're trying to ingest data for a specific resource, the related entity maps must be enabled. In case the bundle contains resources for which the entity maps haven't been enabled, the response displays a warning as follows:

{
    "msind_StatusDetail": "The upsert bundle transaction completed without errors. Review the related logs for additional details.",
    "msind_Status": true,
    "msind_Results": [
        {
            "msind_requeststatus": 935000001,
            "msind_requeststatusdetail": "Warning: Unable to locate entity map for FHIR Resource: Patient. Ensure you have enabled the map for this resource. Once fixed, resubmit the bundle to re-process this record.",
            "msind_fhirresourceid": "patient1",
            "msind_fhirresourcetype": "Patient"
        }
    ]
}

The msind_Status is marked as true and the msind_requestStatus within msind_Results is marked as 935000001 (Warning). This behavior is because you might have intentionally marked the entity map as disabled to not ingest "Patient" resources even if they're in the bundle.

Invalid map

Attribute maps drive the transformations between Dataverse and FHIR. One of the key elements in attribute maps driving this transformation is the FHIR element map, which expects a JPath. If the JPath is incorrect, the response would be as follows:

{
    "msind_StatusDetail": "Warning: There were records that encountered errors. Inspect the individual records error details.",
    "msind_Status": false,
    "msind_Results": [
        {
            "msind_requeststatus": 935000002,
            "msind_requeststatusdetail": "Error: An error occurred while trying to transform the FHIR resource to the Dataverse record. Target table: contact. Exception detail: Unexpected end of content while loading JObject. Path 'c', line 1, position 112.
             Table: contact
             Attribute Map Id: f8ce8297-b4fe-ea11-a815-000d3a37def4
             Column: mobilephone
             Action: 440670000
             FHIR Map: {'s': '$.telecom[?(@use=='mobile')].value', 'c': {'p': 'telecom[0]', 'a': [{'use': 'mobile'}, {'value': '%'}]}",
            "msind_fhirresourceid": "patient1",
            "msind_fhirresourcetype": "Patient"
        }
    ]
}

The msind_Status is marked as false and the msind_requestStatus within msind_Results is marked as 935000002 (Error). The information in msind_requeststatusdetail helps you identify the incorrect map.

Referential integrity is lost

In each resource in a FHIR bundle, many elements are references to other resources (for more information, go to FHIR References). The upsert bundle API tries to resolve these references when upserting records into Dataverse. If the API fails to resolve any of these references, it fails to upsert the record, and ensures that the referential integrity isn't lost. In such a scenario, the response would be as follows:

{
    "msind_StatusDetail": "Warning: There were records that encountered errors. Inspect the individual records error details.",
    "msind_Status": false,
    "msind_Results": [
        {
            "msind_fhirresourceid": "careteam2",
            "msind_fhirresourcetype": "CareTeam",
            "msind_resultingrecordid": "",
            "msind_resultingrecordtype": "",
            "msind_requeststatus": 935000002,
            "msind_requeststatusdetail": "Error: An error occurred while trying to upsert the record. Exception Details: A record with the specified key values does not exist in msemr_encounter entity (-2147088239)."
        } 
    ]
}

Invoke the retrieve bundle API from the web API

The retrieve bundle API (msind_RetrieveBundle) has one request parameter and can be invoked as follows:

POST [Organization URI]/api/data/v9.1/msind_RetrieveBundle
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Content-Type: application/json; charset=utf-8

{
    "msind_FHIRQuery": "<The FHIR query to execute (Required value).>"
}

For the list of supported FHIR queries, go to Supported FHIR queries.

The response contains the status of the complete request, and the detailed status of each resource and its expanded elements.

{
    "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.>"
}

Common warnings and error scenarios

This section lists some of the commonly seen warnings and errors while using the retrieve bundle API.

Invalid FHIR resource ID

Currently, the FHIR query request parameter expects a FHIR ID. If Dataverse doesn't have a record with the FHIR ID, the response would be as follows:

{
  "msind_StatusDetail": {
    "Message": "The request failed due to the following error.",
    "Error": [
      {
        "Message": "Resource type Patient with id <ResourceId> couldn't be found."
      }
    ]
  },
  "msind_JSON": {
    "resourceType": "OperationOutcome",
    "id": "7ee485e2-3797-4ee3-9916-4fc4dd7a6ecd",
    "meta": {
      "lastUpdated": "2022-05-06T15:21:23.8078182+05:30"
    },
    "issue": [
      {
        "severity": "error",
        "code": "not-found",
        "diagnostics": "Resource type Patient with id <ResourceId> couldn't be found."
      }
    ]
  },
  "msind_Status": false
}

Attribute map is disabled

If the FHIR query contains an element search, the retrieve bundle API uses the enabled attribute maps to construct a FHIR JSON. In case any of the attribute maps for the elements in the query are disabled, the response would be as follows:

{
"msind_StatusDetail": {
    "Message": "Request processed successfully with the following warning/information.",
    "Warning": [
      {
        "Message": "Attribute map is disabled for attribute name: msemr_asserter."
      }
    ]
  },
  "msind_JSON": "<FHIR JSON>",
  "msind_Status": true
}

Use the Dataverse healthcare APIs

Invoke the upsert bundle API from the web API

Common warnings and error scenarios

Entity map is disabled

Invalid map

Referential integrity is lost

Invoke the retrieve bundle API from the web API

Common warnings and error scenarios

Invalid FHIR resource ID

Attribute map is disabled

See also

Additional resources