Bulk FHIR Coordinator

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.

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.

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.

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.

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

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.

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.

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.

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.

Directory where temporary files are stored before they are passed to the storage file 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:

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.

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.

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

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.

Each OAuth client configuration also has a Client ID and Client Secret (indicated 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.

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

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.

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.

The BFC exports Newline Delimited JSON (ndjson) files.

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

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

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

• The BFC is processing the export.

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

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

  

• An error occurred on the BFC.

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.

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.

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.

The %HS_BFC_Download_Manage role has the following permissions:

• Download files from all exports.

Use to expand the privileges of %HS_BFC_Administrator.