ID-23: Client Prefetch Queried Data Check

[karlnaden]

Summary

Adds a client test for each hook that verifies that any data provided in the prefetch key is equal to the data returned when Inferno executes the prefetch query separately.

Notable design decisions:

• Inferno checks that the list of ids provided in the prefetch and returned from the query are the same. It does not check contents at a deeper level. Doing so feels like it would be brittle to slight and innocuous differences and major differences would be caught in other tests.
• The queries are performed outside of the hook request because prefetched data would not need to be requested by a payer during the hook call. I was preemptively worried that implementations would limit the scope of their tokens to be just during the call, so I added an input to provide a separate bearer token if needed. The tests warns that it must have the same access scope as used to get the prefetch data.
• The tests will pass if no prefetch data is provided in any of the requests. Prefetch support is optional, so if prefetch is never demonstrated, then that will be considered a pass. Prefetch supported check will be elsewhere.
• No changes were made to the requested prefetch queries.

Testing Guidance

Test by running the CRD Client (using SMART 2.0) and Server tests against each other using the wiki instructions and updating inputs to test different scenarios. Note that by default this preset refers back to the public inferno reference server. the fhirServer value in the requests entered in the server tests to point to a local instance or another server, but that isn't necessary because you can create mismatches by changing the prefetched data provided in the requests.

1. Run each hook type once using the server test requests provided in the preset, which don't have any prefetch data. The "Prefetched data is equivalent to queried data" test should always pass with a message indicating no prefetch data was provided.

2. Test matches - test the case where the prefetched data matches what gets queried, both in the case of a search (coverage) and a read (user or patient). For example, you can use the following request for the order-dispatch hook (put in the "Request body or bodies for invoking the order-dispatch hook" input in the server test).

[
  {
    "hookInstance": "f3945c39-dfbe-44vf-ba6d-3e05e123b2va",
    "fhirServer": "https://inferno.healthit.gov/reference-server/r4",
    "hook": "order-dispatch",
    "fhirAuthorization": {
      "access_token": "SAMPLE_TOKEN",
      "token_type": "Bearer",
      "expires_in": 300,
      "scope": "user/Patient.read user/Practitioner.read user/ServiceRequest.read",
      "subject": "cds-service"
    },
    "context": {
      "patientId": "pat015",
      "order": "DeviceRequest/devreq-015-e0250",
      "performer": "Practitioner/pra1234"
    },
    "prefetch": {
      "coverage": {
        "resourceType": "Bundle",
        "id": "deed9713-045c-49db-81ec-37760a7854d5",
        "meta": {
          "lastUpdated": "2026-01-06T18:23:51.978+00:00"
        },
        "type": "searchset",
        "total": 1,
        "link": [
          {
            "relation": "self",
            "url": "https://inferno.healthit.gov/reference-server/r4/Coverage?patient=pat015&status=active"
          }
        ],
        "entry": [
          {
            "fullUrl": "https://inferno.healthit.gov/reference-server/r4/Coverage/cov015",
            "resource": {
              "resourceType": "Coverage",
              "id": "cov015",
              "meta": {
                "versionId": "1",
                "lastUpdated": "2025-08-14T00:52:07.566+00:00"
              },
              "status": "active",
              "subscriberId": "10A3D58WH456",
              "beneficiary": {
                "reference": "Patient/pat015"
              },
              "payor": [
                {
                  "reference": "Organization/org1234"
                }
              ],
              "class": [
                {
                  "type": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                        "code": "plan"
                      }
                    ]
                  },
                  "value": "Medicare Part A"
                }
              ]
            },
            "search": {
              "mode": "match"
            }
          }
        ]
      },
      "performer": {
        "resourceType": "Practitioner",
        "id": "pra1234",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2025-08-14T00:52:07.566+00:00",
          "profile": [
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
          ]
        },
        "identifier": [
          {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "1122334455"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Doe",
            "given": [
              "Jane",
              "Betty"
            ],
            "prefix": [
              "Dr."
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "716-873-1557"
          },
          {
            "system": "email",
            "value": "[email protected]"
          }
        ],
        "address": [
          {
            "use": "home",
            "type": "both",
            "line": [
              "840 Seneca St"
            ],
            "city": "Buffalo",
            "state": "NY",
            "postalCode": "14210"
          }
        ],
        "qualification": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0360",
                  "code": "MD",
                  "display": "Doctor of Medicine"
                }
              ],
              "text": "Doctor of Medicine"
            },
            "period": {
              "start": "1995"
            },
            "issuer": {
              "display": "Example University"
            }
          }
        ]
      }
    }
  }
]

3. Test mismatches - test the case where the prefetched data does not match what gets queried, both in the case of a search (coverage) and a read (user or patient). For example, you can use the following request for the order-sign hook (put in the "Request body or bodies for invoking the order-sign hook" input in the server test). The "coverage" prefetch key has an extra Coverage resource in the Bundle and the "user" prefetch key has a Practitioner that isn't on the reference server.

[
  {
    "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
    "fhirServer": "https://inferno.healthit.gov/reference-server/r4",
    "hook": "order-sign",
    "fhirAuthorization": {
      "access_token": "SAMPLE_TOKEN",
      "token_type": "Bearer",
      "expires_in": 300,
      "scope": "patient/Patient.read patient/Observation.read",
      "subject": "cds-service4"
    },
    "context": {
      "userId": "Practitioner/pra1234missing",
      "patientId": "pat015",
      "encounterId": "enc-pat014",
      "draftOrders": {
        "resourceType": "Bundle",
        "entry": [
          {
            "resource": {
              "resourceType": "DeviceRequest",
              "id": "devreq-015-e0250",
              "meta": {
                "versionId": "1",
                "lastUpdated": "2024-05-08T09:47:16.992-04:00",
                "source": "#Odh5ejWjud85tvNJ",
                "profile": [
                  "http://hl7.org/fhir/us/davinci-crd/R4/StructureDefinition/profile-devicerequest-r4"
                ]
              },
              "identifier": [
                {
                  "type": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code": "PLAC"
                      }
                    ]
                  },
                  "value": "f105372f-bbef-442c-ad7a-708fee7f8c93"
                }
              ],
              "status": "draft",
              "intent": "original-order",
              "codeCodeableConcept": {
                "coding": [
                  {
                    "system": "https://bluebutton.cms.gov/resources/codesystem/hcpcs",
                    "code": "E0250",
                    "display": "Hospital bed fixed height with any type of side rails, mattress"
                  }
                ]
              },
              "subject": {
                "reference": "Patient/pat015"
              },
              "authoredOn": "2023-01-01T00:00:00Z",
              "requester": {
                "reference": "Practitioner/pra-hfairchild"
              },
              "performer": {
                "reference": "Practitioner/pra1234"
              },
              "insurance": [
                {
                  "reference": "Coverage/cov015"
                }
              ]
            }
          }
        ]
      }
    },
    "prefetch": {
      "coverage": {
        "resourceType": "Bundle",
        "id": "deed9713-045c-49db-81ec-37760a7854d5",
        "meta": {
          "lastUpdated": "2026-01-06T18:23:51.978+00:00"
        },
        "type": "searchset",
        "total": 1,
        "link": [
          {
            "relation": "self",
            "url": "https://inferno.healthit.gov/reference-server/r4/Coverage?patient=pat015&status=active"
          }
        ],
        "entry": [
          {
            "fullUrl": "https://inferno.healthit.gov/reference-server/r4/Coverage/cov015",
            "resource": {
              "resourceType": "Coverage",
              "id": "cov015",
              "meta": {
                "versionId": "1",
                "lastUpdated": "2025-08-14T00:52:07.566+00:00"
              },
              "status": "active",
              "subscriberId": "10A3D58WH456",
              "beneficiary": {
                "reference": "Patient/pat015"
              },
              "payor": [
                {
                  "reference": "Organization/org1234"
                }
              ],
              "class": [
                {
                  "type": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                        "code": "plan"
                      }
                    ]
                  },
                  "value": "Medicare Part A"
                }
              ]
            },
            "search": {
              "mode": "match"
            }
          },
          {
            "fullUrl": "https://inferno.healthit.gov/reference-server/r4/Coverage/cov015",
            "resource": {
              "resourceType": "Coverage",
              "id": "cov015extra",
              "meta": {
                "versionId": "1",
                "lastUpdated": "2025-08-14T00:52:07.566+00:00"
              },
              "status": "active",
              "subscriberId": "10A3D58WH456",
              "beneficiary": {
                "reference": "Patient/pat015"
              },
              "payor": [
                {
                  "reference": "Organization/org1234"
                }
              ],
              "class": [
                {
                  "type": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                        "code": "plan"
                      }
                    ]
                  },
                  "value": "Medicare Part A"
                }
              ]
            },
            "search": {
              "mode": "match"
            }
          }
        ]
      },
      "user": {
        "resourceType": "Practitioner",
        "id": "pra1234missing",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2025-08-14T00:52:07.566+00:00",
          "profile": [
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
          ]
        },
        "identifier": [
          {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "1122334455"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Doe",
            "given": [
              "Jane",
              "Betty"
            ],
            "prefix": [
              "Dr."
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "716-873-1557"
          },
          {
            "system": "email",
            "value": "[email protected]"
          }
        ],
        "address": [
          {
            "use": "home",
            "type": "both",
            "line": [
              "840 Seneca St"
            ],
            "city": "Buffalo",
            "state": "NY",
            "postalCode": "14210"
          }
        ],
        "qualification": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0360",
                  "code": "MD",
                  "display": "Doctor of Medicine"
                }
              ],
              "text": "Doctor of Medicine"
            },
            "period": {
              "start": "1995"
            },
            "issuer": {
              "display": "Example University"
            }
          }
        ]
      }
    }
  }
]

5. Test override token use:
6. Obtain an access token using the FHIR API tests in the client suite:
   - run test 2.1.3 (or 2.1.1 if used SMART 1). You may need to provide the requested scopes - use "launch openid fhirUser offline_access patient/*.rs"
   - run test 2.1.4 (or 2.1.2 if used SMART 1). When asked to launch Inferno from the EHR, navigate to https://inferno.healthit.gov/reference-server/app/app-launch and copy the local launch url from the user action dialog into the "App Launch URL" input and click the "Launch App" button. Inferno will then ask you to authorize the scopes before completing.
   - pull the "ehr_access_token" output from test 2.1.4.08 (or the corresponding 2.1.2.X test for SMART v1) for use in the next step.
7. Re-run the "test matches" scenario above, but add the obtained access token to the "order-dispatch Prefetch Validation Override Bearer Token" (or corresponding input for the hook used) when running the tests.
8. Test 1.2.5.11 will still pass, but there will be a warning about using an override access token and if you look at the read and search request made during that test, they will have used the override token provided instead of SAMPLE_TOKEN