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.

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 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.