Skip to main content
Previous sectionNext section

Introduction

The InterSystems IRIS® FHIR Accelerator Service (FHIRaaS) is a reliable, secure, low maintenance solution that your healthcare application can use to store and retrieve FHIR® data, allowing you to leverage powerful FHIR technology from InterSystems without worrying about setting up its infrastructure.

If you want to take a deep dive into the FHIR support provided by FHIRaaS without needing to examine its Capability Statement, see Supported Interactions and Operations.

If you need to set up the FHIRaaS preview, see Set Up FHIRaaS.

If you are new to FHIR and FHIR servers, you can use the Quick Start to use RESTful API requests to store and retrieve FHIR data with little to no prior experience.

The preview of FHIRaaS gives you the opportunity to explore all of its potential without having to wait for the official commercial launch. Being a preview, there are a number of known limitations and incomplete functionality that will be addressed before the commercial release. For a complete list, see Known Issues in Preview.

Set Up FHIRaaS

After signing up for the InterSystems IRIS FHIR Accelerator Service (FHIRaaS), you need to perform a few tasks to get the service up and running.

Create a New Account

The first step toward setting up FHIRaaS is to create an new account in the InterSystems IRIS Self Service Portal:

  1. In your browser, go to the URL provided to you, and click Create New Account.

  2. On the Sign Up screen, enter the requested information, and click SIGN UP.

  3. Type the verification code sent to the email account you provided, and click CONFIRM ACCOUNT.

After you create your new account, you are taken to the InterSystems Deployments page.

You are also sent a welcome email containing a summary of the key FHIRaaS features.

Create a Deployment

After creating an account, you are ready to deploy FHIRaaS in the cloud:

  1. On the InterSystems Deployments page, click CREATE NEW DEPLOYMENT.

  2. On the Create InterSystems Deployment page, in the Deployment Options section:

    1. Under InterSystems IRIS Service, click FHIR® ACCELERATOR SERVICE.

    2. Under Deployment Size, select a size. (“Demo” is the only size available in the preview.)

    3. Click CONTINUE.

  3. In the Cloud Options section:

    1. Under Cloud Provider, select a provider. (“AWS” is the only provider available in the preview.)

    2. Under Region, select a region. (“us-east-2” is the only region available in the preview.)

    3. Click CONTINUE.

  4. In the Deployment Name section:

    1. Type a name for your deployment. This cannot be changed once created.

    2. Click CONTINUE.

  5. In the Review section:

    1. Review the summary information.

    2. Click CREATE.

It takes several minutes to deploy FHIRaaS. You will receive an email notification when the deployment is complete.

When your deployment is created, click the name of the deployment to go to the Overview tab for your new deployment. Here you will see some important summary information, including your FHIR Endpoint, FHIR OAuth Endpoint, and Deployment ID. You will need the Deployment ID in various setup steps and for support purposes.

If you want to delete your deployment at any point, you can do so from the InterSystems Deployments page, by clicking the trash icon next to your deployment name.

The preview is limited to one deployment.

Set Up Access Controls

Once you have created your FHIRaaS deployment, you need to set up an access control mechanism to govern how users and applications can access the service. FHIRaaS supports two such mechanisms, API keys and OAuth 2.0.

API keys can be used to authenticate FHIR requests to FHIRaaS. Each user is assigned a unique API key that is sent in the header of the request to allow access to the service.

OAuth 2.0 involves creating an OAuth Strategy, which associates an identity provider (often called an IdP), which manages users, with a set of scopes, which define the actions a user or application can perform using the service. You can use either an external identity provider, such as your organization’s existing identity provider, or the built-in identity provider. With OAuth 2.0, a user is given a token that grants access to access FHIRaaS, however the access is limited by the scopes associated with the OAuth Strategy.

When you define the scopes for an OAuth Strategy, you also define the launch context:

  • Backend Service—Use for general connections to the FHIR database using a generated token.

  • Patient Standalone—Use when an application connects to the FHIR database with a patient context. This limits the scope to that specific patient.

  • Provider Standalone—Use when an application connects to the FHIR database with a provider context. This limits the scope to that specific provider or patients of that provider. (Not yet available in the preview.)

For more information on API keys and OAuth 2.0, see the Authentication and Authorization section of this document.

Create API Keys

To create an API key:

  1. In your deployment, click the Credentials tab.

  2. Under API Keys, click CREATE AN API KEY.

  3. On the Add API Key dialog, type the Key Name, and click ADD.

    The key name could be the name of a user or an application.

  4. After the API Key is generated, copy and paste it to a safe location. You will not be able to retrieve it after closing the dialog.

  5. Click CLOSE.

The new API key now appears in the list of API keys on the screen. It may take up to a minute for the key to become active.

If you want to delete an API key at any point, click DELETE next to the API key name.

Set Up OAuth 2.0

To use OAuth 2.0, you need to set up an OAuth Stategy using an identity provider. You can use an external identity provider or the built-in identity provider. If you are using the built-in identity provider, you must also create OAuth 2.0 users in order for users or applications to access FHIRaaS.

Set Up an OAuth Strategy

To set up an OAuth Strategy:

  1. In your deployment, click the OAuth 2.0 tab.

  2. Under OAuth 2.0, click the + button.

  3. Under Create OAuth Strategy, in the Identity Provider section:

    1. Select the built-in identity provider Amazon Cognito or one of the external identity providers.

    2. If you selected an external identity provider, follow the instructions for your chosen identity provider.

    3. Click CONTINUE.

  4. In the Identity Provider App Definition section:

    1. Fill in the requested information. This information will differ depending on the type of identity provider you selected.

    2. Click CONTINUE.

  5. In the App Scopes Builder section:

    1. Select a Launch Context.

      This adds scopes to the Selected Scopes box, depending on the launch context you select.

    2. Under Scope Context, Patient or Clinical is selected for you, depending on the Launch Context you selected..

    3. Select Enable All Resources on this Scope Context, or clear this option and select a single resource from the list.

    4. Select the level of Permissions you want to allow for this resource.

    5. Click ADD SCOPE.

      This adds the specified scope to the Selected Scopes box.

    6. If you are adding scopes for individual resources, you can add additional scopes in the same manner.

    7. When you are done defining scopes, click CREATE OAUTH STRATEGY.

The OAuth 2.0 Strategy now appears on the OAuth 2.0 tab.

Click the name of the OAuth Strategy to get a block of code you can use to connect your application to FHIRaaS, or to download a Postman Collection you can import into the REST API client Postman in order to generate a token or send test requests to FHIRaaS.

If you want to delete your OAuth Strategy at any point, you can do so by clicking the trash icon next to your OAuth 2.0 Strategy name.

The preview is limited to one OAuth Strategy per deployment.

Create an OAuth 2.0 User

If you are using an external identity provider, it can be used to manage users who need access to FHIRaaS. But if you are using the built-in identity provider, you must create users:

  1. In your deployment, click the Credentials tab.

  2. Under OAuth 2.0 Users, click CREATE IDP USER.

  3. On the Create User dialog, type the Username and Password, and click CREATE.

The user now appears in the list of OAuth 2.0 users

If you want to remove a user’s access at any point, click DISABLE in the row for that user.

Quick Start

Once you have deployed the InterSystems IRIS FHIR Accelerator Service (FHIRaaS), you can take the following tour to familiarize yourself with FHIR® resources and begin making RESTful FHIR requests.

Find Your FHIR Endpoint

FHIRaaS has a unique URL that serves as the base of the RESTful FHIR requests made to the service. This is the FHIR endpoint that you use to work with FHIR data. For example, the request to retrieve a particular patient might be GET https://myEndpoint/Patient/10 while a request that stored an Observation might be POST https://myEndpoint/Observation.

Just navigate to the Overview tab to find the FHIR endpoint of your FHIRaaS. For example, the FHIR endpoint might look like:

https://fhir.z4xyins06h.accelerator.intersystems.cloud.io

Obtain an API Key

All requests to FHIRaaS must be authenticated, whether it be with an API key or through OAuth 2.0. For the purposes of this Quick Start, you will use an API key to authenticate the requests.

The Credentials tab allows you to add multiple users who can access the FHIRaaS. Each user is given a unique API key when their account is created. For security, this key cannot be accessed again once the dialog is dismissed, so make sure it is copied to a safe place!

Shortcut: If you are familiar with FHIR requests and like to use a REST client like Postman, you now have all the information you need to start interacting with FHIRaaS. Use the FHIR endpoint as the base URL of your FHIR requests, and authenticate those requests by putting your API key in the x-api-key header. However, if you are new to FHIR or RESTful APIs, you can continue with this Quick Start by using the FHIRaaS Developer Portal.

Explore the Developer Portal

The Developer Portal found on the API Development tab is a great way to familiarize yourself with FHIR resources and make basic API requests that store and retrieve these resources from FHIRaaS.

Learn About the Patient Resource

The Developer Portal allows you to learn more about individual FHIR R4 resources, which is particularly useful if you are new to FHIR.

  1. From the Choose FHIR Resource drop-down, select Patient.

    When you are done with the Quick Start, you can use this drop-down to learn about other resources.

  2. Next, expand the POST /Patient section of the Developer Portal.

  3. From here, you can learn more about the structure of a FHIR R4 Patient resource by looking at sample Patients.

    The Example Value text box uses JSON to display the Patient sample that is currently selected in the Examples drop-down.

  4. Look at the Schemas section of the page to explore the data types, descriptions, and hierarchy of the fields of a valid FHIR R4 Patient resource.

    To see how a Patient is described in the official FHIR specification, see Resource Patient - Content.

Authenticate Your FHIR Requests

Like all requests to FHIRaaS, the requests made through the Developer Portal must be properly authenticated. To authenticate your requests made through the Developer Portal:

  1. Near the top of the API Development tab, click Authorize.

  2. In the Value field of the apiKey section, paste the API key that was displayed when you created the user on the Credentials tab.

  3. Click Authorize.

  4. Click Close.

If you want to use a different user to explore the Developer Portal, you will have to log out the current user, then enter the new API key. To log out a user, select the Authorize button again, and select Logout. There is no way to determine who is currently logged into the Developer Portal.

Add a Patient

You can use the Developer Portal to add Patient resources to FHIRaaS without needing to know the syntax of the FHIR request. In FHIR development, adding a resource is accomplished with the create interaction. To add a Patient to the service:

  1. Expand the POST /Patient section.

  2. Click Try It Out.

  3. Ensure that patient-example-a.json is selected in the Examples drop-down. Notice that the value of the Patient’s gender field is male.

  4. Click Execute.

You can review the cURL call that was executed, which gives you an idea of the FHIR request your application would make to add a Patient.

Search for Patients

Just as you can use the POST /Patient endpoint to add a Patient to FHIRaaS, the Developer Portal allows you to use a GET /Patient endpoint to retrieve Patient resources from the service. Executing a request to this endpoint without specifying parameters will retrieve all of the Patient resources, including the one you just added. However, in this Quick Start, you will retrieve only male patients.

  1. Expand the GET /Patient section.

  2. Click Try It Out.

  3. Scroll through the parameter fields until you find gender, which is a standard search parameter for Patient resources.

  4. Enter male.

  5. Scroll down and click Execute.

You can review the cURL call that was executed, which gives you an idea of the FHIR request your application would make to retrieve a Patient using one or more search parameters. Notice that gender=male is added to the end of the endpoint as a query parameter.

The Response Body displays a FHIR bundle that contains all of the male Patients in your FHIRaaS. You can download this JSON bundle to make it easier to inspect its contents, including finding the Patient that you added during this Quick Start.

Use a REST Client

When using Postman, Advanced REST Client, or any other REST client, be sure to authenticate each request by specifying your API Key as the value of the x-api-key header parameter. For example, your request could include x-api-key: 80nlTZOMyAPIKey. Of course, if FHIRaaS is secured with OAuth 2.0, you can use a token to authenticate your requests.

While the API Development tab is a great way to start exploring the capabilities of FHIRaaS, if you want to try out more complex queries that leverage all of the available search parameters, you need to use a REST client. For a complete list of the standard search parameters, modifiers, and prefixes that are available with FHIRaaS, see Search Interaction. These parameters, modifiers, and prefixes can be applied to all searches.

Of course, you can mix these common search parameters with resource-specific parameters when performing a query. As you have seen in this Quick Start, the API Development tab lists all of the resource-specific parameters that are available when searching for resources. These resource-specific parameters are also summarized in the official FHIR specification; for example, you can review the Patient-specific search parameters.

Authentication and Authorization

FHIR® requests that are made to the FHIRaaS can be authenticated with API keys or through OAuth 2.0.

API Key Credentials

The Credentials tab allows you to obtain API keys that can be used to authenticate FHIR requests to FHIRaaS. Each new user is assigned a unique API key that must be copied to a safe location; once you dismiss the dialog with the key, it cannot be retrieved.

FHIR requests to FHIRaaS are authenticated by including the API key in the header of the request. Simply include the key as the value of the x-api-key header.

OAuth 2.0

The FHIRaaS OAuth solution is centered around having an Identity Provider (IdP) that manages your organization's users and applications. During development, if you want a simplified way to send OAuth tokens to the FHIRaaS from an application, you can use the FHIRaaS built-in IdP. However, an enterprise-grade solution that leverages OAuth and OpenID Connect will most likely include an external, third party IdP. In such an implementation, authentication (OpenID Connect) and authorization (OAuth 2.0) for your application is handled by your IdP, not FHIRaaS. FHIRaaS simply enforces the OAuth tokens obtained from the IdP when responding to FHIR requests from the application.

In many cases, your organization's IdP will already include the users who will be accessing the application that connects to FHIRaaS. For example, members of a health insurance company who use applications built for the organization will likely already be users in an IdP. In this scenario, you will simply register your new application with the IdP and give the existing users permissions to access the application. In FHIRaaS, you create an OAuth Strategy for the application. An OAuth Strategy identifies the application within the IdP and defines the FHIR scopes that the application will be requesting from the IdP.

Roles and Responsibilities

Keeping patient data, including Protected Health Information (PHI), safe and secure is of utmost importance in a healthcare application. FHIRaaS is designed to use OAuth to protect PHI by inspecting access tokens that accompany FHIR requests from the application. FHIRaaS will reject any request that tries to exceed the authorization provided by the scopes of the token.

The following actors are involved in setting up an application to use OAuth 2.0 and OpenID Connect to store and retrieve FHIR resources from FHIRaaS. In many cases, especially early in development, one individual might fill more than one role.

Role Responsibilities
Identity Provider Administrator When an external Identify Provider (IdP) is being used for authentication, the IdP Administrator must register the application with the IdP before the FHIRaaS Administrator can create the OAuth Strategy. The IdP Administrator is also responsible for adding application users to the IdP so their credentials can be verified in order to issue an access token.
FHIRaaS Administrator The FHIRaaS Administrator is responsible for creating an OAuth Strategy for the application and providing the strategy’s access details to the Application Developer. As part of this process, the FHIRaaS Administrator defines the FHIR scopes that the application will be specifying in its request for a token. An application cannot ask the IdP for more scopes than are defined by the OAuth Strategy.
Application Developer The Application Developer is responsible for creating the application, such as a SMART on FHIR app, that accesses FHIRaaS data. The Application Developer takes the access details of the OAuth Strategy and modifies values of a SMART app’s authorization methods to obtain access tokens.
When the access token accompanying a request includes a scope to access data in a specific Patient’s compartment, it is the application’s responsibility to set the correct patient context value. For example, if the application user should only be able to view resources pertaining to Patient 1497, then the application must properly set the patient context value to 1497.
Though the FHIRaaS Administrator defines what scopes are possible, it is the Application Developer’s responsibility to ensure that a user’s request includes the proper scopes in order to protect Protected Health Information (PHI).

SMART on FHIR Applications

The following is the workflow that the FHIRaaS Administrator and IdP Administrator follow to enable OAuth 2.0 and OpenID Connect security for an application that accesses FHIRaaS data. Often, the Application Developer/FHIRaaS Administrator might use a built-in IdP to begin development, thereby removing the need to consult an expert in the organization’s IdP.

Note:

It is beyond the scope of FHIRaaS documentation to explain how to register an application with an IdP or find the values of the IdP app definition that are needed when creating an OAuth Strategy. Consult your organization’s IdP expert or the IdP documentation

If an external Identity Provider (IdP) is being used for authentication, the IdP Administrator must register the application with the IdP before the FHIRaaS Administrator can create the OAuth Strategy for the application. Though different IdPs use different language, the basic concepts are the same: the IdP Administrator provides information about the application to the IdP ("registration"), and receives back some values that uniquely identify the application within the IdP. In FHIRaaS, these details that identify the application within the IdP are known as an IdP app definition.

Before the IdP Administrator can register the application with the IdP, they need information from the FHIRaaS Administrator. The FHIRaaS Administrator can obtain these values from OAuth 2.0 tab.

Assuming that your SMART on FHIR app is built with the fhir-client.js javascript library, integrating the app with FHIRaaS consists of a simple change to the launch.html page of the app. Specifically, the options of the FHIR.oauth2.authorize method must be updated with values provided by the FHIRaaS OAuth Strategy. For details about setting up an OAuth Strategy for your SMART app, see OAuth 2.0.

Once it is defined, the OAuth Strategy for your SMART app is located on the OAuth 2.0 tab. It contains all of the possible values you need to modify the FHIR.oauth2.authorize method. Specifically, the OAuth Strategy provides client_id, clientSecret, scope, redirect_uri, and iss. Not all SMART apps will use all of these values. For example, the launch.html page of an app might include:

<script>
      FHIR.oauth2.authorize({
      "client_id": "19eaog9eoo7fp41adhlshg9o5e",
      "clientSecret": "pbidk5fqdttcskegd7a0c0a4mv752f0uu3doi3b72paepucjasu",
      "scope": "openid profile launch/patient patient/*.read",
      "redirect_uri": "https://localhost:9000/index.html",
      "iss": "https://fhirauth.ypvzqtqq.static-test-account.isccloud.io/oauth2"
      });
</script>
Copy code to clipboard

For more details about the FHIR.oauth2.authorize method and its options, see the SMART API page of the SMART on FHIR JavaScript Library documentation.

Access Logs

The Access Logs tab provides valuable information on who is using your service, and what FHIR requests they are making. For each request, the logs show:

  • Request Time

  • Source IP Address

  • User Agent

  • API Key

  • HTTP Method

  • Status

  • Integration Status

  • Request Path

The Status and Integration Status need to be considered together to form a complete picture. For example, an unauthenticated request might return a Status of 403, but show no Integration Status because the request was blocked from reaching the service. A request that is authenticated but does not have the proper scope might return a Status of 403, but an Integration Status of 200, meaning that the request reached the service, but the request could not be fulfilled due to the improper scope. A successful request returns a Status of 200 and an Integration Status of 200.

To download the access logs in JSON format, click DOWNLOAD LOGS.

Data Management

Adding data to your FHIR database is a two-step process. First, you upload FHIR bundles, in JSON format, using either the Self-Service Portal or SFTP (Secure File Transfer Protocol). Then, in the portal, you import the FHIR bundles you uploaded so that the resources contained in the bundles are available in the database.

You can perform these tasks on the Data Management tab of the Self-Service Portal. The FHIR Data Overview section at the top of the page displays a summary of the resources currently in the FHIR database, as well as the bundles that have been uploaded and are available for you to import. You can also use this section to delete all resources from the database. This can be useful if you are using test data during application development and you want to clear the database in order to load live data.

Upload FHIR Bundles Using the Self-Service Portal

To upload your FHIR bundles using the Self-Service Portal:

  1. On the Data Management tab for your deployment, in the Upload Data section, click the box marked Click here to select your bundles to import.

  2. In the system dialog box, browse for your FHIR bundles and select the files you wish to upload.

  3. Click UPLOAD.

A counter above the UPLOAD button tracks the number of bundles that have been uploaded. You also can look at the FHIR Data Overview section at the top of the page to monitor the progress of the upload. You may need to click REFRESH to update the display.

Upload FHIR Bundles Using SFTP

You can upload FHIR bundles using either the SFTP from the command line or using your favorite FTP client.

To use either method, you must download the private key provided for you:

  1. On the Data Management tab for your deployment, in the Upload Data with SFTP section, click the KEY button.

  2. Store the private key in a location where you can access it when you need to perform an upload.

To upload a FHIR bundle from the command line, use the command shown in the Upload Data with SFTP section of the page, as in the following example:

C:\uploads>sftp -i qjzdbnsd-sftp-key.pem qjzdbnsd@sftp.qjzdbnsd.static-test-account.isccloud.io
Connected to qjzdbnsd@sftp.qjzdbnsd.static-test-account.isccloud.io.
sftp> pwd
Remote working directory: /qjzdbnsd-sftp-bucket/home
sftp> cd fhir
sftp> pwd
Remote working directory: /qjzdbnsd-sftp-bucket/home/fhir
sftp> lcd mybundles
sftp> put testbundle.json
Uploading testbundle.json to /qjzdbnsd-sftp-bucket/home/fhir/testbundle.json
testbundle.json                                                  100% 1281KB   2.2MB/s   00:00

sftp> quit
Copy code to clipboard

In this example, the Deployment ID is qjzdbnsd, the private key is located in the directory C:\uploads, and the FHIR bundles to be uploaded are located in the mybundles subdirectory.

When you connect to the FTP server, you are placed in the home directory, in this example /qjzdbnsd-sftp-bucket/home. You must change your remote working directory to the fhir subdirectory before uploading them in order to import them from the Self-Support Portal later.

Change your local directory to the location where your FHIR bundles to be uploaded are stored, and upload them with the put command. In this example, the bundle testbundle.json is uploaded to the FTP server.

As mentioned earlier, you can also use an FTP client to interactively upload your FHIR bundles. Again, remember to upload them to the fhir subdirectory.

You can look at the FHIR Data Overview section at the top of the page to monitor the progress of the upload. You may need to click REFRESH to update the display.

Note:

If you encounter an error message like “Permissions 0644 for ‘qjzdbnsd-sftp-key.pem’ are too open,” you must remove any permissions on your private key file for other users.

On Unix, set permissions using the chmod command, for example: chmod 400 qjzdbnsd-sftp-key.pem.

On Windows, right-click your private key file, and on the Security tab, click Advanced. Make sure you are the owner, and then remove permissions for all other users.

Import FHIR Bundles

After all of the FHIR bundles you uploaded are available for import, you are ready to import them into your FHIR database:

  1. On the Data Management tab for your deployment, in the FHIR Data Overview section, click IMPORT.

  2. In the dialog box notifying you that you have submitted a Data Import Job, click ACKNOWLEDGE.

You can look at the FHIR Data Overview section to monitor the progress of the import. You may need to click REFRESH to update the display. The display will be updated with the current number of resources in the database, while the number of resources available for import will decrease to zero.

After the bundles are successfully imported, they are removed from the FTP directory.

Backups

The Backup tab provides a mechanism to make a backup of your FHIR database, to restore a backup to the database, or to delete a backup.

Make a Backup

To make a backup of the FHIR database, on the Backup tab, click CREATE BACKUP.

The backup appears in the list of backups on the Backup tab. The Status of the backup is shown as IN PROGRESS until the backup is complete, at which time the Status changes to SUCCESS. The CREATE BACKUP button is disabled while a backup is in progress.

Restore a Backup

To restore a backup to the FHIR database, click RESTORE in the row for that backup.

The screen displays a Restoring indicator until the process is complete.

Delete a Backup

To delete a backup, click DELETE in the row for that backup.

The screen displays a Deleting indicator until the process is complete. After the deletion is complete, the backup remains in the list, with a Status of DELETED.