markdown and clarity edits

Author: KendalBond007

articles/healthcare-apis/fhir/smart-on-fhir.md

@@ -12,51 +12,51 @@ ms.date: 11/10/2022
 
 # SMART on FHIR
 
-Substitutable Medical Applications and Reusable Technologies ([SMART on FHIR](https://docs.smarthealthit.org/)) is a healthcare standard through which applications can access clinical information through a data store. It adds a security layer based on open standards including OAuth2 and OpenID Connect, to FHIR interfaces to enable integration with EHR systems. Using SMART on FHIR provides at least three important benefits:
+Substitutable Medical Applications and Reusable Technologies ([SMART on FHIR](https://docs.smarthealthit.org/)) is a healthcare standard through which applications can access clinical information through a data store. It adds a security layer based on open standards including OAuth2 and OpenID Connect, to FHIR® interfaces to enable integration with EHR systems. Using SMART on FHIR provides at least three important benefits:
 - Applications have a known method for obtaining authentication/authorization to a FHIR repository.
 - Users accessing a FHIR repository with SMART on FHIR are restricted to resources associated with the user, rather than having access to all data in the repository.
 - Users have the ability to grant applications access to a limited set of their data by using SMART clinical scopes.
 
-Below tutorials provide steps to enable SMART on FHIR applications with FHIR Service.
+The following tutorials provide steps to enable SMART on FHIR applications with FHIR Service.
 
 ## Prerequisites
 
 - An instance of the FHIR Service
 - .NET SDK 6.0
 - [Enable cross-origin resource sharing (CORS)](configure-cross-origin-resource-sharing.md)
 - [Register public client application in Microsoft Entra ID](/azure/healthcare-apis/azure-api-for-fhir/register-public-azure-ad-client-app)
-     - After registering the application, make note of the applicationId for client application.
-- Ensure you have access to Azure Subscription of FHIR service, to create resources and add role assignments.
+     - After registering the application, make note of the `applicationId` for client application.
+- Ensure you have access to an Azure Subscription of FHIR service, to create resources and add role assignments.
 
 ## SMART on FHIR using Azure Health Data Services Samples (SMART on FHIR (Enhanced))
 
 ### Step 1: Set up FHIR SMART user role 
-Follow the steps listed under section [Manage Users: Assign Users to Role](../../role-based-access-control/role-assignments-portal.yml). Any user added to this role would be able to access the FHIR Service, provided their requests comply with the SMART on FHIR implementation Guide.  The access granted to the users in this role will then be limited by the resources associated to their fhirUser compartment and the restrictions in the clinical scopes.
+Follow the steps listed in section [Manage Users: Assign Users to Role](../../role-based-access-control/role-assignments-portal.yml). Any user added to this role will be able to access the FHIR Service, provided their requests comply with the SMART on FHIR implementation Guide. The access granted to the users in this role will then be limited by the resources associated to their fhirUser compartment and the restrictions in the clinical scopes.
 
 > [!NOTE]
-> SMART on FHIR Implementation Guide defines access to FHIR resource types with scopes. These scopes impact the access an application may have to FHIR resources. User with SMART user role has access to perform read API interactions on FHIR service. SMART user role does not grant write access to FHIR service.
+> SMART on FHIR Implementation Guide defines access to FHIR resource types with scopes. These scopes impact the access an application may have to FHIR resources. A user with the SMART user role has access to perform read API interactions on FHIR service. SMART user role does not grant write access to FHIR service.
 
 ### Step 2: FHIR server integration with samples
-**[Click on the link](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir)** to navigate to Azure Health Data and AI Samples Open source solution. This step listed in the document enables integration of FHIR server with other Azure Services (such as APIM, Azure functions and more).
+**[Click on this link](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir)** to navigate to Azure Health Data and AI Samples open source solution. The steps listed in the document enable integration of FHIR server with other Azure Services (such as APIM, Azure functions and more).
 
 > [!NOTE]
-> Samples are open-source code, and you should review the information and licensing terms on GitHub before using it. They are not part of the Azure Health Data Service and are not supported by Microsoft Support. These samples can be used to demonstrate how Azure Health Data Services and other open-source tools can be used together to demonstrate [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg) compliance, using Microsoft Entra ID as the identity provider workflow.  
+> Samples are open-source code, and you should review the information and licensing terms on GitHub before using it. They are not part of the Azure Health Data Service and are not supported by Microsoft Support. These samples are used to demonstrate how Azure Health Data Services (AHDS) and other open-source tools can be used together to demonstrate [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg) compliance, using Microsoft Entra ID as the identity provider workflow.  
 
 ## SMART on FHIR Proxy
 <details>
                 <summary> Click to expand! </summary>
 
 > [!NOTE]
-> This is another option to SMART on FHIR(Enhanced) using AHDS Samples mentioned above. We suggest you to adopt SMART on FHIR(Enhanced). SMART on FHIR Proxy option is legacy option.
-> SMART on FHIR(Enhanced) provides added capabilities than SMART on FHIR proxy. SMART on FHIR(Enhanced) can be considered to meet requirements with [SMART on FHIR Implementation Guide (v 1.0.0)](https://hl7.org/fhir/smart-app-launch/1.0.0/) and [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg).
+> This is another option to SMART on FHIR(Enhanced) using the AHDS Samples previously mentioned. We suggest you to adopt SMART on FHIR(Enhanced). SMART on FHIR Proxy option is a legacy option.
+> SMART on FHIR(Enhanced) provides added capabilities to SMART on FHIR proxy. SMART on FHIR(Enhanced) meets requirements in [SMART on FHIR Implementation Guide (v 1.0.0)](https://hl7.org/fhir/smart-app-launch/1.0.0/) and [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg).
 
 ### Step 1: Set admin consent for your client application
 
-To use SMART on FHIR, you must first authenticate and authorize the app. The first time you use SMART on FHIR, you also must get administrative consent to let the app access your FHIR resources.
+To use SMART on FHIR, you must first authenticate and authorize the app. The first time you use SMART on FHIR, you must also get administrative consent to let the app access your FHIR resources.
 
 If you don't have an ownership role in the app, contact the app owner and ask them to grant admin consent for you in the app. 
 
-If you do have administrative privileges, complete the following steps to grant admin consent to yourself directly. (You also can grant admin consent to yourself later when you're prompted in the app.) You can complete the same steps to add other users as owners, so they can view and edit this app registration.
+If you do have administrative privileges, complete the following steps to grant admin consent to yourself directly. (You can also grant admin consent to yourself later when prompted in the app.) You can use these same steps to add other users as owners, so they can view and edit the app registration.
 
 To add yourself or another user as owner of an app:
 
@@ -76,15 +76,15 @@ To enable the SMART on FHIR proxy in the **Authentication** settings for your FH
 
 The SMART on FHIR proxy acts as an intermediary between the SMART on FHIR app and Microsoft Entra ID. The authentication reply (the authentication code) must go to the SMART on FHIR proxy instead of the app itself. The proxy then forwards the reply to the app. 
 
-Because of this two-step relay of the authentication code, you need to set the reply URL (callback) for your Microsoft Entra client application to a URL that is a combination of the reply URL for the SMART on FHIR proxy and the reply URL for the SMART on FHIR app. The combined reply URL takes this form:
+Because of this two-step relay of the authentication code, you need to set the reply URL (callback) for your Microsoft Entra client application to a URL that is a combination of the reply URL for the SMART on FHIR proxy, and the reply URL for the SMART on FHIR app. The combined reply URL takes the following form.
 
 ```http
 https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA
 ```
 
-In that reply, `aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA` is a URL-safe, base64-encoded version of the reply URL for the SMART on FHIR app. For the SMART on FHIR app launcher, when the app is running locally, the reply URL is `https://localhost:5001/sampleapp/index.html`. 
+In the reply, `aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA` is a URL-safe, base64-encoded version of the reply URL for the SMART on FHIR app. For the SMART on FHIR app launcher, when the app is running locally, the reply URL is `https://localhost:5001/sampleapp/index.html`. 
 
-You can generate the combined reply URL by using a script like this:
+You can generate the combined reply URL by using a script like the following.
 
 ```PowerShell
 $replyUrl = "https://localhost:5001/sampleapp/index.html"
@@ -98,20 +98,20 @@ $encodedText = $encodedText.Replace('+','-');
 $newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText
 ```
 
-Add the reply URL to the public client application that you created earlier for Microsoft Entra ID
+Add the reply URL to the public client application that you created previously for Microsoft Entra ID.
 
 <!---![Reply URL configured for the public client](media/tutorial-smart-on-fhir/configure-reply-url.png)--->
 
 
 ### Step 3:  Get a test patient
 
-To test the FHIR service and the SMART on FHIR proxy, you need to have at least one patient in the database. If you've not interacted with the API yet, and you don't have data in the database, see [Access the FHIR service using Postman](./../fhir/use-postman.md) to load a patient. Make a note of the ID of a specific patient.
+To test the FHIR service and the SMART on FHIR proxy, you need to have at least one patient in the database. If you've not used the API yet, and you don't have data in the database, see [Access the FHIR service using Postman](./../fhir/use-postman.md) to load a patient. Make a note of the ID of a specific patient.
 
 ### Step 4:  Download the SMART on FHIR app launcher
 
-The open-source [FHIR Server for Azure repository](https://github.com/Microsoft/fhir-server) includes a simple SMART on FHIR app launcher and a sample SMART on FHIR app. In this tutorial, use this SMART on FHIR launcher locally to test the setup.
+The open-source [FHIR Server for Azure repository](https://github.com/Microsoft/fhir-server) includes a simple SMART on FHIR app launcher and a sample SMART on FHIR app. In this tutorial, use this SMART on FHIR app launcher locally to test the setup.
 
-You can clone the GitHub repository and go to the application by using these commands:
+You can clone the GitHub repository and go to the application by using the following commands.
 
 ```PowerShell
 git clone https://github.com/Microsoft/fhir-server
@@ -128,28 +128,28 @@ The application needs a few configuration settings, which you can set in `appset
 }
 ```
 
-We recommend that you use the `dotnet user-secrets` feature:
+We recommend you use the `dotnet user-secrets` feature:
 
 ```PowerShell
 dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.fhir.azurehealthcareapis.com
 dotnet user-secrets set ClientId <APP-ID>
 ```
 
-Use this command to run the application:
+Use the following command to run the application:
 
 ```PowerShell
 dotnet run
 ```
 
 ### Step 5: Test the SMART on FHIR proxy
 
-After you start the SMART on FHIR app launcher, you can point your browser to `https://localhost:5001`, where you should see the following screen:
+After you start the SMART on FHIR app launcher, you can point your browser to `https://localhost:5001`, where you should see the following:
 
 ![Screenshot showing SMART on FHIR app launcher.](media/smart-on-fhir/smart-on-fhir-app-launcher.png)
 
 When you enter **Patient**, **Encounter**, or **Practitioner** information, you notice that the **Launch context** is updated. When you're using the FHIR service, the launch context is simply a JSON document that contains information about patient, practitioner, and more. This launch context is base64 encoded and passed to the SMART on FHIR app as the `launch` query parameter. According to the SMART on FHIR specification, this variable is opaque to the SMART on FHIR app and passed on to the identity provider. 
 
-The SMART on FHIR proxy uses this information to populate fields in the token response. The SMART on FHIR app *can* use these fields to control which patient it requests data for and how it renders the application on the screen. The SMART on FHIR proxy supports the following fields:
+The SMART on FHIR proxy uses this information to populate fields in the token response. The SMART on FHIR app *can* use these fields to control which patient it requests data for, and how it renders the application on the screen. The SMART on FHIR proxy supports the following fields.
 
 * `patient`
 * `encounter`
@@ -159,7 +159,7 @@ The SMART on FHIR proxy uses this information to populate fields in the token re
 
 These fields are meant to provide guidance to the app, but they don't convey any security information. A SMART on FHIR application can ignore them.
 
-Notice that the SMART on FHIR app launcher updates the **Launch URL** information at the bottom of the page. Select **Launch** to start the sample app, and you should see something like this sample:
+Notice that the SMART on FHIR app launcher updates the **Launch URL** information at the bottom of the page. Select **Launch** to start the sample app, and you should see something like the following.
 
 ![Screenshot showing SMART on FHIR app.](media/smart-on-fhir/smart-on-fhir-app.png)
 
@@ -175,5 +175,6 @@ Now that you've learned about enabling SMART on FHIR functionality, see the sear
 
 >[!div class="nextstepaction"]
 >[FHIR search examples](search-samples.md)
-     
-FHIR&#174; is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.
+
+
+[!INCLUDE [FHIR trademark statement](../includes/healthcare-apis-fhir-trademark.md)]