Skip to main content

InterSystems FHIR Transformation Services Reference Information

This section describes how to configure and manage InterSystems FHIR Transformation Services, organized by page. Use the links in the Deployments section of the main menu in the Cloud Services Portal to navigate from page to page.

For a high-level overview of setting up FHIR Transformation Services, see Introducing FHIR Transformation Services.

Note:

Some of the functionality described in this section may not be available to all users, depending on their role on the development team. For more information, see Tenants PageOpens in a new tab.

Overview Page

The Overview page for your deployment contains two sections, the Deployment Details section and the FTS Details section.

Deployment Details

In the Deployment Details section of the Overview page, 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

  • Service Level and Service Level Urgency

FTS Details

In the FTS Details section of the Overview page, you can view the REST API endpoints for the following transformations:

  • Autodetected message type to FHIR

  • HL7 v2 to FHIR

  • SDA3 to FHIR

For information on how to use these endpoints, see Transform Data using a REST API Endpoint.

Credentials Page

The Credentials page can be used to manage API keys that can be used to access to the FHIR Transformation Services API.

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.

Configurations Page

The Configurations page lets you configure the Amazon S3 interface to InterSystems FHIR Transformation Services. You can use this page to edit the configuration you specified when you deployed FHIR Transformation Services. Once your configuration has been set, you can use this page to help you set up a bucket access policy that enables FHIR Transformation Services to interact with your S3 bucket or buckets. You can also use this page to activate a trigger on your input S3 bucket. This notifies FHIR Transformation Services when messages have been placed into the S3 bucket so that the service can pick up the messages for processing. For more information, see Transform Data using an S3 Bucket.

Edit S3 Interface Configuration

When you first deployed FHIR Transformation Services, you set up an initial S3 interface configuration.

If you need to edit your existing S3 interface configuration:

  1. On the Configurations page for your deployment, make any needed changes to the fields in the Input Properties or Target Properties sections of the screen.

    These fields are the same as described in the Create a Deployment section of this document.

  2. Click Save.

  3. If you have changed either your input or target S3 buckets, set up a bucket access policy for each bucket.

  4. If you have changed your input bucket, activate a trigger on the bucket.

Set Up Bucket Access Policy

In order for FHIR Transformation Services to access your S3 bucket (or buckets), you need to set up an access policy in your AWS account for each bucket.

To set up a bucket access policy:

  1. On the Configurations page for your deployment, follow the instructions in the blue How to setup policy access box to set up permissions for FHIR Transformation Services to access your input S3 bucket.

  2. If you are using a target S3 bucket that is different from the input S3 bucket, you need to set up a bucket access policy on the target bucket, as well. In such cases, the blue How to setup policy access box will provide a separate policy for you to apply to the target bucket.

Note:

If you change either your input S3 bucket or target S3 bucket to another bucket, you will need to apply a bucket policy for the new bucket.

Activate Bucket Trigger

After you set up your initial S3 interface configuration or after you change to a new input S3 bucket, you need to activate a trigger on the input bucket to notify FHIR Transformation Services when messages have been placed into the S3 bucket so that the service can pick up the messages for processing.

To activate a trigger on your input S3 bucket, on the Configurations page for your deployment, click Activate Trigger at the bottom of the screen.

Errors Page

If you are transforming healthcare messages using Amazon S3 buckets, any errors detected during transformation are shown on the Errors page. (See View Errors.)

If an error is detected while processing a healthcare message, it is moved to the errors folder in the input S3 bucket. If the Error Behavior option is set to Ignore (see Configurations page), FHIR Transformation continues processing messages. If the option is set to Pause, processing of additional messages is paused until the error is resolved. (See Resolve Errors.)

View Errors

To view transformation errors, click Errors on the main menu for your deployment.

The displayed errors are divided into three sections:

  • Global Errors — Errors for which a valid facility ID/patient ID combination could not be identified. For example, one or both of these ID types might be missing or the message was malformed and could not be parsed.

  • Local Errors — Errors for which a valid facility ID/patient ID combination could be identified, but where other required information is missing or not valid.

  • Resolved Errors — Errors for which corrections have been determined and the messages have been resubmitted and transformed successfully.

Each error is listed with the date and time of the error, the S3 location where the original healthcare message was moved, and a description of the error. To filter the errors on this page, specify a start date (with an optional start time) and/or an end date (with an optional end time), and click Apply.

Resolve Errors

To use the Errors page as a work list to resolve errors:

  1. Find an error in the Global Errors or the Local Errors section of the page.

  2. Find the original healthcare message in the errors folder of your input S3 bucket, as indicated in the File column for that error.

  3. Identify and fix the error in the message.

  4. Resubmit the message by placing the corrected file in the input S3 bucket, in the folder matching the input bucket prefix. See the Configurations page, if you don’t know the input bucket prefix.

  5. If the corrected message is transformed successfully, on the Errors page, select the error, and click Resolve Errors. If you have corrected several messages, you can select them and resolve them all at once.

    The errors are moved to the Resolved Errors section of the page.

Metrics Page

The Metrics page lets you see various statistics for InterSystems FHIR Transformation Services, including:

  • Number of messages transformed

  • Transformation time

  • Messages categories

  • Facilities

Metadata Page

FHIR Transformation Services allows you create custom metadata to be added to each resource in the FHIR output when a transformation takes place. Each metadata tag is described as a key/value pair.

The following tags are currently supported:

  • meta-source

  • meta-xyz

  • vendor-source-id

Note:

In may take up to an hour for custom metadata to appear in the FHIR output of a transformation. Default values will appear in the output until your custom metadata takes effect.

Metadata is currently supported when transforming C-CDA messages only. Metadata support for HL7 v2 messages will be added in the future.

The Metadata page lists all of the tags you have created and also lets you:

Create a Key/Value Pair

To create a new key/value pair:

  1. On the Metadata page, click Create Metadata.

  2. In the Metadata dialog, type the Key and Value.

  3. Click Save.

After you create a tag, it shows up in the Metadata list.

Edit the Value of a Tag

To edit the value in an existing key/value pair:

  1. On the Metadata page, click the Edit icon in the Actions column for that key/value pair.

  2. In the Metadata dialog, type the new Value for the tag.

    It is not possible to edit the name of the key at this time. If you type the name of a key incorrectly, delete the key/value pair and then re-create it.

  3. Click Save.

After you edit the value of a tag, the new value shows up in the Metadata list.

Delete a Key/Value Pair

To delete a key/value pair:

  1. On the Metadata page, click the Delete icon in the Actions column for that key/value pair.

  2. In the Delete Metadata dialog box, type the name of the key you are deleting, and click Delete.

The key/value pair is removed from the Metadata list.

Metadata Example

This example shows how the metadata you create appears in the FHIR output for a C-CDA transformation.

If you create the following tags:

Key Value
meta-source MS
meta-xyz MXYZ
vendor-source-id VSI

Then the following JSON appears in each FHIR resource in the output:

   "meta": {
      "source": "MS",
      "tag": [
         {
            "code": "MXYZ-CCDA"
         },
         {
            "code": "VSI"
         },
         {
            "code": "cohortIdValue",
            "system": "urn:dav-cohort-id"
         }
      ]
   },

Common Cloud Services Portal Functionality

For information on common Cloud Services Portal functionality that is not specific to FHIR Transformation Services, see Cloud Services Portal Reference InformationOpens in a new tab. This document includes material describing the top-level pages in the main menu:

FeedbackOpens in a new tab