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 first 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 Azure application. After you configure the app registration, make sure you capture the Application/Client ID for the following steps.
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 integration settings area in Data integration toolkit gives 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 available 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
This collection of settings enables you to provide connection details for the FHIR endpoint and an alternate outbound endpoint (if available) for posted messages.
The FHIR service values are required for validation and for constructing the outbound FHIR messages. If you only provide these connection values, the messages are also posted to this endpoint.
Writeback messages may 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). These values are optional, and if provided, the messages are posted as a FHIR Bundle.
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 access the client secret value using the administration tools after saving it. |
Client Secret (string) |
| Resource | The Resource or Scope string of the FHIR service used in acquiring 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.
| 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 access the client secret value using the administration tools after saving it. |
Client Secret (string) |
| Resource | The Resource or Scope string of the remote endpoint used in acquiring 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 |
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.
See also
What is Microsoft Cloud for Healthcare?
Overview of Data integration toolkit
Overview of Dataverse healthcare APIs
Overview of writeback for Dataverse healthcare APIs
Use the Dataverse healthcare APIs