Skip to main content

Introduction

The InterSystems IRIS® FHIR® Accelerator Service 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 subscribe to FHIR Accelerator Service, see Subscribe to the FHIR Accelerator Service.

If you want to preview the FHIR Accelerator Service for 30 days, skip to Set Up the FHIR Accelerator Service. Previewing the FHIR Accelerator Service gives you the opportunity to explore all of its potential without having to sign up for a subscription.

Once you have created a deployment of the FHIR Accelerator Service, you can use the Guided Tour to learn how to use RESTful API requests to store and retrieve FHIR data with little to no prior experience.

Before creating an application that uses the FHIR Accelerator Service, you need to choose an Authentication and Authorization strategy, using API keys or OAuth 2.0. Then you will need to Set Up Access Controls.

The remainder of this chapter covers the management of the FHIR Accelerator Service using the InterSystems Managed Services Portal.

To take a deep dive into the FHIR support provided by the FHIR Accelerator Service without needing to examine its Capability Statement, see Supported Interactions and Operations.

To learn how a development team can work together using the FHIR Accelerator Service, see Team Development.

If you encounter any difficulties while using the FHIR Accelerator Service, see Known Issues.

Subscribe to the FHIR Accelerator Service

FHIR Accelerator Service is available as a subscription in the AWS Marketplace. You must have an Amazon Web Services account to subscribe.

To subscribe to the FHIR Accelerator Service:

  1. Log in to the AWS Console, and then search for “InterSystems” in the AWS Marketplace.

  2. Click FHIR Accelerator Service in the search results to open the product page.

  3. On the product page, read the Product Overview and the other information, and then click Continue to Subscribe.

  4. Review the pricing details, and click Subscribe.

  5. In the pop-up window, click Set Up Your Account to get redirected to the InterSystems Managed Services Portal.

  6. Proceed with the steps in Set Up the FHIR Accelerator Service.

After you subscribe to the FHIR Accelerator Service, you will see it listed on your AWS Marketplace Subscriptions page. If you ever decide to cancel your subscription, you must do it from this page. All billing for the FHIR Accelerator Service is handled by AWS.

Set Up the FHIR Accelerator Service

In order to use the FHIR Accelerator Service, you need to perform a few tasks to get the service up and running, including logging in to the InterSystems Managed Services Portal and creating a deployment.

Log in to the InterSystems Managed Services Portal

If you have an account in the InterSystems Managed Services Portal, log in to the portal.

If you do not have an account, sign up for one, as follows:

  1. In your browser, go to the InterSystems Managed Services Portal login page, and click Create New Account.

  2. On the Sign Up page, 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.

Create a Deployment

After logging in to the InterSystems Managed Services Portal, the next step is to deploy the FHIR Accelerator Service in the cloud.

You can deploy the FHIR Accelerator Service as a subscriber or as a preview user. If you are a preview user, you can subscribe before the preview expires to unlock the full capabilities of the service. Your deployment will begin to accrue AWS charges at that time.

Note:

If you have just subscribed to the FHIR Accelerator Service in the AWS Marketplace, you may need to wait a few minutes for the subscription to be finalized. You can check to see if this has occurred by clicking Settings on the main menu of the Managed Services Portal and then clicking Account. In the Subscriptions section, the FHIR Accelerator Service should have a Status of subscribe-success.

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

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

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

    2. Under Deployment Size, select a size.

      A description of the typical use case is listed for each size. You can change your deployment size later on the Resources page of the Managed Services Portal. (“Preview” is the only size available to preview users.)

    3. Optionally, select the Highly Available (HA) Configuration to deploy a mirrored backup server automatically to minimize or eliminate downtime to the FHIR Accelerator Service.

      Note:

      Selecting this option will result in a higher cost to your subscription. This feature cannot be enabled or disabled after the deployment is created.

    4. Click CONTINUE.

  3. In the Cloud Options section:

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

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

    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 a few minutes to deploy the FHIR Accelerator Service. When the deployment has completed, the status under the deployment name changes to COMPLETE.

Click the name of the deployment to go to the Overview page for your new deployment. This page contains summary information, including your deployment’s expiration date, API Key and OAuth 2.0 endpoints, and Deployment ID. You will need the Deployment ID in various setup steps and for support purposes. For more information, see Overview Page.

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.

Preview users are limited to one deployment.

Guided Tour

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

Find Your FHIR Endpoint

The FHIR Accelerator Service 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 stores an Observation might be POST https://myEndpoint/Observation.

Just navigate to the Overview page to find the FHIR endpoint of your FHIR Accelerator Service. For example, the FHIR endpoint might look like:

https://fhir.yaetvlxv.static-test-account.isccloud.io

Obtain an API Key

All requests to the FHIR Accelerator Service must be authorized, whether it be with an API key or through OAuth 2.0. For the purposes of this Guided Tour, you will use an API key to authorize the requests.

The Credentials page allows you to add an API key for each user who can access the FHIR Accelerator Service. Create an API key now to use for this tour. For security reasons, this key cannot be accessed again once the dialog is dismissed, so make sure to copy it to a safe place! For more information on creating an API Key, see API Keys.

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 the FHIR Accelerator Service. Use the FHIR endpoint as the base URL of your FHIR requests, and authorize 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 Guided Tour by using the FHIR Accelerator Service Developer Portal.

Explore the Developer Portal

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

The FHIR Accelerator Service comes preloaded with synthetic healthcare data so that you can get started right away, without having to generate your own test data or de-identify existing data.

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 list, select Patient.

    When you are done with the Guided Tour, you can use this drop-down list 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 list.

  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.

Authorize Your FHIR Requests

Like all requests to the FHIR Accelerator Service, the requests made through the Developer Portal must be properly authorized. To authorize your requests made through the Developer Portal:

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

  2. In the Value field of the apiKey section, paste the API key you created on the Credentials page.

  3. Click Authorize.

  4. Click Close.

When you are done using the API Development page, click the Authorize button again, and then click Logout.

Add a Patient

You can use the Developer Portal to add Patient resources to the FHIR Accelerator Service 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 list. 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 the FHIR Accelerator Service, 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 Guided Tour, 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. Type 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 FHIR Accelerator Service. You can download this JSON bundle to make it easier to inspect its contents, including finding the Patient that you added during this Guided Tour.

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 the FHIR Accelerator Service is secured with OAuth 2.0, you can use a token to authenticate your requests.

While the API Development page is a great way to start exploring the capabilities of the FHIR Accelerator Service, 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 the FHIR Accelerator Service, 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 Guided Tour, the API Development page 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 FHIR Accelerator Service can be authenticated by API Key or OAuth 2.0/OpenID Connect using an identity provider (IdP).

API Key Credentials

API keys can be used to authenticate FHIR requests to the FHIR Accelerator Service. Each user is assigned a unique API key that is sent in the header of the request to allow access to the service, as shown in the following example.

curl -i -X POST "https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/Patient" 
-H "x-api-key:<YOUR-API-KEY>" -H "accept: application/fhir+json" -H "Content-Type: application/fhir+json" 
-i -d "{ \"name\": [ { \"use\": \"official\", \"family\": \"Johnson\", \"given\": [ \"Darcy\" ] } ], 
\"gender\": \"female\", \"birthDate\": \"1970-02-02\", \"resourceType\": \"Patient\" }"

OAuth 2.0/OpenID Connect

The FHIR Accelerator Service OAuth solution is centered around having an authentication server that manages your organization's users and applications. During development, if you want a simplified way to send OAuth tokens to the FHIR Accelerator Service from an application, you can use the FHIR Accelerator Service integrated authentication server. However, an enterprise-grade solution that leverages OAuth and OpenID Connect will most likely use an authentication server that uses 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 the FHIR Accelerator Service. The FHIR Accelerator Service 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 the FHIR Accelerator Service. 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 the FHIR Accelerator Service, you configure your IdP as an authentication server. Then you configure the application to use that authentication server.

When using OAuth 2.0, the user is assigned a temporary token that is sent in the header of the request to allow access to the service, as shown in the following example.

curl -i -X POST "https://fhirauth.c1zncw08fpyg.static-test-account.isccloud.io/oauth2/Patient" 
-H "Authorization: Bearer <YOUR-TOKEN>" -H "accept: application/fhir+json" -H "Content-Type: application/fhir+json" 
-i -d "{ \"name\": [ { \"use\": \"official\", \"family\": \"Johnson\", \"given\": [ \"Darcy\" ] } ], 
\"gender\": \"female\", \"birthDate\": \"1970-02-02\", \"resourceType\": \"Patient\" }"

Roles and Responsibilities

Keeping patient data, including Protected Health Information (PHI), safe and secure is of utmost importance in a healthcare application. The FHIR Accelerator Service is designed to use OAuth to protect PHI by inspecting access tokens that accompany FHIR requests from the application. The FHIR Accelerator Service 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 the FHIR Accelerator Service. 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 FHIR Accelerator Service Administrator can configure the authentication server and application in the InterSystems Managed Services Portal. 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.
FHIR Accelerator Service Administrator The FHIR Accelerator Service Administrator is responsible for configuring the authentication server and application in the InterSystems Managed Services Portal and providing the configuration details to the Application Developer. If using the integrated authentication server, The FHIR Accelerator Service Administrator also defines the FHIR scopes that the application will be specifying in its request for a token.
Application Developer The Application Developer is responsible for creating the application, such as a SMART on FHIR app, that accesses FHIR Accelerator Service data. The Application Developer takes the access details of the application’s configuration 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 Identity Provider Adminstrator or FHIR Accelerator Service 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).

Set Up Access Controls

Once you have created your FHIR Accelerator Service deployment and chosen API keys or OAuth 2.0 as an authentication and authorization strategy, you need to set up the access controls needed to govern how users and applications can access the service.

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

Create API Keys

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

You can create and manage API keys on the Credentials page for your deployment.

Set Up OAuth 2.0

To use OAuth 2.0, you need to configure an authentication server and one or more associated applications.

The authentication server is used to authenticate users of your service and can be the integrated authentication server or an external authentication server. The integrated authentication server, built on Amazon Cognito, gives you a quick way to get up and running with the FHIR Accelerator Service. An external authentication server is the preferred solution for organizations that have an existing identity provider (often called an IdP) that can be used to manage users and provide authentication.

An application is a means of tying a FHIR-enabled application to the authentication server. If you are using the integrated authentication server, creating an application allows you to define an authentication flow, as well as set up the scopes that will be used to provide the user with the authorization needed to access the required FHIR resources. If you are using an existing IdP, you need to set up the application in the administrative console of your IdP. Configuring the application in the Managed Services Portal is then a matter of entering the Client ID and Client Secret of your application, as determined by your IdP.

You can configure an authentication server and its associated applications on the OAuth 2.0 page for your deployment.

If you are using the integrated authentication server, you must also create users who will be permitted to log in to the authentication server in order for them to use the application to access the FHIR Accelerator Service. You can create users on the Credentials page for your deployment.

Overview Page

The Overview page contains two sections: Deployment Details, which contains useful information about your deployment, and FHIR® Details, which provides a summary of your deployment’s FHIR endpoints.

Deployment Details

In the Deployment Details section, you can view the details of your deployment, including:

  • Deployment size

  • Number of cores

  • Amount of RAM

  • Deployment ID

  • Underlying InterSystems IRIS platform and version

  • Cloud provider and region

  • Creation and expiration dates

  • High Availability Status

FHIR® Details

In the FHIR® Details section, you can find the URLs of your deployment’s API Key Endpoint and OAuth 2.0 Endpoint.

If you are using API keys to control access to the FHIR Accelerator Service, click the FHIR REQUEST API KEY SAMPLES button to obtain sample cURL commands you can use as templates for constructing API requests to send to the FHIR Accelerator Service using the command line, a REST client, or an application. You can generate an API Key to use with these samples in the API Keys section of the Credentials page, as described in Create API Keys.

If you are using OAuth 2.0 to control access to the FHIR Accelerator Service, click the FHIR REQUEST OAUTH2 SAMPLES button to obtain sample cURL commands you can use as templates for constructing API requests to send to the FHIR Accelerator Service using the command line, a REST client, or an application. If you are using the integrated authentication server, you can generate a token to use with these samples on the Applications tab of the OAuth 2.0 page, as described in Configure an Application Using the Integrated Authentication Server.

You can also generate sample cURL commands on the API Development page, as described in Explore the Developer Portal.

Metrics Page

In contrast with the access logs, which show information regarding individual FHIR requests, the Metrics page for a deployment shows summary statics for a given route, including the overall count of requests made (either using an API Key or OAuth 2.0), the latency (in milliseconds), and the number of 4xx and 5xx status errors.

OAuth 2.0 Page

The OAuth 2.0 page allows you to manage the authentication servers and applications in your deployment.

The Authentication Servers tab of the OAuth 2.0 page lists all of the configured authentication servers for your deployment. These authentication servers can be either integrated (if you are not using an existing IdP to manage users) or external (if you are using an existing IdP to manage users). This tab also allows you to configure new authentication servers or delete existing authentication server configurations from your deployment.

The Applications tab of the OAuth 2.0 page lists all of the configured applications for your deployment and allows you to view their details. If you have more than one authentication server configured, you can filter the tab so that it displays only applications associated with a particular authentication server. This tab also allows you to configure new applications or delete existing application configurations.

For background information on how the FHIR Accelerator Service uses OAuth 2.0, see OAuth 2.0/OpenID Connect. For basic information on deciding how to set up your OAuth 2.0 strategy, see Set Up OAuth 2.0.

Configure an Authentication Server

To configure an authentication server:

  1. In your deployment, click OAuth 2.0 on the main menu.

  2. On the OAuth 2.0 page, click the Authentication Servers tab.

  3. In the Configured Authentication Servers section, click CREATE AUTHENTICATION SERVER.

  4. In the Create Authentication Server section, type a Name for your authentication server.

  5. Select an Authentication Server Type.

    If you do not have (or do not want to use) an existing IdP, select the integrated authentication server. Otherwise, select the platform that matches your existing IdP.

  6. If you are using an external authentication server, type the Issuer Discovery URL for your IdP.

    An example is provided as a guide to the expected format of the URL.

  7. Click CREATE.

The authentication server now appears in the Configured Authentication Servers section.

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

Note:

You cannot delete an authentication server that has one or more applications associated with it. Delete any associated applications before deleting the authentication server.

You can configure a maximum of one integrated authentication server.

Configure an Application Using the Integrated Authentication Server

To configure an application when using the integrated authentication server:

  1. On the OAuth 2.0 page for your deployment, click the Applications tab.

  2. In the Configured Applications section, click CREATE APPLICATION.

  3. In the Create Application section, under Authentication Server, select the integrated authentication server from the drop-down list.

    This list contains all authentication servers you have configured, both integrated and external.

  4. Type a Name for your application.

  5. Select the Authentication Flow that is appropriate for your FHIR-enabled application.

    Read the Use Case for each type of application to help you decide which authentication flow to use.

  6. Select the Grant Type that is appropriate for your FHIR-enabled application.

  7. If you have already developed a FHIR-enabled application and want to connect it to the FHIR Accelerator Service, type its Redirect URL and Logout URL.

  8. For manual testing of the FHIR Accelerator Service using OAuth 2.0, check the Quick Create box to use the default callback Redirect URL and Logout URL.

  9. Optionally, check the Generate Secret box, if you need to generate a Client Secret.

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

      • Select Backend Service for testing purposes or to connect an application to the FHIR Accelerator Service without context.

      • Select Patient Standalone to connect an application to the FHIR Accelerator Service with a patient context. This limits the scope to that specific patient.

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

    3. Under Resources, select Enable All Resources on this Scope Context, or clear this option and select a single resource from the drop-down 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.

  11. When you are done defining scopes, click CREATE.

The application now appears in the Configured Applications section. If you have multiple authentication servers, you can filter your applications by using the Authentication Server drop-down list.

Click an application to:

  • View the details of the application, including the scopes defined for the application.

  • Obtain the Client ID, Client Secret (if you generated one), and OpenID endpoints you may need to further configure your FHIR-enabled application.

  • Download a Postman Collection you can import into the REST API client Postman in order to generate a token or send test requests to the FHIR Accelerator Service.

  • Generate an access token right from the Managed Services Portal. You will be asked to authenticate as an OAuth 2.0 user known to your authentication server.

If you want to delete your application at any point, you can do so by clicking the application and then clicking DELETE at the bottom of the page.

Configure an Application Using an External Authentication Server

To configure an application when using an external authentication server:

  1. On the OAuth 2.0 page for your deployment, click the Applications tab.

  2. In the Configured Applications section, click CREATE APPLICATION.

  3. In the Create Application section, under Authentication Server, select an external authentication server from the drop-down list.

    This list contains all authentication servers you have configured, both integrated and external.

  4. Type a Name for your application.

  5. Enter the Client ID and Client Secret for your application, as defined by your IdP.

  6. If you have already developed a FHIR-enabled application and want to connect it to the FHIR Accelerator Service, type its Redirect URL and Logout URL.

  7. For manual testing of the FHIR Accelerator Service using OAuth 2.0, check the Quick Create box and use the default callback Redirect URL and Logout URL.

  8. Click CREATE.

The application now appears in the Configured Applications section. If you have multiple authentication servers, you can filter your applications by using the Authentication Server drop-down list.

Click an application to view the details of the application, including the application secrets.

If you want to delete your application at any point, you can do so by clicking the application and then clicking DELETE at the bottom of the page.

Credentials Page

The Credentials page can be used to manage API keys, if you are using them as a mechanism to control access to the FHIR API. This page can also be used to manage users, if you are using the integrated authentication server for OAuth 2.0 authentication and authorization.

API Keys

To create an API key:

  1. In your deployment, click Credentials on the main menu.

  2. Under API Keys, click CREATE 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 page. 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.

Authentication Server Users

To create a user for the integrated authentication server :

  1. In your deployment, click Credentials on the main menu.

  2. Under Authentication Server Users, click CREATE USER.

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

The user now appears in the list of authentication server users

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

Note:

If you are using an external IdP to manage users for OAuth 2.0, add or delete users using the administrative console of your IdP

API Development Page

The API Development page, sometimes referred to as the Developer Portal, presents a Swagger specification for the FHIR Accelerator Service API. This provides you with documentation on the available FHIR resource types and the methods that can be used to access or manipulate resources of each type.

This page can also be used as an interactive development tool so that you can easily send a test API request to the FHIR Accelerator Service by using a handy form-based interface. You can then view the cURL command equivalent to your API request, including the headers and the body of the HTTP request sent to the API. You can also use the cURL command as a template in the code of your application. Using the Development Portal, you can also inspect the response code, headers, and body of the response (in JSON format) to learn about the data that is returned for that request.

For a quick hands-on tutorial of the API Development Page, see the Guided Tour, or continue reading the sections below.

Note:

You can also use the API to import resources by posting it to the root URL of your FHIR endpoint. For more in formation see Import Bundles Using the API.

Resources

The API Development page is organized by resource type, such as Patient, Claim, Encounter, or Medication.

For example, a Patient resource is a block of data that contains demographic or administrative information about a patient, either human or animal, such as name, address, birth date, or gender. A Patient also has a Resource Identifier, or id, that uniquely identifies the patient within the FHIR database. This id should not be confused with an identifier assigned by a business identity, though a Patient resource can contain these, as well.

A Patient resource can also contain metadata, which is data about the resource itself, not the patient. If you search for a patient in the FHIR database using the patient’s id, you might notice that the resource that is returned contains a metadata element that includes the version number of the resource or the last date and time the resource was updated. If you were to update the address of a patient and again search for that patient, you would see that the version number is incremented and the last updated date/time matches the time you made the change.

A collection of resources is called a bundle. If you do a search for all the patients in the FHIR database, these are returned as a bundle. If you request the history for a patient, you receive a bundle containing all the versions of that patient’s resource. If you want to add a number of patients to the FHIR database, you can upload a bundle of patients on the Data Management page or send the bundle using an API request. A bundle can also contain resources of many different types, such as a patient and the patient’s immunization resources.

Use the Choose FHIR Resource drop-down list on API Development page to view the specification for a particular resource type or to test its available methods.

Authorization

You can view the documentation for any resource type on the API Development page without needing authorization, including sample data that might be returned if you used one of the available methods for that resource type. However, you need to have an API key to actually send an API request and access the data in the FHIR database.

To authorize your API requests:

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

  2. In the Value field of the apiKey section, paste a valid API key.

    If you do not have an API key, a user with the admin role can create one on the Credentials page.

  3. Click Authorize.

  4. Click Close.

When you are done using the API Development page, click the Authorize button again, and then click Logout.

Methods

The top section of the API Development page lists the actions that can be performed for a given resource type. These actions are composed of a method (or verb) and an endpoint.

Common methods you will see in the FHIR Accelerator Service API include: POST (create), GET (read), PUT (update), or DELETE (delete).

The behavior of these methods depends on the endpoint listed next to the method. Some of the endpoints contain path parameters, which are indicated by curly brackets.

The table below summarizes the methods that are available for the Patient resource type, and a more detailed discussion follows the table. The methods for the other resource types are similar.

Patient Resource Methods
Method Endpoint Purpose Notes
POST /Patient Adds a new patient to the database Request body contains contents of Patient resource.
GET /Patient Searches for patients Optionally, use parameters to narrow search. Returns bundle of Patient resources in response body.
GET /Patient/{id} Returns Patient resource of patient with resource identifier {id} Returns most recent version of resource from the history.
PUT /Patient/{id} Stores a new version of Patient resource for patient with resource identifier {id} Stores new version of resource in the history, incrementing the version id.
DELETE /Patient/{id} Deletes patient with resource identifier {id} from the database History is also deleted and cannot be retrieved.
GET /Patient/{id}/_history Returns version history of patient with resource identifier {id} Returns bundle containing all versions of Patient resource for the patient.
GET /Patient/{id}/_history/{vid} Returns version with version id {vid} from history of patient with resource identifier {id} Returns an error if either patient or version not found.

As mentioned earlier, the method and endpoint taken together define the behavior that results from an API request. For example, GET /Patient can retrieve all of the patients in the FHIR database, while GET /Patient/{id} returns only the patient with the specified id. The endpoint is appended to the server to form the request URL, for example, https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/Patient

Expand a method in the Development Portal to see the parameters that can be sent with the API request, as well as the data that can be sent in the body of the request.

Parameters are used to modify the API request, for example, to narrow the focus of the request. If you look at the available parameters for GET /Patient, you will see that you can filter the returned results by gender, birth date, family name, and many other fields. Parameters are appended to the request URL in the query string.

If you have authorized yourself to use the Development Portal, you will see a Try It Out button to the right of the Parameters heading. You can click this button to test a method. To search for all female patients in the database, expand GET /Patient, enter female in the Gender field, and click Execute.

In the Responses section, you can see the cURL command that is equivalent to the API request you just made:

curl -X GET "https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/Patient?gender=female" 
-H  "accept: application/fhir+json" -H  "x-api-key: nnp4R6vkob7cvDmLfumE33gX7z4zlTgD29YIpybx"

Notice that the parameter you specified is appended to the request URL: https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/Patient?gender=female

Provided that no problems occur with the request, you should see that the server response includes the HTTP status code 200, meaning that the request was successful. In the response body, you will see a bundle of patient resources, one for each of the patients in the database who is female.

Conversely, when you send a request that stores data for a resource in the database, this data is usually contained in the body of the request. To add a new patient resource to the database, you send a POST /Patient request. If you expand this section in the Developer Portal, you can see that this request does not take any parameters, but it does require a request body, which contains the data to be stored for this resource. Select an example from the drop-down list to see the request body for a sample patient.

If you select a sample patient resource and use the Try It Out feature to send the post request, you should see the HTTP status code 201, meaning that the resource was created. This request returns no body, but it does return some headers. In particular, notice that the Location header contains a value that looks something like https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/Patient/8111/_history/1. This tells you that the patient was assigned an id of 8111 and that you stored version 1 of the resource in the history.

Now, you can retrieve this patient by executing GET /Patient/{id}, where id = 8111. If you make a PUT /Patient/8111 request and send a body containing a new version of the patient resource, it is stored as version 2 in the history.

Schemas

The Schemas section of the Developer Portal describes the data elements that can be contained in a resource of a given type. For example, a Patient resource can contain the birthDate and maritalStatus elements. Some elements, such as Address, can contain themselves contain elements. A patient’s Address can contain City and State, for example. The data type of each element is also given, such as string or boolean.

Access Logs Page

The Access Logs page provides valuable information on who is using your service and what FHIR requests they are making. For each request, the access log shows the fields listed below. For summary information, see the Metrics page.

Request Time

The time the request was made, in UTC.

Endpoint

The endpoint called in this request. This can be either the FHIR Endpoint or the FHIR Oauth2 Endpoint, as listed on the Overview page for your deployment.

Source IP

The source IP address from where the request was made.

HTTP Method

The HTTP method used for the request, for example, POST (create), GET (read), PUT (update), or DELETE (delete). A given request is sometimes preceded by an OPTIONS request, which asks the server if it is acceptable to send the request.

Request Path

The path of the request. This generally corresponds to the resource requested, for example, /Patient or /Account. A request sent using OAuth 2.0 will start with /oauth2, as in /oauth2/Patient or /outh2/Account.

Status

The HTTP status code of the request. A successful request results in a status in the range 200-299. For example, a successful GET request might return a status of 200 (OK), while a successful POST request might return a status of 201 (Created). A status in the range 400-499 indicates a client error. For example, a status of 403 (Forbidden) generally indicates that the client is not authorized to make the request. A status in the range 500-599 indicates a server error. For example, if the request is sent to an unknown request path, it might return a status of 502 (Bad Gateway).

The column in the access log is actually composed to two statuses, the Status (shown in bold) and Integration Status (shown in normal text). These 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 POST request might return a Status of 201 and an Integration Status of 200.

API Key

The API key used for the request, if applicable.

It can take a few minutes for a request to appear in the access log.

To sort the access log by any field, click the column header for that field.

To download the access log in JSON format, click DOWNLOAD LOGS. The JSON file contains some additional information about each request, such as the User Agent (information on the browser or other client used to make the request).

Note:

The listing on the Access Logs page and the contents of JSON log file are currently limited to a maximum number of 5,000 requests, and the requests must have been sent in the past 8 hours.

Data Management Page

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

The Data Management page of the Managed Services Portal contains several tabs to help you accomplish these and other tasks.

As an alternative to importing resources using the Data Management features of the Managed Services Portal, you can use the FHIR Accelerator Service API to import bundles.

View the FHIR Resource Count

To view the count of resources in the FHIR database:

  1. On the Data Management page for your deployment, click the Dashboard tab.

  2. In the FHIR Resources Count section, view the number of total resources and the number of patient, practitioner, and organization resources.

If you are in the process of importing a large number of bundles, you can watch the count of resources on this tab increase as they are imported. You may need to click REFRESH to update the display.

Upload FHIR Bundles

You have several options for uploading FHIR bundles to the FHIR Accelerator Service. You can upload them manually from your computer, upload bundles from a selection of pre-populated data sets, or upload bundles using SFTP.

Upload Bundles Manually

To upload your FHIR bundles manually using the Managed Services Portal:

  1. On the Data Management page for your deployment, click the Bundle Operations tab.

  2. In the Upload Bundles section, click the paperclip icon.

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

  4. Click UPLOAD.

When the upload completes, the number of uploaded bundles in the Import Bundles section at the top of the page is updated to indicate the number of bundles that are now available for import.

Upload Pre-Populated Data Sets

To upload FHIR bundles from a selection of pre-populated data sets:

  1. On the Data Management page for your deployment, click the Bundle Operations tab.

  2. In the Upload Bundles section, choose one of the listed scenarios from the table of pre-populated data sets.

    Click the down arrow at the end of a row in the scenarios table to view a description of that scenario and the types of resources the bundle contains. If you don’t see the scenario you are looking for, you can use the search feature or navigate through the pages of scenarios by clicking the arrows at the bottom of the table of pre-populated data sets.

  3. Click UPLOAD SCENARIO.

When the upload completes, the number of uploaded bundles in the Import Bundles section at the top of the page is updated to indicate the number of bundles that are now available for import.

Note:

The FHIR Accelerator Service comes pre-populated with a small amount of sample data for testing purposes. If you ever delete the data from your database and want to reload this sample data, upload the Reload Quickstart scenario.

Upload Bundles Using SFTP

You can upload FHIR bundles using either 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 page for your deployment, click the Connections tab.

  2. In the SFTP Server Status section, enable the SFTP Server, if it is not currently enabled.

    After enabling the SFTP Server, it takes a few minutes for the SFTP server to become ready for use. The default setting for the server is Disabled, to prevent the consumption of unused cloud resources and to close one possible port of entry to the FHIR Accelerator Service.

  3. In the Upload Data with SFTP section, click the DOWNLOAD KEY button.

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

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 SFTP 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 Managed Services 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 SFTP 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.

When the SFTP transfer completes, the number of uploaded bundles in the Import Bundles section at the top of the Bundle Operations tab is updated to indicate the number of bundles that are now available for import.

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 page, 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 page for your deployment, click the Bundle Operations tab.

  2. In the Import Bundles section:

    1. Optionally, click VALIDATE BUNDLES to validate your bundles before importing them.

      During the validation process, the screen is updated with a running count of valid and invalid bundles. You can stop the process by clicking CANCEL VALIDATION. After the validation process is complete, any errors are displayed on the page.

    2. If the bundles do not pass validation or you decide not to import them for some other reason, click CLEAR BUNDLES.

      The bundles are deleted and removed from the SFTP server (if applicable) and the count of bundles in the Import Bundles section is updated accordingly.

    3. Or, to proceed with the import, click IMPORT BUNDLES.

After starting the import process, you can look at the FHIR Resources Count section of the Dashboard tab to monitor the progress of the import. You will see the number of resources in the database increase as bundles are imported.

After the bundles are successfully imported, they are removed from the SFTP server (if applicable).

If you need to stop an import that is in process, click CANCEL IMPORT. You can resume the import process later by clicking IMPORT BUNDLES again. This is useful if you are running low on disk space. You can cancel the import process, expand your storage capacity on the Resources page, and then import the remaining bundles.

View the Import Logs

After you import your uploaded FHIR bundles, an entry appears on the Import Logs tab, providing a summary for that job. For each import job, you can see the Created and Updated date/time (in UTC); Job ID; Job Status (such as IN PROGRESS, COMPLETE, CANCELED, or FAILED); Duration (in seconds); and number of Total, Successful, and Failed Bundles. To sort the import logs table by any field, click the column header for that field.

To download the log for an import job, in JSON format, click the icon in the Download Import Log column for that job. The downloaded log file contains details about each imported bundle, including the file name, the physical size of the file, the number of resources in the bundle, and the time it took to be imported. If a bundle fails the import process, you can see the error message for that bundle.

Import Bundles Using the API

As an alternative to importing resources using the Data Management features of the Managed Services Portal, you can use the FHIR Accelerator Service API to import bundles of type transaction. To do this, send a POST / request to the root URL of your FHIR Accelerator Service endpoint, for example, https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/, with the bundle in the body of the request. A transaction is treated as a single unit. For example, if transaction bundle creates a patient resource and an observation resource and the creation of one of the resource fails, the entire transaction is rolled back.

After you import bundles using the API, the count of resources in the FHIR Resources Count section of the Dashboard tab is updated to reflect the new count. Since this method bypasses the standard Data Management features, the import is not shown on the Import Logs tab.

Note:

When you post a bundle to the root URL, it is processed as a series of create or update requests. When you post a bundle to the /Bundle endpoint, it is stored as is, without processing.

Delete All FHIR Resources

The Data Management page also allows you to delete all of the resources from your FHIR database. This can be useful if you are done testing a set of data and want to delete it and import a new set of data.

To delete all resources from your FHIR database:

  1. On the Data Management page for your deployment, click the Dashboard tab.

  2. In the Delete All FHIR Data section, click DELETE.

  3. In the Delete All FHIR Resources dialog box, type Permanently Delete, and then click DELETE.

Important:

Unless you have created a backup of your FHIR database, the deleted resources are not recoverable.

Resources Page

The Resources page allows you to change your deployment to a new deployment size or to monitor the amount of storage your deployment is using and expand the storage allocation if you need more space.

Change Deployment Size

The Deployment Size section of the Resources page lets you change the size of your deployment to a smaller or larger size, including the number of virtual CPUs and the amount of memory.

To change your deployment to a new size:

  1. Move the slider to the desired target deployment size.

    As you move the slider, the page shows you the specifications for the target deployment size and lets you compare it with the current specifications.

  2. Click RESIZE.

It can take a few moments for the resize to complete. Do not navigate away from the page until the process is complete. The other Managed Services Portal functions are not available while the resize is in progress.

Note:

Changing the size of your deployment will result in a change in cost to your subscription.

Monitor or Expand Storage Allocation

The Storage Allocation section of the Resources page lets you monitor or expand the amount of storage your deployment is using. At the top of this section, you can see the amount of storage currently used by your deployment, the amount of storage available, and the total amount of storage allocated. If you are actively ingesting a lot of new data, you can click REFRESH to update the display.

While you can use this display to monitor your storage visually, the tenant owner also receives an email when the deployment reaches 85% of the allocated capacity.

The Expand Storage subsection of the page allows you to request more storage when you need it, in increments of 10G.

To expand your storage size:

  1. Move the slider to the desired storage allocation after expansion.

  2. Click EXPAND.

It can take a few moments for the expansion to complete. You may need to click REFRESH to see the new storage allocation reflected on the page.

Due to AWS constraints, you can only expand your storage allocation once every six hours. After requesting an expansion, the EXPAND button is grayed out until the end of this six-hour time period.

Note:

Expanding the storage allocation of your deployment will result in an additional cost on your subscription. You cannot reduce your storage allocation, so do not expand your allocation until you are sure you need more storage.

Backup Page

The Backup page 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 page, click CREATE BACKUP.

The backup appears in the list of backups on the Backup page, along with its Backup ID and Creation Date (in UTC). The Status of the backup is shown as IN PROGRESS until the backup is complete, at which time the Status changes to SUCCESS. You may need to click REFRESH to update the display.

The CREATE BACKUP button is disabled while a backup is in progress.

Note:

Wait a few minutes before making a backup of the FHIR database on a new deployment to make sure any deployment creation processes have completed.

Restore a Backup

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

The page displays a Restoring indicator until the process is complete. The Dashboard tab on the Data Management page is updated to reflect the new number of resources in the FHIR database.

Delete a Backup

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

After the deletion is complete, the backup remains in the list, with a Status of DELETED. You may need to click REFRESH to update the display.

Important:

Deleted backups cannot be retrieved.

Help

If you have any questions on how to use the FHIR Accelerator Service, choose one of the following options:

  • Documentation—Written documentation for the FHIR Accelerator Service, the same information you are reading now.

  • Learning—The InterSystems Online Learning website, including videos and other resources to help you set up or use the FHIR Accelerator Service.

  • Community—The InterSystems Developer Community website, where you can read announcements from InterSystems and exchange information with InterSystems customers, employees, and other members of the developer community.

  • Support—Information on all of the InterSystems customer support options, including phone, email, and online.

You can access these same options by clicking Help at the bottom right of the Managed Services Portal. If you are reading this document on paper or in PDF form, and you do not see the information you are looking for, click Help to make sure you are reading the latest version of this guide.

Additional information is available on the Resource Center page of the Managed Services Portal.

If you would like to submit any feedback to help InterSystems improve the FHIR Accelerator Service, click your name at the top right of the Managed Services Portal, and then click Submit Feedback. While we cannot respond to all feedback we receive, we welcome your opinion and will take it into consideration when determining future directions and enhancements to the FHIR Accelerator Service.

Feedback