Skip to main content

Fetch and Evaluate FHIR Data

As mentioned in the previous exercise, a useful InterSystems® Healthcare Action Engine rule usually evaluates data from a client application’s HL7® FHIR® resource server to determine whether a given condition is met. The client must therefore make the necessary FHIR data available to the Healthcare Action Engine as part of the request to the service endpoint. One CDS Hooks-compliant way that a service request can do this is by providing an OAuth 2.0 bearer token which authorizes the Healthcare Action Engine to query the client application’s FHIR resource server for the necessary data. (A subsequent exercise demonstrates an alternative approach: providing prefetched data within the service request.)

In the exercise on this page, you will configure your demo environment so that your simulated client can request a bearer token from an OAuth 2.0 server which authorizes the Healthcare Action Engine to access your FHIR resource server. After the simulated client receives a token in response to this initial request, your simulated client will send a second request: a service call which includes the token in the body. The Healthcare Action Engine can then use the token to fetch the data which it requires to evaluate the invoked rule and provide a card in response.

Configure Authorized Access to Your FHIR Resource Server

The OAuth 2.0 server which authorizes the Healthcare Action Engine to access to your FHIR resource server must issue bearer tokens according to the workflow specified by the CDS Hooks specification (https://cds-hooks.hl7.org/2.0/#fhir-resource-accessOpens in a new tab), which is itself based on the SMART on FHIR launch sequence (http://hl7.org/fhir/smart-app-launch/1.0.0/#smart-launch-sequenceOpens in a new tab). If you are using a HealthShare Unified Care Record instance’s OAuth 2.0 server for this purpose, refer to Configure a Unified Care Record OAuth 2.0 Server.

In the example provided within the Postman Collection, the simulated client submits a bearer token request for use with the FHIR server endpoint (the audience, aud). The request uses HTTP Basic authentication, providing the client_id and client_secret as the username and password for a confidential client registered with the OAuth 2.0 server.

You can use the Healthcare Action Engine to register a compatible client configuration for your OAuth 2.0 server on behalf of the simulated client by performing the following steps:

  1. Within the Management Portal for your Healthcare Action Engine instance, navigate to System Administration > Security > OAuth 2.0 > Client.

  2. If you have not already defined an Issuer Endpoint for the HealthShare Unified Care Record OAuth 2.0 server, select Create Server Description and define one. See Creating a Server Description (Using Discovery).

  3. Select the Client Configurations link associated with the HealthShare Unified Care Record OAuth 2.0 server’s Issuer endpoint.

  4. If you have already defined an OAuth 2.0 client configuration for accessing the FHIR resource server, select it from the Client Configurations list. If not, select Create Client Configuration.

  5. Configure and register a client configuration which meets the following criteria:

    • Client Type must be Confidential.

    • Resource owner password credentials and Client credentials must be selected as Required grant types.

    • Authentication type must be Basic.

    • Under the JWT Settings tab, you must select an appropriate algorithm in the Access token algorithms row for Signing access tokens.

If your FHIR server’s OAuth 2.0 server expects a different request, configure the request 3. Acquire OAuth Access Token for FHIR Fetch (and subsequent FHIR access token requests) as is appropriate for your authorization workflow.

If you are using a HealthShare Operational Data Store FHIR endpoint as your FHIR resource server, you must perform the additional steps described in Enable Access to the ODS FHIR Endpoint.

Configure a Unified Care Record OAuth 2.0 Server

If you are using the HealthShare Unified Care Record OAuth 2.0 Server to authorize access to a FHIR resource server, modify the OAuth 2.0 Authorization Server Configuration so that it meets the following criteria:

  • Audience required must be selected.

  • Resource owner password credentials and Client credentials must be selected as Supported grant types.

Unified Care Record Only: Enable Access to the ODS FHIR Endpoint

HealthShare grants authorization to access the ODS (which provides the FHIR endpoint for data stored within Unified Care Record) based on the roles assigned to HealthShare user accounts. It does not currently support the use of the OAuth 2.0 client credentials grant type to authorize requests from applications outside the HealthShare federation.

Therefore, to use the HealthShare ODS as a FHIR resource server in a Healthcare Action Engine interaction, you must customize the authentication mechanism so that such applications are assigned a role which is authorized to access the ODS. To do this, perform the following steps:

Caution:

The following instructions are provided for demonstration purposes only. For security reasons, only apply this change within a secured, non-production environment.

  1. Use a supported IDEOpens in a new tab to connect to your Unified Care Record instance’s Registry namespace.

  2. Open the HS.Local.ZAUTHENTICATE class and locate the OnAfterProperties method.

  3. Edit the OnAfterProperties method as follows:

    ClassMethod OnAfterProperties(ServiceName, Namespace, ByRef tResponse, ByRef Properties) As %Status
 {
    Set:((Namespace="HSODS")&&(Properties("Roles")="")) Properties("Roles")="%HS_ServiceRole"
    Quit $$$OK
 }

  4. Import and compile your customized HS.Local.ZAUTHENTICATE class.

Request 3: Acquire OAuth Access Token for FHIR Fetch

Once your FHIR resource server and its corresponding OAuth 2.0 server are configured so that the Healthcare Action Engine can access it using a bearer token, perform the following steps to request a bearer token:

  1. Within Postman, access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and modify the Current Value of the following variables:

    • odsNamespace (Unified Care Record only) — the name of the Unified Care Record Operational Data Store namespace, in lowercase characters.

    • odsFHIRversion (Unified Care Record only) — the code for the FHIR version you are using. In most cases, the Initial value (r4) is the correct one.

    • fhirEndpoint — the base REST endpoint for your FHIR resource server. If you are using the Unified Care Record Operational Data Store FHIR endpoint as your FHIR server, you can simply replace the placeholder <odsBaseURL> with the base URL for accessing your Unified Care Record Operational Data Store over HTTPS, including the port number or instance prefix as needed.

    • fhirAuthURL — the base issuer endpoint for your FHIR server’s OAuth 2.0 server. If you are using a HealthShare Unified Care Record OAuth 2.0 server, you can simply replace the placeholder <registryBaseURL> with the base URL for accessing your Unified Care Record Registry over HTTPS, including the port number or instance prefix as needed.

    • fhirClientID — the client ID for the OAuth 2.0 client which you registered using the Healthcare Action Engine.

    • fhirClientSecret — the client secret for the OAuth 2.0 client which you registered using the Healthcare Action Engine.

    Requests in subsequent steps use these variables to construct their target URLs.

  2. Select Save to save this update to your Variables.

  3. Select the request 3. Acquire OAuth Access Token for FHIR Fetch.

  4. Select Send to request a bearer token to allow the Healthcare Action Engine to fetch the FHIR data it requires to evaluate a rule.

  5. The body of the response to a successful token request includes the bearer token under the key access_token, as depicted in the following screenshot:

    Response to FHIR token request in Postman

    Copy the value of access_token (excluding the quotation marks).

  6. Access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and update the Current Value of fhirAccessToken to equal the value of access_token (which you copied in the preceding step).

  7. Select Save to save this update to your Variables.

Note:

Per the CDS Hooks specification, bearer tokens to access a FHIR resource server expire after a very short interval of time. (For example, the token in the preceding screenshot expires after five minutes.) This means that—if considerable time has passed—it may be necessary to acquire a new token by repeating the steps in this section before you can complete a subsequent service request successfully.

Request 4: Service Request (with FHIR Fetch, no CDS Hooks OAuth)

The simulated client can now provide the bearer token it has acquired to the Healthcare Action Engine within the body of a request to the service endpoint for a rule. This allows the Healthcare Action Engine to query the FHIR resource server for the data it needs to evaluate the rule. Then, the Healthcare Action Engine can respond to the request with any cards which result from that evaluation.

To invoke a rule according to this workflow:

  1. Within Postman, access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and modify the Current Value of the following variables:

    • haeDemoRule1 — the name of the demo rule that you want to invoke.

    • patientID1 — the ID for the patient whose data you want to evaluate using haeDemoRule1. The Healthcare Action Engine demo provides sample patient data for testing each synchronous demo rule; the FHIR resource server assigns IDs to the sample patients as you import this data. If you are using a HealthShare Operational Data Store FHIR endpoint as your FHIR server, you can search for the assigned MPIID using the Patient Registry.

    These variables are used to construct the target endpoint for the service request which you will invoke in the steps which follow.

  2. Select the request 4. Service Request (with FHIR Fetch, no CDS Hooks OAuth). Note the following:

    • The target URL for this request is the service endpoint for the rule you want to invoke, haeDemoRule1.

    • The body of the service request provides the Healthcare Action Engine with the information it needs to fulfill this request in accordance with the CDS Hooks specification. This information includes:

      • The ID of the patient whose data you want to evaluate (as patientID, within the context object).

      • The endpoint for the FHIR resource server where the patient’s data is stored (as fhirServer).

      • The access token, along with required metadata (as fhirAuthorization).

  3. Select Send.

The body of the response to a successful service request contains a CDS Hooks card which describes the results of evaluating the patient’s data according to the rule you invoked. In the screenshot which follows, the request invoked the demo rule EDSDemoElevatedINR to evaluate the sample patient George Holman. The card in the response body warns the user of our simulated client application that George Holman’s blood is clotting more slowly than normal:

Excerpt of card in response to service request

Secure Client Requests to the Healthcare Action EngineNext section
Previous sectionHello, CDS Hooks!
FeedbackOpens in a new tab