Skip to main content

Bulk FHIR Coordinator

While a typical HL7® FHIR® interaction seeks specific information about a particular patient, a FHIR bulk dataOpens in a new tab interaction extracts large quantities of data across patients from a FHIR resource server. Typical uses for bulk FHIR include identifying study cohorts, population health, or transferring data from one EHR to another.

Introduction to the Bulk FHIR Coordinator

In order to simplify the FHIR bulk data interaction for clients and to not overwhelm a FHIR server with bulk data requests, the InterSystems Bulk FHIR Coordinator(BFC) mediates the interaction between a bulk data client and a FHIR resource server endpoint for bulk data requests. The Bulk FHIR Coordinator can facilitate bulk FHIR export for FHIR resource servers that do not natively support the bulk data interaction.

When the Bulk FHIR Coordinator requests and receives FHIR resources from a FHIR endpoint on behalf of a client, it is called an export.

The diagram below illustrates how the Bulk FHIR Coordinator mediates the interaction between a client and FHIR endpoints.

The Bulk FHIR Coordinator mediates the interaction between a client and a FHIR endpoint

You can interact with the Bulk FHIR Coordinator either by using the BFC home page or through a bulk data REST client:

  • On the BFC home page, you can enter a set of configurations. Each bulk FHIR configuration identifies a FHIR resource server endpoint, and defines the authorization type, file location, and other parameters to be used in the bulk data interaction. The FHIR endpoint may be InterSystems IRIS for Health, HealthShare Health Connect, HealthShare Unified Care Record, or any other system that supports returning all resources and, for patient and group exports, supports the Patient/$everything operation.

    From the home page you can also initiate exports, view export status, download exported files, and view the export logs.

  • Using a REST client you can perform each of the requests described in the FHIR Bulk Data Export specificationOpens in a new tab. Each bulk FHIR configuration provides two endpoints:

    • bulk FHIR endpoint — supports export, status, and delete requests

    • file storage endpoint — supports file download requests

The Bulk FHIR Coordinator Home Page

To work with bulk FHIR configurations, navigate to Home > Health > foundationNamespace > Bulk FHIR Coordinator:

The Bulk FHIR Coordinator home page displays the named configurations and includes icons that you can use to perform actions.

Each configuration has a name and a unique endpoint. Use the icons on the Configurations > List page to perform the following actions:

Icon Action Notes
  New Configuration Allows you to create a new configuration either by opening the Edit page or by importing a JSON file.
The view exports icon View Exports Opens the Export view page for the configuration where you can view in-progress and completed bulk FHIR exports or request a new export.
The copy icon Copy Opens the Edit page with an identical configuration, except that the Name and Endpoint have _copy appended. Step through the configuration pages using the Next button and make any necessary adjustments. Click Configure on the Review page to save the new configuration.
The edit icon Edit Opens the Edit page for the configuration. Step through the configuration pages using the Next button and make any necessary adjustments. Click Configure on the Review page to save the changes.
The download icon Download Creates a JSON-formatted record of your configuration. The name of the file is the same as the name of your configuration, with any special characters replaced by an underscore. To import a JSON-formatted configuration, click the New Configuration button, select Import JSON, and then locate the file using the browse control.
The delete icon Delete Enter the endpoint URL as indicated in the text box to confirm and then click the Delete button.
Note:

Which actions appear for each configuration depend on the user’s roles.

Creating or Editing a Bulk FHIR Configuration

To create or edit a bulk FHIR configuration:

  1. Log in to InterSystems IRIS for Health as a user with administrative privileges.

  2. Navigate to Home > Health > foundationNamespace > Bulk FHIR Coordinator.

  3. On the Bulk FHIR Configurations page, invoke the Create/Edit workflow by clicking either The edit icon or The copy icon for an existing configuration or by clicking New Configuration followed by Create New.

The bulk FHIR configuration Create/Edit workflow consists of five separate pages:

  1. Configuration Settings

  2. Authorization Types

  3. Fetch

  4. Storage Location

  5. Review

Enter values on each page in the Create/Edit workflow and then click Next to move to the next page. On the final review page, click Configure to save the bulk FHIR configuration. The sections that follow explain the various settings.

Bulk FHIR Create/Edit Workflow: Configuring Settings

The settings on the Configuration Settings page of the Create/Edit workflow for bulk FHIR configurations are:

Name

Enter a unique name for your configuration. If you include some of the key parameters in the name, it will help you distinguish among several configurations. A name is required.

Auto-start Exports

Select this option if export jobs should start as soon as a request is received. Deselect this option if initiating an export requires manual approval before starting. Selected by default.

Authorized Users

Optionally enter a comma-delimited list of non-administrative users who are permitted to perform exports using this configuration. A user who holds only the %HS_BFC_Exporter role must be listed as an authorized user in order to perform exports. This includes the dummy users associated with OAuth clients for the purpose of mapping roles.

Note:

A user who holds only the %HS_BFC_Exporter role will not be able to access Bulk FHIR Coordinator home page UI unless they are either provided a direct link to the page, or their startup namespaceOpens in a new tab is configured to be the BFC foundation namespace.

BFC Endpoint

Enter the URL for this bulk FHIR endpoint. This value is required and must be unique among configurations. It should be a relative value, for example /bulkFHIR/r4a. When you save this configuration, a web app will be created using this URL that will serve as the REST endpoint.

Core FHIR Package

This is a read-only field that is derived from the Fetch Endpoint URL for the configuration when the configuration is saved. An example value is hl7.fhir.r4.core@4.0.1

Permitted Exports

Select which type of exports are allowed:

  • Patient — the set of FHIR resources pertaining to all patients.

  • Group — the set of FHIR resources pertaining to all members of the specified Group resource. With the HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab fetch adapter, a Group resource is understood to be a Unified Care Record cohort.

  • System — all FHIR resources, whether or not they are associated with a patient. This supports use cases like backing up a server, or exporting terminology data by restricting the resources returned using the _type parameter.

    Note:

    System export is not supported with the HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab fetch adapter.

Expire After

The time in minutes after which stored ndjson files expire. Defaults to 1440 minutes (one day). Any ndjson files that have expired are deleted by the Bulk FHIR expiration task that runs hourly by default.

Max file size

The maximum size of each ndjson file in bytes. When this limit is reached, the open ndjson file in the export is saved and a new file is started. Defaults to one million bytes.

Flush Interval

The flush interval in minutes. When the interval is reached, the open ndjson file in the export is saved and a new ndjson file is started. Defaults to 60 minutes.

Working Directory

Directory where temporary files are stored before they are passed to the storage file adapter.

Bulk FHIR Create/Edit Workflow: Configuring Authorization

Which settings appear on the Authorization Types page of the Create/Edit workflow depend upon the Auth Adapter that you select:

Auth Adapter

This field is required. This defines the type of auth used between the bulk data client and the Bulk FHR Coordinator. Select either HS.BulkFHIR.Auth.BasicAuth.AdapterOpens in a new tab or HS.BulkFHIR.Auth.OAuth.AdapterOpens in a new tab. InterSystems IRIS for Health includes a utility that will configure an OAuth 2.0 server for you if you do not already have one.

For the BasicAuth adapter, no additional settings are required. For the OAuth adapter, also enter the settings below:

Issuer URL

The URL of an existing OAuth 2.0 server. When using the OAuth adapter this field is required. The OAuth server may be on the IRIS for Health instance or elsewhere. IRIS for Health includes a utility that will create an OAuth 2.0 server for you if you do not already have one.

Example value: https://example.org/oauth2.

BFC Client Name

When using the OAuth adapter this field is required. Enter the Application Name of the OAuth client configuration for the Bulk FHIR Coordinator as an OAuth resource server.

When a REST client presents a token to the Bulk FHIR Coordinator endpoint, the BFC Client validates the token with the OAuth server.

  • If the BFC Client configuration is not already defined then it will be created automatically when you save this bulk FHIR configuration, as long as your OAuth server supports dynamic client registration.

  • If your OAuth server does not support dynamic client registration, then you must:

    1. Request that OAuth server administrator provision a client account on the OAuth server for the BFC resource server.

    2. Manually add an OAuth client configuration on the Bulk FHIR Coordinator instance using the value in BFC Client Name by navigating to Home > System Administration > Security > OAuth 2.0 > Client > issuerEndpoint > Client Configurations.

Clients

A list of OAuth clients approved for performing bulk FHIR exports from this BFC endpoint.

Your OAuth server should have a set of OAuth client descriptions defined that match the OAuth client configurations in Home > System Administration > Security > OAuth 2.0 > Client > issuerEndpoint > Client Configurations.

Each OAuth client configuration has an Application Name (indicated on the General tab).

OAuth client configuration page showing the application name on the general tab

To indicate which OAuth clients may use this BFC configuration, enter in the Clients field a comma-separated list of the form name:authentication_method where:

  • name is the Application Name in the OAuth client configuration.

  • authentication_method identifies which Open ID Connect workflow this client will use to authenticate with the OAuth server. The value for authentication_method must be either client_secret_post or private_key_jwt.

Note:

If the client configurations you enter do not already exist, they will be created when you save this bulk FHIR configuration, as long as your OAuth server supports dynamic client registration. Alternatively, you can create these clients manually.

Each OAuth client configuration also has a Client ID and Client Secret (indicated on the Client Credentials tab).

OAuth client configuration page showing the client ID on the client credentials tab

When a bulk data REST client sends a request to the BFC endpoint, the access token that it presents includes a client_id and client_secret. The access token’s client_id is validated against the Client IDs of the OAuth client configurations listed in the Clients field of the BFC configuration, and the client_secret in the access token is validated against the Client Secret in the OAuth client configuration.

Important:

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. See Setting up Users for detailed instructions.

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. This user is typically created as “Not Enabled”, which prevents an actual user from logging in with those credentials.

Bulk FHIR Create/Edit Worklow: Configuring Fetch

On the Fetch page of the Create/Edit workflow:

  1. Select a fetch adapter

  2. Configure the fetch adapter

  3. Configure the authorization settings

Configuring Fetch: Selecting an Adapter

Fetch Adapter

This field is required. Select either HS.BulkFHIR.Fetch.PureFHIR.AdapterOpens in a new tab or HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab. The ODS adapter is specific to the Unified Care Record ODS.

Note:

System export is not supported with HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab.

Configuring Fetch: Configuring the Adapter

All of the settings under the Adapter Configuration heading appear for both the PureFHIR and ODS fetch adapters with the exception of the Registry Webservice settings that appear only for the ODS fetch adapter.

Endpoint URL

The full URL of the FHIR endpoint, for example, https://example.org/fhir/r4. This field is required.

SSL Configuration

The InterSystems IRIS SSL/TLS client configuration that describes how to communicate with the FHIR endpoint when using HTTPS.

Resource Types

The comma-delimited default list of FHIR resource types that should be included in an export operation for this configuration. This list can be overridden by a client using the _type query parameter in the bulk data request. If this field is left blank, then all resource types are included by default.

Max Requests Per Second

Maximum number of HTTP(S) requests to make to the FHIR endpoint each second. This number will be shared across all active export operations for the configuration, and may be used to limit the load imposed by the Bulk FHIR Coordinator on the FHIR endpoint. The default value is 10 requests per second.

HTTP Timeout

Timeout value in seconds for each HTTP(S) request to the FHIR endpoint when fetching data. If your export is for a very large population and the FHIR endpoint has a large page size, you may wish to extend this timeout if you get timeout errors while fetching. The default value is 180 seconds.

Worker Jobs

Number of background worker jobs assigned to do the fetch processing. The default value is 4 jobs.

Registry Webservice Credential Id

Required when using HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab. The interoperability credential to use when calling the Hub web service at the Unified Care Record Registry.

This credential should match the Username Token Profile setting in the UCR service registry entry for the Hub web service. You can identify this service registry entry as it will refer to baseURL/services/HS.Hub.HSWS.WebServices.cls. The service registry entry is typically named HSREGISTRY. A typical value of the Username Token Profile setting in the HSREGISTRY service registry entry is HS_Services.

The username and password in the credential will be used when invoking the Hub web service at runtime.

Registry Webservice Endpoint URL

Required when using HS.BulkFHIR.Fetch.ODS.AdapterOpens in a new tab. The Hub web service URL at the Unified Care Record Registry. Typically:

https://UCRHost:Port/csp/healthshare/registryNamespace/services/HS.Hub.HSWS.WebServices.cls

Configuring Fetch: Configuring Authorization

Once the fetch adapter is configured, specify the authorization settings for the BFC fetch interactions with the FHIR endpoint.

Authorization Type

This defines the type of auth used between the Bulk FHIR Coordinator and the FHIR endpoint when performing an export. Select either HTTP for basic auth, X-API for X-API-Key header auth, or OAuth for OAuth 2.0.

Note:
  • The HTTP Credential Id setting appears only if you select basic auth.

  • The X-API Key Credential setting appears only if you select X-API-Key header auth.

  • The remaining settings appear only if you select OAuth 2.0.

HTTP Credential Id

For basic auth only, the interoperability credential to use when communicating with the FHIR endpoint.

X-API Key Credential

For X-API-Key header auth only, the interoperability credential to use when communicating with the FHIR endpoint. The X-API-Key header will contain the password from the credential when the BFC sends an HTTP request to the FHIR endpoint.

OAuth Issuer URL

Issuer URL of the FHIR endpoint's OAuth server.

If this OAuth server supports discovery, a server description will be created for it when you save this BFC configuration.

Client Name

The Application Name of the OAuth client configuration that the Bulk FHIR Coordinator will use to authenticate with the FHIR endpoint's OAuth server when performing an export.

This client configuration will be created automatically when you save this BFC configuration if the FHIR endpoint’s OAuth server supports discovery and dynamic client registration. Alternatively, you may create this client configuration manually at Home > System Administration > Security > OAuth 2.0 > Client > FHIRServerIssuerEndpoint > Client Configurations.

Grant Type

OAuth grant type to use when obtaining an access token from the FHIR endpoint's OAuth server.

Depending on the client configuration’s Required Grant Types, the possible values for this field are:

  • password — Resource Owner Password Credentials

  • client_credentials — Client Credentials

Fetch Token Scopes

Comma-delimited list of OAuth scopes to specify when obtaining an access token from the FHIR endpoint's OAuth server. This applies only when the original request to the Bulk FHIR Coordinator did not use an access token. For example, system/*.read allows everything.

Important:

If the Authorization Type is OAuth, any patient or group export requires a minimum of the system/Patient.read scope in order to support the Patient/$everything operation that is used in the fetch in order to return both the patient compartment and related resources outside of the patient compartment such as Practitioner. Even if the _type parameter filters out Patient resources, the operation still requires the system/Patient.read scope, along with scopes for all other resources being retrieved.

Fetch Token Credential ID

The interoperability credential to use to authenticate with the FHIR endpoint's OAuth server if a grant type requires basic authentication credentials.

Bulk FHIR Create/Edit Workflow: Configuring Storage

The settings on the Storage Location page of the Create/Edit workflow for bulk FHIR configurations are:

Storage Adapter

This field is required. Select HS.BulkFHIR.Storage.File.AdapterOpens in a new tab.

File URL

Relative URL path for the web application file which serves bulk export files (for example, /file or /bulkfhir/file). Different configurations in the same namespace may use the same URL.

This URL variesOpens in a new tab depending on your web server configuration: if you employ a single web server for multiple InterSystems IRIS for Health instances, include the instance prefix.

Directory

Storage location for ndjson files that contain the exported FHIR resources. If not specified, defaults to installDir/mgr/Temp/BulkFHIR/namespace/. This directory will contain numbered subdirectories for each session. Each session subdirectory will contain resource group directories and files. Distinct directories must be used between namespaces due to the potential for collisions in session identifiers.

Bulk FHIR Create/Edit Workflow: Reviewing and Validating Your Configuration

The Review page of the Create/Edit workflow for bulk FHIR configurations lists the value of each setting from the other pages. Review the settings and click Configure save your bulk FHIR configuration. When you click Configure, the BFC will validate each setting and present any issues that need to be addressed. Once each setting has passed validation, the BFC performs any automatic configuration of OAuth client configurations and server descriptions that is necessary.

Importing a Bulk FHIR Configuration using JSON

To import a configuration, click the New Configuration button, select Import JSON, and then locate the file using the browse control.

Specifics of the JSON specification for bulk FHIR configuration are shown pretty-printed below by section:

  • A simple property that you wish to leave blank may simply be excluded.

  • Square brackets in the JSON indicate that a comma-separated list of values may be entered.

  • Text colors in the JSON fragments indicate:

    • Green text indicates that a string value in quotes is expected.

    • Red text indicates that a numeric value is expected.

    • Orange text indicates that a boolean value of true or false is expected.

Sample JSON is shown below for the following pages:

Sample JSON for the Configuration Settings Page

generated description: bulk json config settings

Sample JSON for the Authorization Types Page

Basic Auth Adapter

generated description: bulk json auth types basic

OAuth Adapter

generated description: bulk json auth types oauth

Sample JSON for the Fetch Page

ODS Fetch Adapter

generated description: bulk json fetch ods

See Fetch Authorization Settings for the closing portion of the property "fetch_config": {

Pure FHIR Fetch Adapter

generated description: bulk json fetch pure fhir

See Fetch Authorization Settings for the closing portion of the property "fetch_config": {

Fetch Authorization Settings

HTTP Fetch Authorization

The JSON fragment below is the closing portion of the property "fetch_config": {

generated description: bulk json fetch http

X-API Fetch Authorization

The JSON fragment below is the closing portion of the property "fetch_config": {

generated description: bulk json fetch xapi

OAuth Fetch Authorization

The JSON fragment below is the closing portion of the property "fetch_config": {

generated description: bulk json fetch oauth

Sample JSON for the Storage Location Page

generated description: bulk json storage

Performing an Export from the Bulk FHIR Home Page

When the Bulk FHIR Coordinator requests a set of FHIR resources from a FHIR endpoint on behalf of a client it is called an export.

This section describes how to:

Accessing the Export Page

To initiate or inspect a bulk FHIR export:

  1. Log in to InterSystems IRIS for Health as a user with appropriate privileges.

  2. Navigate to Home > Health > foundationNamespace > Bulk FHIR Coordinator.

  3. Navigate to the Exports page either by:

    • Clicking the Exports link to open the Exports > List page to view all exports.

    • Clicking The view exports icon to open the Exports > View page to view the exports for a particular configuration.

The exports list page displays in-progress and completed exports and includes icons that allow you to perform certain actions

On the Exports page, you can view the status of exports that are in progress and completed. You can also take the following actions:

Icon Action Notes
  New Export Request Initiate a new export.
The pause icon Pause Pause an export that is in progress.
The resume icon Resume Resume an export that was previously paused.
The cancel icon Cancel Cancel an export that is in progress.
The view logs icon View Logs View the logs for an export that is in progress or that is completed. Opens the Logs > List page where you can filter and view the export logs.
The copy icon Copy Create a new export using the information from a completed export.
The download icon Download Opens the Exports > Exported Files page where you can search for and download the ndjson files for specific resources by type, and also download export errors.
Note:

Which actions appear depend on the user’s roles.

Initiating an Export Request

  1. From the Exports page, click New Export Request to initiate an export.

  2. Select a BFC Configuration from the drop down list.

  3. Click Next.

  4. Select the type of Export from among the available choices which may include System, Group, and Patient.

  5. If you selected a group export, enter the Group ID. For Unified Care Record ODS, the group ID would be a cohort name.

  6. Optionally enter a date in the Since field in the format YYYY-MM-DD, or select a date using the date chooser. You may also enter a time by clicking Add Time and then entering a time.

  7. Click Export Now to initiate your export.

  8. Your export will appear as a row in the In Progress table on the Exports page. You may Pause/Resume or Cancel the export when it is in progress. You may also view the logs to determine how the export is progressing.

Downloading the ndjson for a Completed Export

  1. From the Exports page, in the Completed Exports pane, optionally enter a filter value and click Apply to filter the list of completed exports.

  2. In the desired row of the Completed Exports table, click The download icon to view a list of available files for that export. The exported files are segregated by resource type.

  3. To pare down the list of files, optionally enter a Search term.

  4. To download an ndjson file click The download icon.

Viewing the Export Logs

The export logs provide detailed information for various event types in several different components of the bulk FHIR workflow:

Component Event Type Details
BFC session_action actions: created, start, pause, resume, complete, failure (reason, stack)
BFC flush reasons: size, interval, finalize_session
fetch rest_request path, rate_limit_time, http_response_time, http_status (reason, stack)
storage flush reasons: size, interval, finalize_session
storage file_access client, file

To view the exports logs for a session

  1. From the Exports page, click The view logs icon in the row for an In Progress or Completed session. Alternatively, click Logs to view the logs for all sessions.

  2. Optionally enter filter values and click Apply to pare down the list of logs.

  3. Click The view logs icon to view a particular log file.

Performing a Bulk FHIR Export from a REST Client

When the Bulk FHIR Coordinator requests a set of FHIR resources from a FHIR endpoint on behalf of a client it is called an export.

This section describes how to:

Initiating an Export Request from a REST Client

To initiate a bulk FHIR export from a REST client, send a GET request to your BFC endpoint indicating the desired operation, for example:

  • System — GET https://bfcEndpoint/$export

  • Patient — GET https://bfcEndpoint/Patient/$export

  • Group — GET https://bfcEndpoint/Group/groupID/$export

If this BFC configuration uses the OAuth Auth Adapter, obtain an access token by specifying:

  • 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 grant type that is supported by the OAuth client. (In InterSystems IRIS, this would be one of the Required Grant Types selected on the General tab of your OAuth client configuration.)

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

An example patient export using OAuth is shown below:

generated description: bulk rest

The following optional parameters are supported with $export:

_outputFormat

The BFC exports Newline Delimited JSON (ndjson) files.

The value application/fhir+ndjson and the abbreviated values application/ndjson and ndjson are accepted.

_since

Resources will be included in the response if their state has changed after the indicated time in “FHIR Instant” format:

YYYY-MM-DDThh:mm:ss.sss+zz:zz

_type

Comma-delimited list of FHIR resource types to include in the export. Defaults to all resource types supported by the fetch adapter as configured.

Checking the Status of an Export from a REST Client

The response header to your initial GET request will include a CONTENT-LOCATION key that indicates a URL of the form:

bfcEndpoint/status/sessionNumber

Periodically send GET requests to the CONTENT-LOCATION URL to obtain the status of your bulk FHIR export session.

The following status responses may be returned:

202 Accepted
  • The BFC is processing the export.

  • The response header will include an X-PROGESS key with the value in-progress.

200 OK
  • The export is complete, and files are ready for download.

  • The response header will include an EXPIRES key indicating how long the ndjson files will be kept on the BFC file server.

  • The response body will contain file URLs for ndjson files stored on the BFC file server. For each resource type returned, there will be one or more files:

    generated description: bulk rest files

500 Internal Server Error
  • An error occurred on the BFC.

Downloading the ndjson for a Completed Export

Once you receive a Status: 200 OK in the response header, your files are ready to download from the BFC file server. To retrieve the files, send a GET request to each file URL.

If this BFC configuration uses the OAuth Auth Adapter, obtain a new access token by specifying:

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

An example is shown below:

generated description: bulk rest file

Cancelling an Export

To cancel an export that is in progress, send a DELETE request to the CONTENT-LOCATION URL. The BFC will return an HTTP status code of “202 Accepted” if the delete is successful. Other status codes indicate an error.

Bulk FHIR Roles and Resources

The Bulk FHIR Coordinator employs role-based access:

Bulk FHIR Roles

The Bulk FHIR Coordinator offers the following user roles:

%HS_BFC_Exporter

The %HS_BFC_Exporter role has the following permissions:

  • View and perform Patient or Group exports on configurations where the user is listed as an authorized user.

  • Pause, stop, resume, or cancel those exports, and view and download logs for those exports.

Assign this role to each dummy InterSystems IRIS user that you create to match your OAuth client configurations (in addition to making the dummy user an authorized user for the configuration).

Because %HS_BFC_Exporter is intended primarily for the dummy user that maps roles to an OAuth client , a user with only this role cannot access the Bulk FHIR Coordinator home page through the Management Portal menu. If you assign this role to a real user, either make the BFC foundation namespace the user’s startup namespace, or provide the user a direct link to the BFC home page in the portal.

When combined with the %HS_BFC_Export_Manage role, this user can initiate Patient or Group exports on all configurations, and view and download logs for exports that the user initiates. They can also access the home page in the portal.

%HS_BFC_Export_Manage

The %HS_BFC_Export_Manage role has the following permissions:

  • View all configurations and all exports.

  • Cannot create configurations, initiate exports, or view export logs.

Can be combined with %HS_BFC_Exporter to expand privileges.

%HS_BFC_Administrator

The %HS_BFC_Administrator role has the following permissions:

  • View, create, edit, copy, and delete all configurations.

  • Perform system exports on any configuration that supports them.

  • View, pause, stop, resume, cancel, and view or download logs for all exports.

  • Download exports that the user initiates.

When combined with %HS_BFC_Download_Manage, can download files from all exports.

%HS_BFC_Download_Manage

The %HS_BFC_Download_Manage role has the following permissions:

  • Download files from all exports.

Use to expand the privileges of %HS_BFC_Administrator.

Navigate to Home > Security > Roles to view the resources and privileges associated with these roles.

Bulk FHIR Resources and Privileges

Actions within the Bulk FHIR Coordinator are associated with the following privileges:

Resource Privileges
%HS_BFC_Configuration
  • W — create, edit or delete configurations

  • R — view configurations

%HS_BFC_Download_Manage
  • U — download files created by exports which were started by any user

%HS_BFC_Export_Download
  • U — download files created by exports which were started by the current user only

%HS_BFC_Export_Group
  • U — start a group export

%HS_BFC_Export_Log
  • R — view logs for exports which were started by the current user

%HS_BFC_Export_Manage
  • U — view, pause, stop, and resume exports in progress which were started by any user

%HS_BFC_Export_Patient
  • U — start a patient export

%HS_BFC_Export_Status
  • R — view exports started by the current user

  • W — pause or cancel exports started by the current user

%HS_BFC_Export_System
  • U — start a system export

%HS_BFC_Log_Manage
  • U — view logs for exports which were started by any user

You can also find a description of these resources and privileges by navigating to Home > Security > Resources.

Creating an OAuth 2.0 Server for the Bulk FHIR Coordinator

If you wish to use OAuth 2.0 for authentication between bulk FHIR REST clients and the Bulk FHIR Coordinator and you do not already have an OAuth 2.0 server, InterSystems IRIS for Health includes a utility that will create an OAuth 2.0 server on your local instance specifically to support SMART Backend Services AuthorizationOpens in a new tab for Bulk FHIR Coordinator endpoints. This OAuth server is configured to support dynamic client registration.

Several prerequisites must be met before you can successfully run this utility:

  1. Your web server is configured for SSL/TLS.

  2. You have created an SSL/TLS configuration for your instance.

  3. In the Configure Secure Communication dialog in the Installer Wizard, you have created and activated a secure communication configuration.

  4. After configuring secure communications in the Installer Wizard, you have configured and activated a Foundation namespace where you will create your bulk FHIR configurations.

The OAuth 2.0 server utility consists of two methods in the class HS.BulkFHIR.OAuth2InstallerOpens in a new tab. Call these methods from your Foundation namespace.

Configures an IRIS OAuth 2.0 authorization server in the local IRIS instance for bulk FHIR and creates a service registry entry that points to the OAuth server issuer endpoint. This method depends on class parameters OAuthSSLConfigName and OAuthIssuerServiceName for the values of those two items.

Arguments:

  • pForceDelete

    0 = abort and return fail if an existing OAuth server is found (default)

    1 = delete existing OAuth server and its clients before re-creating

  • pVerbose

    0 = do not display method outcome text

    1 = display method outcome text (default)

Creates a service registry entry in the current namespace that points to the issuer endpoint for the OAuth server in the current IRIS instance. This method depends on class parameters OAuthSSLConfigName and OAuthIssuerServiceName for the values of those two items.

This method is only necessary if your OAuth server is already set up as desired and the you want to create a bulk FHIR configuration in a second Foundation namespace.

Arguments:

  • pVerbose:

    0 = do not display method outcome text

    1 = display method outcome text (default)

Note:

Setup of the OAuth 2.0 client configuration can be done automatically, when you create and save your bulk FHIR configuration.

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

FeedbackOpens in a new tab