Configure Dataverse healthcare APIs
This article provides a step-by-step guide for configuring the Dataverse healthcare APIs.
Grant an Azure application access to the Dataverse environment
The first step to enable access to the Dataverse healthcare APIs is to grant an Azure application permission to the Dataverse environment. These steps guide you through setting up an App registration in Azure, and then granting that application access to Dataverse by setting up an application user.
Register an application with the Microsoft identity platform. After you configure the app registration, make sure you capture the Application/Client ID.
In the Power Platform admin center, open your Dataverse environment.
On the action pane, select Settings.
Under Users + Permissions, select Application users.
On the action pane, select New app user.
In the panel that opens, select Add an app.
Search by using your Application/Client ID, select your app, and then select Add.
Select your Business unit.
Select the Sync admin for FHIR App Reg User security role, and then select Save.
Select Create.
Configure integration settings
The data integration toolkit integration settings give you access to Dataverse environment variables that you can use to configure the Dataverse healthcare APIs.
With writeback support, you can configure entity maps for Dataverse records to be written back to the remote server. After configuration, new records created in Dataverse or records created using the Dataverse healthcare inbound APIs can be updated and posted to the remote endpoint.
In addition to the configuration steps, the following section also describes the integration settings required to connect to the remote endpoint for writeback events. To access the integration settings in data integration toolkit:
Sign in to Microsoft Power Apps.
On the Environments pane, select the environment where you deployed data integration toolkit.
On the left pane, select Apps, and then select Data Integration Toolkit.
Under Application Config, select Integration Settings, and then select Dataverse Healthcare API.
Set the variables with values for your environment.
The settings for Dataverse healthcare APIs are categorized into the following two sections:
- General Settings: Covers logging and ingestion settings.
- Write Back Configuration: Covers connectivity and retry settings for the remote writeback endpoint.
General settings
The following table describes the general environment variable settings:
| Name | Description | Value |
|---|---|---|
| Logging Level | Controls the level of information logged to Dataverse for both the inbound Dataverse healthcare API and writeback events. By default, the value is set to Disabled. For more information, go to Review Dataverse healthcare API logs. |
Use one of the following values: Information Only: Log details marked as information. Warning Only: Log details marked as warning. Exception Only: Log details marked as error or exception. Verbose: Log all details. Disabled: Disable logging. |
| FHIR Bundle Size Limit for Upsert | The maximum number of resources in a bundle. By default, the value is 100. | Use a value from 1 through 500 to control the maximum number of resources in a valid bundle. If the bundle size exceeds the configured limit, the upsert bundle API responds with an error. |
Writeback configuration
Writeback messages can be posted to an alternate endpoint instead of the FHIR service, such as an Azure Logic App or an Azure Function that supports Open Authorization (OAuth). The writeback settings enable you to provide connection details for the FHIR endpoint and an alternate outbound endpoint (if available) for posted messages. You need the FHIR service values for validating and constructing the outbound FHIR messages. These connection values are optional, and if provided, the messages are posted as a FHIR Bundle to this endpoint.
The following sections describe the environment variable settings for the writeback solution configuration. You can select which values to configure based on your usage scenario.
FHIR service settings
These settings constitute the settings specific to a FHIR service, such as an Azure Health Data Services FHIR service.
| Name | Description | Value |
|---|---|---|
| Application/Client ID | The application registration user ID configured for the FHIR service to which the writeback service connects. | Application Registration User ID (GUID) |
| Client Secret | The client secret associated with the application registration user ID. Note: For security, you can't use the administration tools to access the client secret value after saving it. |
Client Secret (string) |
| Resource | The Resource or Scope string of the FHIR service used to acquire the authentication token. For the Azure Health Data Services FHIR service, this value is typically the same value as the endpoint URL. |
String, or properly formatted URL |
| Endpoint Base URL | The URL of the FHIR service to which the writeback service connects. | Properly formatted URL |
| Authority URL | The URL of the OAuth authority provider, including the tenant ID. The writeback service uses this URL to acquire the auth token for the given client ID and secret. | Properly formatted URL |
Alternate outbound endpoint settings
These settings constitute the settings specific to an alternate writeback endpoint, such as a Logic App. The alternate outbound endpoint must support authentication via OAuth 2.0 using a Client ID and Client Secret, and should be configured with an HTTP trigger.
| Name | Description | Value |
|---|---|---|
| Application/Client ID | The application registration user ID configured for the remote endpoint to which the writeback service connects. | Application Registration User ID (GUID) |
| Client Secret | The client secret associated with the application registration user ID. Note: For security, you can't use the administration tools to access the client secret value after saving it. |
Client Secret (string) |
| Resource | The Resource or Scope string of the remote endpoint used to acquire the authentication token. For the Azure Health Data Services FHIR service, this value is typically the same value as the endpoint URL. | String, or properly formatted URL |
| Endpoint Base URL | The URL of the remote endpoint to which the writeback service connects. | Properly formatted URL |
| Authority URL | The URL of the OAuth authority provider, including the tenant ID. The writeback service uses this URL to acquire the auth token for the given client ID and secret. | Properly formatted URL |
Important
When you use an alternate endpoint such as an Azure Function or Logic App, make sure that you configure the endpoint with an HTTP trigger. When the writeback service posts to this location, it also sends a FHIR Bundle containing the FHIR resource that's created or updated and a FHIR provenance message.
The writeback service expects a bundle containing the response from the remote FHIR service as a response from the remote FHIR endpoint. This response is needed to update the Dataverse record with the new FHIR version ID and the last modified values. For examples on expected responses, see Write back to an alternate endpoint.
General writeback settings
| Name | Description | Value |
|---|---|---|
| Max Retry Timeout | The maximum number of minutes between automatic retries before failing a message. | Retry timeout (minutes) Default value: 5 |
| Max Retry Count | The maximum number of retries before failing a message. | Number of retries (count) Default value: 3 |
| FHIR Application Registration User ID | The application registration user ID configured for inbound message processing. This variable allows the writeback processor to filter the inbound messages and avoid circular processing. | Application Registration User ID (GUID) |
Configure data ingestion
After you update the integration settings, you can post FHIR bundles directly to the custom API endpoint. Or, you can deploy a Logic App to help with relaying the data between Dataverse and the Azure Health Data Services FHIR service. For more information, see:
- Post data directly to Dataverse Healthcare APIs.
- Create a Logic App through manual configuration to sync data between Dataverse healthcare APIs and Azure Health Data Services.
- Deploy a group of Logic Apps using a template to orchestrate ingestion of FHIR bundles into Dataverse healthcare APIs and Azure Health Data Services.