Merge pull request #186211 from CaitlinV39/master

Small updates to docs

Author: ShannonLeavitt

articles/healthcare-apis/azure-api-for-fhir/azure-active-directory-identity-configuration.md

@@ -21,16 +21,16 @@ In order for a client application to access Azure API for FHIR, it must present
 
 There are many ways to obtain a token, but the Azure API for FHIR doesn't care how the token is obtained as long as it's an appropriately signed token with the correct claims. 
 
-Using [authorization code flow](../../active-directory/azuread-dev/v1-protocols-oauth-code.md) as an example, accessing a FHIR server goes through the four steps below:
+Using [authorization code flow](../../active-directory/azuread-dev/v1-protocols-oauth-code.md) as an example, accessing a FHIR server goes through the four steps:
 
 ![FHIR Authorization](media/azure-ad-hcapi/fhir-authorization.png)
 
-1. The client sends a request to the `/authorize` endpoint of Azure AD. Azure AD will redirect the client to a sign-in page where the user will authenticate using appropriate credentials (for example username and password or two-factor authentication). See details on [obtaining an authorization code](../../active-directory/azuread-dev/v1-protocols-oauth-code.md#request-an-authorization-code). Upon successful authentication, an *authorization code* is returned to the client. Azure AD will only allow this authorization code to be returned to a registered reply URL configured in the client application registration (see below).
+1. The client sends a request to the `/authorize` endpoint of Azure AD. Azure AD will redirect the client to a sign in page where the user will authenticate using appropriate credentials (for example username and password or two-factor authentication). See details on [obtaining an authorization code](../../active-directory/azuread-dev/v1-protocols-oauth-code.md#request-an-authorization-code). Upon successful authentication, an *authorization code* is returned to the client. Azure AD will only allow this authorization code to be returned to a registered reply URL configured in the client application registration.
 1. The client application exchanges the authorization code for an *access token* at the `/token` endpoint of Azure AD. When requesting a token, the client application may have to provide a client secret (the applications password). See details on [obtaining an access token](../../active-directory/azuread-dev/v1-protocols-oauth-code.md#use-the-authorization-code-to-request-an-access-token).
 1. The client makes a request to the Azure API for FHIR, for example `GET /Patient` to search all patients. When making the request, it includes the access token in an HTTP request header, for example `Authorization: Bearer eyJ0e...`, where `eyJ0e...` represents the Base64 encoded access token.
 1. The Azure API for FHIR validates that the token contains appropriate claims (properties in the token). If everything checks out, it will complete the request and return a FHIR bundle with results to the client.
 
-It's important to note that the Azure API for FHIR isn't involved in validating user credentials and it doesn't issue the token. The authentication and token creation is done by Azure AD. The Azure API for FHIR simply validates that the token is signed correctly (it is authentic) and that it has appropriate claims.
+It's important to note that the Azure API for FHIR isn't involved in validating user credentials and it doesn't issue the token. The authentication and token creation is done by Azure AD. The Azure API for FHIR simply validates that the token is signed correctly (it's authentic) and that it has appropriate claims.
 
 ## Structure of an access token
 
@@ -39,15 +39,15 @@ Development of FHIR applications often involves debugging access issues. If a cl
 FHIR servers typically expect a [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWT, sometimes pronounced "jot"). It consists of three parts:
 
 **Part 1**: A header, which could look like:
-    ```json
+```json
     {
       "alg": "HS256",
       "typ": "JWT"
     }
-    ```
+```
 
 **Part 2**: The payload (the claims), for example:
-    ```json
+```json
     {
      "oid": "123",
      "iss": "https://issuerurl",
@@ -56,7 +56,7 @@ FHIR servers typically expect a [JSON Web Token](https://en.wikipedia.org/wiki/J
         "admin"
       ]
     }
-    ```
+```
 
 **Part 3**: A signature, which is calculated by concatenating the Base64 encoded contents of the header and the payload and calculating a cryptographic hash of them based on the algorithm (`alg`) specified in the header. A server will be able to obtain public keys from the identity provider and validate that this token was issued by a specific identity provider and it hasn't been tampered with.
 
@@ -86,11 +86,11 @@ The token can be decoded and inspected with tools such as [https://jwt.ms](https
 
 ## Obtaining an access token
 
-As mentioned above, there are several ways to obtain a token from Azure AD. They are described in detail in the [Azure AD developer documentation](../../active-directory/develop/index.yml).
+As mentioned, there are several ways to obtain a token from Azure AD. They're described in detail in the [Azure AD developer documentation](../../active-directory/develop/index.yml).
 
 Azure AD has two different versions of the OAuth 2.0 endpoints, which are referred to as `v1.0` and `v2.0`. Both of these versions are OAuth 2.0 endpoints and the `v1.0` and `v2.0` designations refer to differences in how Azure AD implements that standard. 
 
-When using a FHIR server, you can use either the `v1.0` or the `v2.0` endpoints. The choice may depend on the authentication libraries you are using in your client application.
+When using a FHIR server, you can use either the `v1.0` or the `v2.0` endpoints. The choice may depend on the authentication libraries you're using in your client application.
 
 The pertinent sections of the Azure AD documentation are:
 

articles/healthcare-apis/azure-api-for-fhir/azure-api-fhir-access-token-validation.md

@@ -12,7 +12,7 @@ ms.author: cavoeg
 ---
 # Azure API for FHIR access token validation
 
-How Azure API for FHIR validates the access token will depend on implementation and configuration. In this article, we will walk through the validation steps, which can be helpful when troubleshooting access issues.
+How Azure API for FHIR validates the access token will depend on implementation and configuration. In this article, we'll walk through the validation steps, which can be helpful when troubleshooting access issues.
 
 ## Validate token has no issues with identity provider
 
@@ -24,7 +24,7 @@ GET https://login.microsoftonline.com/<TENANT-ID>/.well-known/openid-configurati
 
 where `<TENANT-ID>` is the specific Azure AD tenant (either a tenant ID or a domain name).
 
-Azure AD will return a document like the one below to the FHIR server.
+Azure AD will return a document like this one to the FHIR server.
 
 ```json
 {
@@ -90,7 +90,7 @@ Azure AD will return a document like the one below to the FHIR server.
     "rbac_url": "https://pas.windows.net"
 }
 ``` 
-The important properties for the FHIR server are `jwks_uri`, which tells the server where to fetch the encryption keys needed to validate the token signature and `issuer`, which tells the server what will be in the issuer claim (`iss`) of tokens issued by this server. The FHIR server can use this to validate that it is receiving an authentic token.
+The important properties for the FHIR server are `jwks_uri`, which tells the server where to fetch the encryption keys needed to validate the token signature and `issuer`, which tells the server what will be in the issuer claim (`iss`) of tokens issued by this server. The FHIR server can use this to validate that it's receiving an authentic token.
 
 ## Validate claims of the token
 
@@ -110,7 +110,7 @@ When using the OSS Microsoft FHIR server for Azure, the server will validate:
 
 Consult details on how to [define roles on the FHIR server](https://github.com/microsoft/fhir-server/blob/master/docs/Roles.md).
 
-A FHIR server may also validate that an access token has the scopes (in token claim `scp`) to access the part of the FHIR API that a client is trying to access. Currently, the Azure API for FHIR and the FHIR server for Azure do not validate token scopes.
+A FHIR server may also validate that an access token has the scopes (in token claim `scp`) to access the part of the FHIR API that a client is trying to access. Currently, the Azure API for FHIR and the FHIR server for Azure don't validate token scopes.
 
 ## Next steps
 Now that you know how to walk through token validation, you can complete the tutorial to create a JavaScript application and read FHIR data.

articles/healthcare-apis/azure-api-for-fhir/carin-implementation-guide-blue-button-tutorial.md

@@ -47,13 +47,13 @@ Outside of defining search parameters, the other update you need to make to pass
 
 ### Sample rest file
 
-To assist with creation of these search parameters and profiles, we have a [sample http file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/C4BB/C4BB.http) that includes all the steps outlined above in a single file. Once you've uploaded all the necessary profiles and search parameters, you can run the capability statement test in Touchstone.
+To assist with creation of these search parameters and profiles, we have a [sample http file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/C4BB/C4BB.http) that includes all the steps outlined in this tutorial in a single file. Once you've uploaded all the necessary profiles and search parameters, you can run the capability statement test in Touchstone.
 
 :::image type="content" source="media/cms-tutorials/capability-test-script-execution-results.png" alt-text="Capability test script execution results.":::
 
 ## Touchstone read test
 
-After testing the capabilities statement, we will test the [read capabilities](https://touchstone.aegis.net/touchstone/testdefinitions?selectedTestGrp=/FHIRSandbox/CARIN/CARIN-4-BlueButton/01-Read&activeOnly=false&contentEntry=TEST_SCRIPTS) in Azure API for FHIR against the C4BB IG. This test is testing conformance against the eight profiles you loaded in the first test. You will need to have resources loaded that conform to the profiles. The best path would be to test against resources that you already have in your database, but we also have an [http file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/C4BB/C4BB_Sample_Resources.http) available with sample resources pulled from the examples in the IG that you can use to create the resources and test against.
+After testing the capabilities statement, we'll test the [read capabilities](https://touchstone.aegis.net/touchstone/testdefinitions?selectedTestGrp=/FHIRSandbox/CARIN/CARIN-4-BlueButton/01-Read&activeOnly=false&contentEntry=TEST_SCRIPTS) in Azure API for FHIR against the C4BB IG. This test is testing conformance against the eight profiles you loaded in the first test. You'll need to have resources loaded that conform to the profiles. The best path would be to test against resources that you already have in your database, but we also have an [http file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/C4BB/C4BB_Sample_Resources.http) available with sample resources pulled from the examples in the IG that you can use to create the resources and test against.
 
 :::image type="content" source="media/cms-tutorials/test-execution-results-touchstone.png" alt-text="Touchstone read test execution results.":::
 

articles/healthcare-apis/azure-api-for-fhir/patient-everything.md

@@ -20,10 +20,14 @@ To call Patient-everything, use the following command:
 ```json
 GET {FHIRURL}/Patient/{ID}/$everything
 ```
+
+> [!Note]
+> You must specify an ID for a specific patient. If you need all data for all patients, see [$export](../data-transformation/export-data.md). 
+
 The Azure API for FHIR validates that it can find the patient matching the provided patient ID. If a result is found, the response will be a bundle of type `searchset` with the following information:
 
 * [Patient resource](https://www.hl7.org/fhir/patient.html) 
-* Resources that are directly referenced by the patient resource, except [link](https://www.hl7.org/fhir/patient-definitions.html#Patient.link) references that are not of [seealso](https://www.hl7.org/fhir/codesystem-link-type.html#content) or if the `seealso` link references a `RelatedPerson`.
+* Resources that are directly referenced by the patient resource, except [link](https://www.hl7.org/fhir/patient-definitions.html#Patient.link) references that aren't of [seealso](https://www.hl7.org/fhir/codesystem-link-type.html#content) or if the `seealso` link references a `RelatedPerson`.
 * If there are `seealso` link reference(s) to other patient(s), the results will include Patient-everything operation against the `seealso` patient(s) listed.
 * Resources in the [Patient Compartment](https://www.hl7.org/fhir/compartmentdefinition-patient.html)
 * [Device resources](https://www.hl7.org/fhir/device.html) that reference the patient resource. 
@@ -42,14 +46,14 @@ The Azure API for FHIR supports the following query parameters. All of these par
 | end | Specifying the end date will pull in resources where their clinical date is before the specified end date. If no end date is provided, all records after the start date are in scope. |
 
 > [!Note]
-> You must specify an ID for a specific patient. If you need all data for all patients, see [$export](../data-transformation/export-data.md). 
+> This implementation of Patient-everything does not support the _count parameter.
 
 
 ## Processing patient links
 
 On a patient resource, there's an element called link, which links a patient to other patients or related persons. These linked patients help give a holistic view of the original patient. The link reference can be used when a patient is replacing another patient or when two patient resources have complementary information. One use case for links is when an ADT 38 or 39 HL7v2 message comes. The ADT38/39 describe an update to a patient. This update can be stored as a reference between two patients in the link element.
 
-The FHIR specification has a detailed overview of the different types of [patient links](https://www.hl7.org/fhir/valueset-link-type.html#expansion), but below is a high-level summary:
+The FHIR specification has a detailed overview of the different types of [patient links](https://www.hl7.org/fhir/valueset-link-type.html#expansion), but here's a high-level summary:
 
 * [replaces](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-replaces) - The Patient resource replaces a different Patient.
 * [refer](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-refer) - Patient is valid, but it's not considered the main source of information. Points to another patient to retrieve additional information.
@@ -63,9 +67,9 @@ The Patient-everything operation in Azure API for FHIR processes patient links i
 > [!Note]
 > A link can also reference a `RelatedPerson`. Right now, `RelatedPerson` resources are not processed in Patient-everything and are not returned in the bundle.
 
-Right now, [replaces](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-replaces) and [refer](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-refer) links are ignored by the Patient-everything operation, and the linked patient is not returned in the bundle. 
+Right now, [replaces](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-replaces) and [refer](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-refer) links are ignored by the Patient-everything operation, and the linked patient isn't returned in the bundle. 
 
-As described above, [seealso](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-seealso) links reference another patient that's considered equally valid to the original. After the Patient-everything operation is run, if the patient has `seealso` links to other patients, the operation runs Patient-everything on each `seealso` link. This means if a patient links to five other patients with a type `seealso` link, we'll run Patient-everything on each of those five patients.
+As described, [seealso](https://www.hl7.org/fhir/codesystem-link-type.html#link-type-seealso) links reference another patient that's considered equally valid to the original. After the Patient-everything operation is run, if the patient has `seealso` links to other patients, the operation runs Patient-everything on each `seealso` link. This means if a patient links to five other patients with a type `seealso` link, we'll run Patient-everything on each of those five patients.
 
 > [!Note]
 > This is set up to only follow `seealso` links one layer deep. It doesn't process a `seealso` link's `seealso` links.
@@ -81,20 +85,21 @@ In addition, you can set the `Prefer` header to `handling=strict` to throw an er
 
 ## Patient-everything response order
 
-This implementation of Patient-everything does not support the _count parameter. Patient-everything returns the results by executing several phases. After each phase, the results from the next phase will start on a new page by following the next link in the bundle. The phases are outlined below: 
+The Patient-everything operation returns results in phases:
 
-1. Phase 1 returns the `Patient` resource and any `generalPractitioner` and `managingOrganization` resources linked to the patient.
-1. Phase 2 will return resources from the patient compartment that can be filtered by their clinical date if start or end are specified. If no start or end date is passed in, this phase is skipped.
-1. Phase 3 will return resources from the patient compartment that cannot be filtered by their clinical data **or** will return all patient-compartment resources if no start or end date was specified.
+1. Phase 1 returns the `Patient` resource itself in addition to any `generalPractitioner` and `managingOrganization` resources ir references.
+1. Phase 2 and 3 both return resources in the patient compartment. If the start or end query parameters are specified, Phase 2 returns resources from the compartment that can be filtered by their clinical date, and Phase 3 returns resources from the compartment that can't be filtered by their clinical date. If neither of these parameters are specified, Phase 2 is skipped and Phase 3 returns all patient-compartment resources.
 1. Phase 4 will return any devices that reference the patient.
 
+Each phase will return results in a bundle. If the results span multiple pages, the next link in the bundle will point to the next page of results for that phase. After all results from a phase are returned, the next link in the bundle will point to the call to initiate the next phase.
+
 If the original patient has any `seealso` links, phases 1 through 4 will be repeated for each of those patients. 
 
 ## Examples of Patient-everything 
 
-Below are some examples of using the Patient-everything operation. In addition to the examples below, we have a [sample REST file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/PatientEverythingLinks.http) that illustrates how the `seealso` and `replaced-by` behavior works.
+Here are some examples of using the Patient-everything operation. In addition to the examples, we have a [sample REST file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/PatientEverythingLinks.http) that illustrates how the `seealso` and `replaced-by` behavior works.
 
-To use Patient-everything to query a patient's "everything" between 2010 and 2020, use the following call: 
+To use Patient-everything to query between 2010 and 2020, use the following call: 
 
 ```json
 GET {FHIRURL}/Patient/{ID}/$everything?start=2010&end=2020
@@ -115,7 +120,7 @@ If a patient is found for each of these calls, you'll get back a 200 response wi
 
 ## Next steps
 
-Now that you know how to use the Patient-everything operation, you can learn about the search options. For more information, see
+Now that you know how to use the Patient-everything operation, you can learn about the search options.
 
 >[!div class="nextstepaction"]
 >[Overview of search in Azure API for FHIR](overview-of-search.md)