Exercise - Use Dataverse Healthcare APIs with Insomnia

Completed

In this exercise, you set up Insomnia to call Dataverse Healthcare APIs to send a Patient FHIR resource bundle to Dataverse and then retrieve data from Dataverse. To complete this exercise, you need to have Insomnia installed locally.

Note

Insomnia introduces the workspace concept to enable you and your team to share APIs, collections, documents, and other components. You can use the default workspace, or create a local or remote workspace for you or your team. In this exercise, you'll create an environment and collection in the default workspace. For more information, see the Insomnia documentation.

Task: Register a Microsoft Entra ID app

In this task, you register a Microsoft Entra ID app to authenticate Insomnia with Dataverse. Grant the Sync Admin for FHIR App Reg User security role to this app so that it can call the Dataverse Healthcare APIs to write to and read from Dataverse. This app uses the implicit grant flow to obtain an access token from Microsoft Entra ID to authenticate Insomnia; hence, you don't need to create a secret for this app. For more information, see Token grant flows.

1. Follow the steps from Microsoft Cloud for Healthcare training environment preparation to register a Microsoft Entra ID app.

2. Set up the Microsoft Entra ID app by using the following details:

   • Name - Lamna Healthcare Integration App

   • Supported account types - Accounts in this organizational directory only

3. After registering the Microsoft Entra ID app, copy its Client ID and then provide the following API permission:

   • API Name - Dynamics CRM

   • Permissions type - Delegated permissions

   • Permission - user_impersonation

4. On the left pane, select Authentication.

5. On the right pane, select + Add a platform.

6. Select Web.

7. On the Configure Web panel, enter the following values and then, select Configure.

   • Redirect URIs - https://insomnia.rest/

   • Select the tokens you would like to be issued by the authorization endpoint - Access tokens (used for implicit flows)

   

8. Select Manifest on the left pane to update the allowPublicClient to true in the manifest file.

   

9. Select Save.

Task: Grant Microsoft Entra ID app permission on Dataverse

In this task, you grant permission to the registered Microsoft Entra ID app on Dataverse.

1. While signed in to your Microsoft 365 tenant as global administrator, open a new tab and then go to Microsoft Power Platform admin center.

2. On the left navigation pane, select Environments.

3. On the right pane, select Lamna Healthcare environment.

4. Select Settings from the command bar.

5. On the Settings page, select Users + permissions > Application users.

6. Select + New app user.

7. On the Create a new app user panel, select + Add an app.

8. On the Add an app from Microsoft Entra ID panel, use the search box to search for Lamna Healthcare Integration App by using its client ID that you copied in a previous step.

9. Select Lamna Healthcare Integration App and then select Add.

10. After adding the Microsoft Entra ID app, you'll be redirected to the Create a new app user panel. Select the ID from the Business unit dropdown menu, and then select the edit icon beside the Security role option.

11. In the Add security roles pane, select Sync admin for FHIR App Reg User, and then select Save.

12. You're redirected to the Create a new app user panel. Select Create to add Lamna Healthcare Integration App as an application user and then assign it the Sync admin for FHIR App Reg User security role.

Task: Get a Dataverse access token by using the Implicit grant type

In this task, you set up Insomnia to use Dataverse Healthcare API.

1. Install Insomnia on your computer, and launch the application. For more information, see Install Insomnia.

2. Select the settings icon next to Base environment.

3. Enter Dataverse-Healthcare-APIs as the name for the new environment.

4. Add the following variables in the Dataverse-Healthcare-APIs environment, and then select Save.

   • client_id - Enter the client ID of the Lamna Healthcare Integration App that you copied previously

   • url - https://<Dataverse-environment-name>.api.crm.dynamics.com

   • callback - https://insomnia.rest/

   • authurl: https://login.microsoftonline.com/common/oauth2/authorize?resource={{url}}

   

5. Select the + icon and select HTTP request.

   

6. Name the request to GetDataverseAccessToken.

7. Select Auth tab and then set up authentication type as OAuth 2.0

   

8. On the right pane, in the Configure New Token section, fill in the following details:

   • Grant Type - Implicit

   • Authorization URL - Enter {{authurl}}

   • Client ID - Enter {{client_id}}

   • Redirect URL - Enter {{callback}}

   

9. Scroll down and select Fetch token. At the prompt, select Accept.

10. After the Fetch token completes, you can view the token in the following section:

    

Important

You can also use the Client Credential grant flow to obtain an access token from Microsoft Entra ID to authenticate Insomnia. To do so, follow these steps:

1. Register a Microsoft Entra ID app.

2. Create a client secret for the app.

3. Grant the Microsoft Entra ID app with the Sync admin for FHIR APP Reg User permission on Dataverse.

4. In Insomnia, on the right pane in the Configure New Token section, use the following values:

   • Grant Type - Client Credentials

   • Access Token URL - https://login.microsoftonline.com/{{tenant_id}}/oauth2/v2.0/token

   • Client ID - Enter the Client ID of the registered Microsoft Entra ID app

   • Client Secret - Enter the Client Secret of the registered Microsoft Entra ID app

   • Scope - https://<Dataverse-env>.crm.dynamics.com/.default

Use the msind_UpsertBundle API

In this task, you use the msind_UpsertBundle API to create a record in the Contact entity of Dataverse. You use the Patient FHIR resource bundle as JSON payload.

1. Create a new HTTP request.

2. Name the new request to msind_UpsertBundle_Patient as you're posting the Patient FHIR bundle to the endpoint.

3. Select POST as the HTTP operation type.

4. Set the request URL to https://<Dataverse-environment-name>.crm.dynamics.com/api/data/v9.1/msind_UpsertBundle.

5. In the Bearer tab,

   • Select Token - Paste the token from the previous task.

   

   Note

   You can use the /api/data/v9.1/msind_UpsertBundle or the /api/data/v9.2/msind_UpsertBundle endpoint in your API call.

6. Select the Headers tab and then add the following two request headers:

   • Content-Type - application/json; charset=utf-8

   • OData-Version - 4.0

7. Select the Body tab.

8. Select JSON.

9. Use the following FHIR bundle as JSON payload.

    {
        "msind_BundleTag": "PatientDatatest",
        "msind_JSON": "{\"resourceType\":\"Bundle\",\"type\":\"batch\",\"entry\":[{\"resource\":{\"resourceType\":\"Patient\",\"id\":\"b7777777-b777-b777-b777-b77777777777\",\"text\":{\"status\":\"generated\"},\"identifier\":[{\"system\":\"https://github.com/synthetichealth/synthea\",\"value\":\"51978986-f824-43da-b69a-d2d17f49df70\"}],\"name\":[{\"use\":\"official\",\"family\":\"Contoso\",\"given\":[\"Allen\"],\"prefix\":[\"Ms.\"]}],\"telecom\":[{\"system\":\"phone\",\"value\":\"555-664-6121\",\"use\":\"home\"}],\"gender\":\"female\",\"birthDate\":\"1965-11-04\",\"address\":[{\"extension\":[{\"url\":\"http://hl7.org/fhir/StructureDefinition/geolocation\",\"extension\":[{\"url\":\"latitude\",\"valueDecimal\":42.605887766784662},{\"url\":\"longitude\",\"valueDecimal\":-71.0695322588603}]}],\"line\":[\"165 Shanahan View\"],\"city\":\"North Reading\",\"state\":\"Massachusetts\",\"country\":\"US\"}],\"multipleBirthBoolean\":false},\"request\":{\"method\":\"POST\",\"url\":\"Patient\"}}]}"
    }
   

   

10. Select Send.

    After successful implementation of the API request, Dataverse will respond with the HTTP Status code 200 OK.

    

11. Verify the new patient record in Dataverse, go to Microsoft Power Apps portal, and then select your environment.

12. Select Dataverse > Tables > Contact entity to find the newly created patient record.

    

Use the msind_RetrieveBundle API

In this task, you use Insomnia to call the msind_RetrieveBundle Dataverse Healthcare API. This API accepts FHIRResource/ID to look for the respective FHIR resource in Dataverse, and if found, it returns the resource with HTTP Status code 200.

1. Create a new HTTP request.

2. Name the new request to msind_RetrieveBundle_Patient because you're fetching the Patient FHIR resource from Dataverse.

3. Select POST as the HTTP operation type.

4. Set the request URL to https://<Dataverse-environment-name>.crm.dynamics.com/api/data/v9.1/msind_RetrieveBundle.

5. Set up the authentication as mentioned in the previous Task - Get a Dataverse access token by using the Implicit grant type.

   Note

   You can use the /api/data/v9.1/msind_RetrieveBundle or the /api/data/v9.2/msind_RetrieveBundle endpoint in your API call.

6. Select the Headers tab and then add the following two request headers:

   • Content-Type - application/json; charset=utf-8

   • OData-Version - 4.0

7. Select the Body tab.

8. Select JSON.

9. Use the following FHIR bundle as JSON payload.

    {
        "msind_FHIRQuery": "Patient/b7777777-b777-b777-b777-b77777777777"
    }
   

   

10. Select Send.

On successful implementation of the API request, Dataverse responds with the HTTP Status code 200 OK.

You successfully used the Dataverse Healthcare APIs by using Insomnia to create a new record in the Contact entity in Dataverse, and then you retrieved the newly created entity from Dataverse.