Skip to main content

Bulk FHIR Setup Checklist

Configuring bulk FHIR interactions requires a lot of moving parts in different locations. The checklist below serves as away to insure that all of the required configuration has occurred so that your bulk FHIR interactions succeed:

FHIR Resource Server Setup Checklist

  • For each FHIR resource server, obtain the endpoint URL.

  • Obtain the SSL/TLS configuration information.

  • If using the OAuth fetch adapter, obtain the FHIR endpoint’s OAuth server endpoint URL. Determine the accepted grant types.

  • If using the ODS fetch adapter, obtain the Unified Care Record Registry web service endpoint and SSL/TLS configuration information.

  • If the FHIR endpoint imposes a limit on the number of resources that can be returned in a given search, consider increasing this limit in order to prevent search errors. For InterSystems IRIS for Health, when a FHIR server is created, the Max Search Results setting defaults to 1000. To increase this number, go to Home > Health > FHIR Configuration > Server Configuration > endpoint > Configuration > Max Search Results. The recommended value depends on the contents of the FHIR server, but a value of 3000 should suffice.

Bulk FHIR Coordinator Setup Checklist

Before creating your BFC configurations, make sure that the prerequisites are in place:

Create SSL/TLS Configurations

  • Create an SSL/TLS configuration for communicating with each FHIR Resource Server and OAuth server.

  • If using the ODS fetch adapter, create an SSL/TLS configuration for communicating with Unified Care Record Registry web service.

Create Interoperability Credentials

  • If using the HTTP fetch adapter, create a credential to authenticate with the FHIR endpoint.

  • If using the X-API Key fetch adapter, create a credential to authenticate with the FHIR endpoint where the password in the credential is the API key.

  • If using the OAuth fetch adapter, and the FHIR endpoint’s grant type requires basic authentication credentials, create a credential for the fetch token.

Set Up OAuth

If you use OAuth 2.0 as your BFC auth adapter or your FHIR endpoint requires OAuth 2.0 for fetch, you will have to properly set up OAuth, which may include creating an OAuth server for the BFC, server descriptions for FHIR endpoints that require OAuth, and various client configurations.

Create or Identify an OAuth Server

If you use OAuth as your BFC Auth Adapter, you will need to provide the URL of the OAuth server for the Bulk FHIR Coordinator that supports SMART Backend Services AuthorizationOpens in a new tab. If you do not already have an OAuth server, you can use an InterSystems IRIS for Health utility to create one.

Create an OAuth Client for the BFC as an OAuth Resource Server

If you use OAuth as your BFC Auth Adapter, you will need an OAuth client configuration for the BFC as an OAuth resource server against your OAuth server issuer endpoint. Note the Application Name.

This OAuth client configuration will be created automatically when you save your BFC configuration if your OAuth server supports dynamic client registration.

Create OAuth Clients for Exports

If you use OAuth as your BFC Auth Adapter, you will need OAuth client configurations against your OAuth server issuer endpoint for use by bulk FHIR REST clients. Note the Application Name and Client ID of each client.

These OAuth client configurations will be created automatically when you save your BFC configuration if they are listed in the Clients field and your OAuth server supports dynamic client registration. Alternatively, they may be created manually.

Create Server Descriptions and OAuth Clients for FHIR Endpoints

For each FHIR endpoint with an Authorization Type of OAuth, create a server description on the BFC instance by using discovery against the FHIR endpoint’s OAuth server. Create an OAuth client configuration for the BFC against each FHIR endpoint’s OAuth server issuer endpoint using dynamic client registration or by manually entering the client ID and client secret.

Both the server description and the BFC client configuration for the FHIR endpoint’s OAuth server will be created automatically when you save your BFC configuration if the FHIR endpoint’s OAuth server supports discovery and dynamic client registration.

Set Up Users

  • Create an administrative user with the %HS_BFC_Administrator role.

  • Create a dummy user for each OAuth export client The dummy user should hold at least the %HS_BFC_Exporter role and be listed as an authorized user:

    Each OAuth export client must have both an OAuth client configuration and a dummy InterSystems IRIS user of the same name. The dummy user serves to map the appropriate roles to the OAuth client.

    To create a dummy user for an OAuth client:

    1. On the Bulk FHIR Coordinator instance, navigate to Home > System Administration > Security > Users > Create New User.

    2. In the Name field, enter the same name that you entered in the Clients name string when you configured the auth adapter, namely the Application Name specified in the OAuth client configuration.

    3. In the Password and Password (confirm) fields, enter a random string of characters, using the same string for both fields. Even though this account will not be used for login purposes, a password is required in order to create an InterSystems IRIS user.

    4. Deselect User Enabled as this user account will not be used for login purposes. This will prevent anyone from attempting to login as the user.

    5. Click Save.

    6. On the Roles tab, add the appropriate user roles, typically %HS_BFC_Exporter. To add a role, select it in the Available pane and click generated description: config arrow to move it to the Selected pane. Then click Assign as shown below.

      The roles tab of the user add GUI

    The dummy user is used solely as a means to map user roles to an OAuth client, which enables a REST export client to engage in bulk FHIR interactions with this BFC endpoint.

Set Up Storage Locations

  • Identify a temporary working directory for your exports.

  • Identify a storage directory with sufficient space for the ndjson files that will be produced by the exports.

  • When you save your BFC configuration, a CSP app will be created using the file URL you provide.

REST Client Setup Checklist

  • As described above, use dynamic client registration against the BFC endpoint URL to create an OAuth client configuration for the REST client to use.

  • When you initiate or check the status of a bulk FHIR export from a REST client using OAuth, present an access token with:

    • The Grant Type identified on the Fetch tab of your BFC configuration.

    • The OAuth server’s access token endpoint (issuerEndpoint/token) and audience if required (?aud=https://bfcEndpoint).

    • The client id and client secret for one of the OAuth Clients listed on the Authorization Types tab of your BFC configuration.

    • A scope, where the minimum required scope is system/Patient.read. A scope of system/*.read allows everything.

  • When you download ndjson files from the BFC file server with a REST client using OAuth, present an access token with:

    • The Grant Type identified on the Fetch tab of your BFC configuration.

    • The OAuth server’s access token endpoint (issuerEndpoint/token) and audience if required (?aud=https://bfcFileEndpoint).

    • The client id and client secret for one of the OAuth Clients listed on the Authorization Types tab of your BFC configuration.

    • A scope, typically user/*.read for file download.


Previous sectionCreating an OAuth 2.0 Server for the Bulk FHIR Coordinator
FeedbackOpens in a new tab