diff --git a/.gitignore b/.gitignore index 7557abe9..15d147f7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,7 @@ # This .gitignore file was automatically created by Microsoft(R) Visual Studio. ################################################################################ + +/samples/.vs /.vs/TS/v17 /.vs diff --git a/samples/sample-postman-queries/README.md b/samples/sample-postman-queries/README.md index 83d477c3..10a3fc2f 100644 --- a/samples/sample-postman-queries/README.md +++ b/samples/sample-postman-queries/README.md @@ -4,10 +4,220 @@ To interact with FHIR data, you can utilize Postman to write FHIR queries to que ## Prerequisites -* Please follow this tutorial first prior to starting this sample: [Access using Postman | Microsoft Learn](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/use-postman). - * If you already have knowledge of how to access the FHIR server using Postman, including [registering the client application to access the FHIR service](https://github.com/microsoft/azure-health-data-services-workshop/blob/main/resources/docs/Postman_FHIR_service_README.md#step-1---create-an-app-registration-for-postman-in-aad) and granting proper [FHIR Data Contributor](https://github.com/microsoft/azure-health-data-services-workshop/blob/main/resources/docs/Postman_FHIR_service_README.md#step-2---assign-fhir-data-contributor-role-in-azure-for-postman-service-client) permissions, you can skip this. * Postman installed locally. For more information about Postman, see [Get Started with Postman](https://www.getpostman.com/). * FHIR service deployed in Azure. For information about how to deploy the FHIR service, see [Deploy a FHIR service](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/fhir-portal-quickstart). +* **User Access Administrator** role for you to be able to do role assignments. + +## Setup Steps + Below are 3 major steps that we will perform to access **FHIR Service** from **Postman**. + +A. Register a client application(App Registration) in Microsoft Entra ID. + +B. Assign **FHIR Data Contributor** role in Azure. + +C. Set up **Environment** and **Collection** in Postman. + +## Step A: Register a client application in Microsoft Entra ID + +1. In the [Azure portal](https://ms.portal.azure.com), select Microsoft Entra ID. +

+ +

+ +2. Select **App registrations** under **Manage** section. +

+ +

+ +3. Select new **App registrations**. + +4. Enter a name for app registration. For Supported account types, select **Accounts in this organization directory only**. Leave the other options as is. +

+ +

+ +5. Select **Register**. + +## Application ID (client ID) +After registering a new application, you can find the application (client) ID and Directory (tenant) ID from the overview menu option. **Make a note of the values for use later(you will need these when you configure your Postman environment)**. +

+ +

+ +

+ +

+ +## Authentication setting: confidential vs. public +Select Authentication to review the settings. The default value for Allow public client flows is "No". + +If you keep this default value, the application registration is a confidential client application and a certificate or secret is required. +

+ +

+ +If you change the default value to "Yes" for the "Allow public client flows" option in the advanced setting, the application registration is a public client application and a certificate or secret isn't required. The "Yes" value is useful when you want to use the client application in your mobile app or a JavaScript app where you don't want to store any secrets. + +For tools that require a redirect URL, select Add a platform to configure the platform. +

+ +

+ +For Postman, select Mobile and desktop applications. Enter "https://www.getpostman.com/oauth2/callback" in the Custom redirect URIs section. Select the Configure button to save the setting. +

+ +

+ +## Certificates & secrets +Select **Certificates & Secrets** and select **New Client Secret**. Select Recommended 6 months in the Expires field. This new secret will be valid for six months. You can also choose different values such as: + +* 03 months +* 12 months +* 24 months +* Custom start date and end date. + +>[!NOTE] +>It is important that you save the secret value, not the secret ID. + +Click on **Certificates and secrets**. Click **+New client secret**. + +

+ +

+ +Under **Add a client secret**, enter a name for the secret in the **Description** field. Click **Add**. + +

+ +

+ +Copy the secret **Value** and securely store it somewhere (you will need this when you configure your Postman environment). + +

+ +

+ +>[!NOTE] +>Use grant_type of client_credentials when trying to obtain an access token for the FHIR service using tools such as Postman or REST Client. + +## Step B: Assign FHIR Data Contributor role in Azure +This section shows the steps to assign **FHIR Data Contruibutor** role to a registered application for the FHIR® service in Azure Health Data Services. + +1. In Azure Portal, go to the resource group containing your FHIR service instance. When in the resource group Overview, click on your FHIR service name in the list. +

+ +

+ +2. Go to the Access Control (IAM) blade. Click on +Add -> Add role assignment. +

+ +

+ +3. In **Add** role assignment under the **Role** tab, scroll down in the list and select **FHIR Data Contributor**. Then click **Next**. +

+ +

+ +4. Under the **Members** tab, click on **+Select members**. Type in the name of your Postman service client app in the **Select** field on the right. Select the app. +

+ +

+ +

+ +

+ +5. In same way, Type in the name of your username in the **Select**. Select your user so it is added to list along with app registration and click **Select**. Then click **Next**. + +

+ +

+ +

+ +

+ +5. Under the **Review + assign** tab, click **Review + assign**. + +

+ +

+ + +## Step C: Set up Environment and Collection in Postman + +### Save collection file and environment file + +1. Access the Postman environment template for FHIR service [here](./fhir-service.postman_environment.json). Save the file locally (click on **Raw** and then do a **Save as** from your browser). + +2. Now, access the ```FHIR Collection.postman-collection.json``` file available in this repo [here](./FHIR-Collection.postman_collection.json) and save the file locally. + + +### Create a workspace, Import collection and environment +Follow these steps to create a workspace, Import collection and environment. + +Postman introduces the workspace concept to enable you and your team to share APIs, collections, environments, and other components. You can use the default My workspace or Team workspace or create a new workspace for you or your team. + +1. Launch the postman app and select **Create Workspace** option from **Workspaces** menu, Select **Blank workpace** and click on **Next**. +

+ +

+ +2. Enter Workspace name in **Name** field and select suitable access level from list and click on **Create**. +

+ +

+ +3. Your workpace is created. +

+ +

+ +4. Click **Import** button to import collection. +

+ +

+ +5. Click on **files** link and browse to the location where are saved and select the collection file ```FHIR Collection.postman-collection.json``` to import collection in Postman. +

+ +

+ +

+ +

+ +6. Collection **FHIR Collection** is imported in workspace. +

+ +

+ +7. Select **Environments** blade, Select **Import**. +

+ +

+ +8. Select **files** blade. +

+ +

+ +9. Browse to the location where files are saved and select environment file ```fhir-service.postman_environment.json```. +

+ +

+ +10. **fhir-service** environment is imported into postman workspace. +

+ +

+ +## Update the evironment values + +Set the values for highlighted fields in **Current value** in the environment and save it. +

+ +

## Collection overview The queries in this collection are categorized into the folders listed below: @@ -42,55 +252,16 @@ The queries in this collection are categorized into the folders listed below: - `FHIR & Terminology Service Integration` - This folder has queries for FHIR and terminology service operations like $lookup, $translate, $validate, $expand, $subsumes, $find-matches and $closure. User need to set up APIM and use APIM url for these queries, please refer [fhir-terminology-service-integration](https://github.com/Azure-Samples/azure-health-data-services-samples/tree/main/samples/fhir-terminology-service-integration) sample. # Getting started -To set up Postman for testing FHIR service, we'll walk through these steps: - -**Step 1:** Import environment template and collection files into Postman -**Step 2:** Enter parameter values for the Postman environment -**Step 3:** Get an authorization token from AAD -**Step 4:** Test FHIR service with Postman - -## Step 1 - Import environment and collection files into Postman +Now we have set up Postman for accessing FHIR service, we'll walk through these steps: -1. Access the Postman environment template for FHIR service [here](./fhir-service.postman_environment.json). Save the file locally (click on **Raw** and then do a **Save as** from your browser). - -2. In Postman, create a new [Workspace](https://www.postman.com/product/workspaces/) (or select an existing one if already created). - -3. Find the **Environments** tab on the left and click the **Import** button next to the workspace name. - - -4. Import the ```fhir-service.postman_environment.json``` file that you just saved locally. - + Add the file to Postman using the **Upload Files** button. Then click **Import**. - - -5. Now, access the ```FHIR Collection.postman-collection.json``` file available in this repo [here](./FHIR-Collection.postman_collection.json) and save the file locally. Then import the file into Postman. - + Add the file to Postman using the **Upload Files** button. Then click **Import**. - - - - -## Step 2 - Configure Postman environment -Now you will configure your Postman environment (`fhir-service`). - -1. For the `fhir-service` Postman environment, fill out the following values in the **CURRENT VALUE** column: - - - `tenantId` - AAD tenant ID (go to **Azure Active Directory** -> **Overview** -> **Tenant ID**) - - `clientId` - Application (client) ID for Postman service client app (go to **Azure Active Directory** -> **App registrations** -> `` -> **Overview** -> **Application (client) ID**) - - `clientSecret` - Client secret stored for Postman that was created when you registered the app in Azure Active Directory. More information [here](https://github.com/microsoft/azure-health-data-services-workshop/blob/main/resources/docs/Postman_FHIR_service_README.md#step-1---create-an-app-registration-for-postman-in-aad) - - `fhirurl` - FHIR service endpoint - e.g. `https://-.fhir.azurehealthcareapis.com` (go to **Resource Group** -> **Overview** -> `` -> **FHIR metadata endpoint** and copy *without* "/metadata" on the end) - - `resource` - FHIR service endpoint - (**same as `fhirurl`**) e.g. `https://-.fhir.azurehealthcareapis.com` - - Populate the above parameter values in your `fhir-service` Postman environment as shown below. Input the values in the **CURRENT VALUE** column. Leave `bearerToken` blank. Make sure to click **Save** to retain the `fhir-service` environment values. - - - -## Step 3 - Get an access token from AAD -To obtain an access token from AAD via Postman, you would typically follow steps outlined [here](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/use-postman#get-azure-ad-access-token), however, for the purposes of this starter collection, we have included the ```POST Get Authorization Token``` call pre-configured. +## Step 1 - Get an access token from AAD In Postman, click on **Collections** on the left, select the `FHIR Collection` collection, open the first folder titled `AuthToken`, and then select `POST Get Authorization Token`. Press **Send** on the right. __IMPORTANT:__ Be sure to make the `fhir-service` environment active by selecting from the dropdown menu above the **Send** button. In the image below, `fhir-service` is shown as the active environment. - +

+

On clicking **Send**, you should receive a response in the **Body** tab like shown below. The `access_token` value is automatically saved to the ```bearerToken``` variable in the Postman environment. @@ -110,25 +281,30 @@ You now have a valid access token in your Postman environment and can use the to __Note:__ Access tokens expire after 60 minutes. To obtain a token refresh, simply make another ```POST Get Authorization Token``` call and you will receive a new token valid for another 60 minutes. -## Step 4 - Query FHIR service with Postman +## Step 2 - Query FHIR service with Postman 1. Try `GET List All Patients` under `Common Queries` folder in the `FHIR Collection` collection and press **Send**. If the response is as shown below, with status "200 Ok" and resourceType as "Bundle", this means you successfully obtained a list of all `Patient` resources stored in the FHIR service database. If there aren't any `Patient` resources in Fhir service, you will get and empty bundle in response as shown below. - +

+

If there are `Patient` resources in Fhir service, you will see Bundle with an array named "entry" in response with list of `Patient` resources as shown in two images below. +

+

Any of the above response means that your setup is functional. 2. Now we will create a [bundle](https://www.hl7.org/fhir/bundle.html) of resources by posting a `Bundle` to the FHIR service. Under the `Create Starter Bundle` folder, click on ```POST Create Resources Bundle (Multiple resources)``` and press **Send**. If the response matches the following, this means you successfully created multiple resources included in a bundle. This bundle contains `Patient`, `Practitioner`, `Organization`, `Location`, `PractitionerRole`, `Encounter`, `Observation`, `Condition`, `Procedure`, `Group`, `Device`, `RelatedPerson` and `ServiceRequest`. These resources will be used as references for creating other resources in the later steps of this tutorial which depend on them. The environment variables for Ids of these resources will be updated. +

+

The following instructions will go through the various folders of the collection in order. @@ -145,9 +321,15 @@ The following instructions will go through the various folders of the collection - Please make sure that the configuration settings for export are set before running export, more details for configurations are available [here](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/configure-export-data) - Below is a sample response from export. In response headers we receive 'Content-Location' header with a url value, this url is used to get status of the export job. - Export: - ' +

+ +

+ - Export Status: +

+

+ - `Delete & Conditional Delete`: The Azure Health Data Services FHIR service supports soft deletes, hard deletes and conditional deletes for resources: - Soft deletes maintain the history of the resource which can used to recreate the resource if needed. - Hard deletes will delete resource along with history so you won't be able to recover. @@ -161,38 +343,51 @@ The following instructions will go through the various folders of the collection - Once you create a new search parameter, reindexing must be done before the new search parameter is available. More information is available at [Test new search Parameters](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/how-to-do-custom-search#test-new-search-parameters). - To perform reindexing, use the `POST Reindex` request. The reindex operation takes some time to finish - the `POST Reindex` request returns a reindex task Id, which can be used to check status of reindex task. +

+

- Keep checking the status of the reindex task with the `GET Get Status on Reindex Job` request. +

+

- Once the reindex is completed, your new search parameter is ready to use. - +

- +

7. Explore the resource specific queries (Create/Update/Get/Delete) in resource specific folders (by resource type in alphabetical order). +

+

- In `FHIR Collection`, the `Get` folder under each resource contains intermediate level queries that combine multiple search parameters and queries to fetch list of resources with multiple IDs. Some examples are shown below: +

+

+

+

8. `Everything` operation for Patient resources - The `$everything` operation for Patient resources returns a patient and related resources. More details are available on the Microsoft Learn page for the [Patient Everything operation](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/patient-everything). Details about response order are available [here](https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/patient-everything#patient-everything-response-order). - `GET $everything Patient by Id` will return a response with `Bundle` having type `searchset`. A successful match returns a bundle with the requested `Patient` resource, one or more related resources, and, if there are more resources to retrieve, a `link` with a `relation` of `next` with the URL for the next set of records as shown in the image below. - + +

+

- If you click the `next` URL in Postman, a new request will be opened. Before sending the request, you need to add the authorization token to it - in the `Auth` tab, select `Bearer Token`. After clicking on send, the response will be a `Bundle` with the type `searchset`. It will contain one or more resources related to the requested patient, and may contain another link to more results (a `link` with a `relation` of `next`), as shown in the image below. +

- +

9. Please check other sample calls or create your own FHIR API calls by following the examples. diff --git a/samples/sample-postman-queries/images/App1.png b/samples/sample-postman-queries/images/App1.png new file mode 100644 index 00000000..3dc30712 Binary files /dev/null and b/samples/sample-postman-queries/images/App1.png differ diff --git a/samples/sample-postman-queries/images/App10.png b/samples/sample-postman-queries/images/App10.png new file mode 100644 index 00000000..3e6a8e86 Binary files /dev/null and b/samples/sample-postman-queries/images/App10.png differ diff --git a/samples/sample-postman-queries/images/App2.png b/samples/sample-postman-queries/images/App2.png new file mode 100644 index 00000000..80d41821 Binary files /dev/null and b/samples/sample-postman-queries/images/App2.png differ diff --git a/samples/sample-postman-queries/images/App3.png b/samples/sample-postman-queries/images/App3.png new file mode 100644 index 00000000..732758d8 Binary files /dev/null and b/samples/sample-postman-queries/images/App3.png differ diff --git a/samples/sample-postman-queries/images/App4.png b/samples/sample-postman-queries/images/App4.png new file mode 100644 index 00000000..baa8ef53 Binary files /dev/null and b/samples/sample-postman-queries/images/App4.png differ diff --git a/samples/sample-postman-queries/images/App5.png b/samples/sample-postman-queries/images/App5.png new file mode 100644 index 00000000..b9e1d1f6 Binary files /dev/null and b/samples/sample-postman-queries/images/App5.png differ diff --git a/samples/sample-postman-queries/images/App6.png b/samples/sample-postman-queries/images/App6.png new file mode 100644 index 00000000..ac0bc9a4 Binary files /dev/null and b/samples/sample-postman-queries/images/App6.png differ diff --git a/samples/sample-postman-queries/images/App7.png b/samples/sample-postman-queries/images/App7.png new file mode 100644 index 00000000..6fac46b4 Binary files /dev/null and b/samples/sample-postman-queries/images/App7.png differ diff --git a/samples/sample-postman-queries/images/App8.png b/samples/sample-postman-queries/images/App8.png new file mode 100644 index 00000000..b4328704 Binary files /dev/null and b/samples/sample-postman-queries/images/App8.png differ diff --git a/samples/sample-postman-queries/images/App9.png b/samples/sample-postman-queries/images/App9.png new file mode 100644 index 00000000..803afe0c Binary files /dev/null and b/samples/sample-postman-queries/images/App9.png differ diff --git a/samples/sample-postman-queries/images/EntraId.png b/samples/sample-postman-queries/images/EntraId.png new file mode 100644 index 00000000..96830945 Binary files /dev/null and b/samples/sample-postman-queries/images/EntraId.png differ diff --git a/samples/sample-postman-queries/images/Env1.png b/samples/sample-postman-queries/images/Env1.png new file mode 100644 index 00000000..ca7752b2 Binary files /dev/null and b/samples/sample-postman-queries/images/Env1.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC1.png b/samples/sample-postman-queries/images/RoleFDC1.png new file mode 100644 index 00000000..b62bfaa2 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC1.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC2.png b/samples/sample-postman-queries/images/RoleFDC2.png new file mode 100644 index 00000000..172278e2 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC2.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC3.png b/samples/sample-postman-queries/images/RoleFDC3.png new file mode 100644 index 00000000..80387609 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC3.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC4.png b/samples/sample-postman-queries/images/RoleFDC4.png new file mode 100644 index 00000000..1ee497e0 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC4.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC5.png b/samples/sample-postman-queries/images/RoleFDC5.png new file mode 100644 index 00000000..9a6b3f88 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC5.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC6.png b/samples/sample-postman-queries/images/RoleFDC6.png new file mode 100644 index 00000000..5da64461 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC6.png differ diff --git a/samples/sample-postman-queries/images/RoleFDC7.png b/samples/sample-postman-queries/images/RoleFDC7.png new file mode 100644 index 00000000..1463d534 Binary files /dev/null and b/samples/sample-postman-queries/images/RoleFDC7.png differ diff --git a/samples/sample-postman-queries/images/SetEnv.png b/samples/sample-postman-queries/images/SetEnv.png new file mode 100644 index 00000000..f479fe35 Binary files /dev/null and b/samples/sample-postman-queries/images/SetEnv.png differ diff --git a/samples/sample-postman-queries/images/fhirurl.png b/samples/sample-postman-queries/images/fhirurl.png new file mode 100644 index 00000000..658b92b9 Binary files /dev/null and b/samples/sample-postman-queries/images/fhirurl.png differ diff --git a/samples/sample-postman-queries/images/postman1.png b/samples/sample-postman-queries/images/postman1.png new file mode 100644 index 00000000..3a5ddd86 Binary files /dev/null and b/samples/sample-postman-queries/images/postman1.png differ diff --git a/samples/sample-postman-queries/images/postman10.png b/samples/sample-postman-queries/images/postman10.png new file mode 100644 index 00000000..91a3b99e Binary files /dev/null and b/samples/sample-postman-queries/images/postman10.png differ diff --git a/samples/sample-postman-queries/images/postman11.png b/samples/sample-postman-queries/images/postman11.png new file mode 100644 index 00000000..efc36f28 Binary files /dev/null and b/samples/sample-postman-queries/images/postman11.png differ diff --git a/samples/sample-postman-queries/images/postman2.png b/samples/sample-postman-queries/images/postman2.png new file mode 100644 index 00000000..627d7a31 Binary files /dev/null and b/samples/sample-postman-queries/images/postman2.png differ diff --git a/samples/sample-postman-queries/images/postman3.png b/samples/sample-postman-queries/images/postman3.png new file mode 100644 index 00000000..d6187c9b Binary files /dev/null and b/samples/sample-postman-queries/images/postman3.png differ diff --git a/samples/sample-postman-queries/images/postman4.png b/samples/sample-postman-queries/images/postman4.png new file mode 100644 index 00000000..af4ac0c9 Binary files /dev/null and b/samples/sample-postman-queries/images/postman4.png differ diff --git a/samples/sample-postman-queries/images/postman5.png b/samples/sample-postman-queries/images/postman5.png new file mode 100644 index 00000000..92cada6a Binary files /dev/null and b/samples/sample-postman-queries/images/postman5.png differ diff --git a/samples/sample-postman-queries/images/postman6.png b/samples/sample-postman-queries/images/postman6.png new file mode 100644 index 00000000..47cfa10d Binary files /dev/null and b/samples/sample-postman-queries/images/postman6.png differ diff --git a/samples/sample-postman-queries/images/postman7.png b/samples/sample-postman-queries/images/postman7.png new file mode 100644 index 00000000..8795ed89 Binary files /dev/null and b/samples/sample-postman-queries/images/postman7.png differ diff --git a/samples/sample-postman-queries/images/postman8.png b/samples/sample-postman-queries/images/postman8.png new file mode 100644 index 00000000..9d156586 Binary files /dev/null and b/samples/sample-postman-queries/images/postman8.png differ diff --git a/samples/sample-postman-queries/images/postman9.png b/samples/sample-postman-queries/images/postman9.png new file mode 100644 index 00000000..8d7f712e Binary files /dev/null and b/samples/sample-postman-queries/images/postman9.png differ diff --git a/samples/sample-postman-queries/images/rgfhirservice.png b/samples/sample-postman-queries/images/rgfhirservice.png new file mode 100644 index 00000000..783540da Binary files /dev/null and b/samples/sample-postman-queries/images/rgfhirservice.png differ diff --git a/samples/sample-postman-queries/images/secret1.png b/samples/sample-postman-queries/images/secret1.png new file mode 100644 index 00000000..ac1c46b3 Binary files /dev/null and b/samples/sample-postman-queries/images/secret1.png differ diff --git a/samples/sample-postman-queries/images/secret2.png b/samples/sample-postman-queries/images/secret2.png new file mode 100644 index 00000000..e9538932 Binary files /dev/null and b/samples/sample-postman-queries/images/secret2.png differ diff --git a/samples/sample-postman-queries/images/secret3.png b/samples/sample-postman-queries/images/secret3.png new file mode 100644 index 00000000..d82bd14b Binary files /dev/null and b/samples/sample-postman-queries/images/secret3.png differ