InterSystems FHIR Server Reference Information

View Deployment Details

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

• Deployment size

• Number of cores

• Amount of RAM

• Deployment ID

• Underlying InterSystems platform and version

• Cloud provider and region

• Service Status (for example, RUNNING or STOPPED)

• Creation and expiration dates

• High Availability Status

• Service Level and Service Level Urgency

In Deployment Details section, you can also start or stop the deployment. For more information, see Start or Stop a Deployment.

Start or Stop a Deployment

If you are not actively using your deployment, you can temporarily stop it to reduce charges to your account. While you will continue to be billed for your storage use, you will not be charged for virtual CPU use while your deployment is stopped. When a deployment is stopped, you cannot access any of the functionality of the deployment in the Cloud Services Portal, except for the Overview page. All other pages are grayed out on the main menu. In addition, any API requests to FHIR Server for the deployment will return a 502 status while the deployment is stopped.

When you are ready to resume use of your deployment, you can start it again.

You can see the current Service Status (usually RUNNING or STOPPED) in the Deployment Details section of the Overview page for the deployment or on the card for the deployment on the Deployments page.

To start a currently stopped deployment:

1. On the Overview page for your deployment, in the Deployment Details section, click Start Deployment

2. In the Start Deployment dialog box, type start, and then click Start.

   The Service Status changes to STARTING and then RUNNING, when the startup process is complete. This may take a few minutes.

To stop a currently running deployment:

1. On the Overview page for your deployment, in the Deployment Details section, click Stop Deployment

2. In the Stop Deployment dialog box, type stop, and then click Stop.

   The Service Status changes to STOPPING and then STOPPED, when the shutdown process is complete. This may take a few minutes.

View FHIR Details

In the FHIR Details section of the Overview page for your deployment, 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 FHIR Server, click the FHIR Request Samples with API Key button to obtain sample cURL commands you can use as templates for constructing API requests to send to FHIR Server 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.

If you are using OAuth 2.0 to control access to FHIR Server, click the FHIR Request Samples with OAuth2 button to obtain sample cURL commands you can use as templates for constructing API requests to send to FHIR Server 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.

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 and optional Description 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.

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 FHIR Server, type its Redirect URL and Logout URL.

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

9. 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 FHIR Server without context.

       • Select Patient Standalone Launch to connect an application to FHIR Server 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 FHIR Server.

• Generate an access token right from the Cloud 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 FHIR Server, type its Redirect URL and Logout URL.

7. For manual testing of FHIR Server 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.

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 the Delete icon in the Action column in the row for the API key.

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.

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 Select 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. On the Available Authorizations dialog box, in the Value field, 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 FHIR Server 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.

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.

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 resources in the database.

   The number of total resources and the number of resources of the main resource types are viewable in the top table. A more detailed breakdown of resources by type is given in the Extended Resource Counts table.

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 FHIR Server. You can upload them manually from your computer or upload bundles from a selection of pre-populated data sets.

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 Stop 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 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. You may need to click Refresh to update the display.

If you need to stop an import that is in process, click Stop 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 Cloud Services Portal, you can use FHIR Server API to import bundles of type transaction. To do this, send a POST / request to the root URL of your FHIR Server 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.

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.

Monitor or Expand Storage Allocation

The Storage tab of the Resources page lets you monitor or expand the amount of storage your deployment is using.

The Storage Allocation section of the page shows you 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 section of the page allows you to request more storage when you need it, in increments of 10GB.

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. Do not navigate away from the page until the process is complete. The other Cloud Services Portal functions are not available while the expansion is in progress.

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

Make a Backup

To make a backup of the FHIR database, on the Backup page, click Create Backup. It may take several minutes or more for the backup to complete, depending on the size of your database.

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.

The Create Backup button is disabled while a backup is in progress.

Restore a Backup

To restore a backup to the FHIR database, click the Restore Backup icon in the Actions column for that backup. It may take several minutes or more for the restore to complete, depending on the size of the backup.

The restore appears in the list of restores on the Backup page, along with its Restore ID and Start Date (in UTC). The Status of the restore is shown as IN PROGRESS until the restore is complete, at which time the Status changes to SUCCESS. 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 the Delete Backup icon in the Actions column for that backup. The Status changes to DELETING.

After the deletion is complete, the backup remains in the list, with a Status of DELETED.