Chapter 9. Connecting to FHIR

Fast Healthcare Interoperability Resources (FHIR) is a standard for exchanging healthcare data. In an integration, you can obtain one or more FHIR resources, create or update a resource, update one or more fields in a resource, or use a transaction to create multiple resources. To do this, add a FHIR connection to the middle of a flow or as a simple integration’s finish connection.

Fuse Online connections to FHIR:

  • Can communicate with FHIR servers that use basic or bearer token (OAuth) authentication.
  • Can operate on all FHIR resources that comply with FHIR DSTU3.
  • Cannot operate on extensions, which allow for storing custom data in a resource. If an extension is in data that is received from a FHIR server, the integration silently ignores it.

In an integration that connects to FHIR, in a data mapper step, you can map only one level of depth for a FHIR list field. In other words, if a FHIR list contains a list then you cannot map the fields in the nested list. To mitigate this limitation, Fuse Online converts some FHIR resource list fields to single-value fields, for example, an address that is in a list field might be displayed in the data mapper as a single field.

Details for connecting to FHIR are in the following topics:

9.1. Creating a connection to a FHIR server

In an integration, to operate on FHIR resources, create a connection to a FHIR server and then add that connection to the middle of a flow or as a simple integration’s finish connection.

A FHIR connection cannot be the start connection of a simple integration. However, you can start a simple integration with a timer that periodically triggers a FHIR connection.

Prerequisites

  • You must know the URL for the FHIR server that you want to connect to.
  • You must have authorization credentials for accessing the FHIR server. You should obtain these from the FHIR server administrator. Rarely, a FHIR server does not require authentication and you can create a connection without specifying credentials. For example, a public FHIR server or a FHIR server in a private network might not require authentication.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. Click Create Connection to display connectors.
  3. Click the FHIR connector and configure the connection as follows:

    1. In the FHIR version field, accept DSTU3, which is required.
    2. In the FHIR server URL field, enter the URL for the FHIR server that you want to access. While creating an integration, you might accept the default test server http://fhirtest.uhn.ca/baseDstu3.
    3. In the FHIR server username field, enter your username. This is required by FHIR servers that use basic authentication.
    4. In the FHIR server password field, enter your password, which is also required by FHIR servers that use basic authentication.
    5. In the FHIR server bearer token field, enter your token. This is required by FHIR servers that use OAuth authentication.
  4. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameters and try again.
  5. If validation is successful, click Next.
  6. In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter FHIR West.
  7. In the Description field, optionally enter any information that is helpful to know about this connection.
  8. Click Save to see that the connection you created is now available. If you entered the example name, you would see that FHIR West appears as a connection that you can choose to add to an integration.

9.2. Obtaining a resource from a FHIR server

In an integration, you can obtain one resource that is of the type that you specify. To do this, add a FHIR connection to the middle of a flow.

Prerequisites

  • You created a connection to the FHIR server that has the resource that you want to obtain.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection.
  2. Click the FHIR connection that can access the resource that you want to obtain.
  3. On the Choose an action page, select Read.
  4. Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to obtain.
  5. In the Contained Resource Types field, if the resource type that you want contains other resource types, select them. Use the Ctrl key if you need to select more than one.

    Identifying contained resource types lets the data mapper display the fields that are in the contained resources. If you do not specify a contained resource type then you cannot map from any fields that are in the contained resource. There is no harm in selecting a resource that is not actually contained.

  6. In the Resource Id field, enter the ID of the resource that you want. Or, leave this field blank if you plan to map it from an earlier step that is in the flow.
  7. In the Resource version field, optionally specify a version ID for the resource. Leave this field blank to obtain the most recent version of the resource or to map the version ID of the resource that you want to obtain from a previous step.
  8. Click Next to add this connection to the flow.

Result

The connection appears in the integration visualization where you added it. During execution, this connection returns one resource.

Next steps

To map a value to the Resource Id field or the Resource version field, add a data mapper step before this connection.

9.3. Querying a FHIR server for resources

In an integration, you can query a FHIR server to obtain instances of a particular FHIR resource that satisfy a query that you specify. For example, suppose you want to ensure that all patients who are 65 and older received a pneumonia vaccination. Specify a query that obtains the resources for patients who were born before 1955. To do this, add a FHIR connection to the middle of a flow.

Prerequisites

  • You created a connection to the FHIR server that has the resources that you want to obtain.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection.
  2. Click the FHIR connection that has the resources that you want to obtain.
  3. On the Choose an action page, select Search.
  4. Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to obtain.
  5. In the Query field, specify a FHIR query or leave this field blank to map the query from a previous step. For details about forming a FHIR query, see FHIR Release 3 Search.
  6. Click Next to add this connection to the flow.

Result

The connection appears in the integration visualization where you added it. During execution, this connection returns a list of resources that satisfy the query that you specified. Fuse Online treats this list as a collection.

Next steps

If you did not specify a query, then add a data mapper step before this connection and map the query to this connection. To operate on individual returned resources, rather than on the returned list collection, after this connection, add a split step to the flow.

9.4. Creating a resource on a FHIR server

In an integration, you can create and add a resource to a FHIR server. When you configure the connection’s Create action, you specify the type of the resource that you want to create. For example, you might want to add a new patient resource to a FHIR server. To create a resource, add a FHIR connection to the middle of a flow, or as a simple integration’s finish connection.

To populate the values in the new resource, add a data mapper step to the flow just before the FHIR connection that you are adding in this procedure. It is expected that the previous steps in the flow provide the data that you want the new resource to contain. Map fields in the previous steps to fields in the target resource that this FHIR connection is creating. The new resource contains only the fields that you map to.

When a connection performs the Create action to create a new resource on a FHIR server, the new resource has an automatically-generated FHIR resource ID. If you want to specify the resource ID for a new resource, instead of selecting the Create action choose the Update action for the connection to perform.

Prerequisites

  • You created a connection to the FHIR server that you want to add a resource to.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to add a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. Click the FHIR connection to the server that you want to add a resource to.
  3. On the Choose an action page, select Create.
  4. Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to create.
  5. In the Contained Resource Types field, if the resource type that you want to create contains other resource types, select them. Use the Ctrl key if you need to select more than one.

    Identifying contained resource types lets the data mapper display the fields that are in the contained resources. If you do not specify a contained resource type then you cannot map to or from any fields that are in the contained resource. There is no harm in selecting a resource that is not actually contained.

  6. Click Next to add this connection to the flow.

Result

The connection appears in the integration visualization where you added it. During execution, the connection creates a new resource on the FHIR server. The connection returns a MethodOutcome resource that includes an id.idPart field. This field contains the new resource’s resource ID, which you might want to map to a subsequent step in the flow.

Next steps

If this flow needs additional steps to obtain the data that you want the new resource to contain, add them before this FHIR connection. After those steps are in place, add a data mapper step to the flow just before the FHIR connection that creates a new resource. In the data mapper step, map to the fields in the resource to be created.

Caution

Without a data mapper step just before a FHIR connection that creates a new resource, the connection tries to create an empty resource. Depending on the FHIR server configuration, this might or might not work.

9.5. Updating all fields in a resource on a FHIR server

In an integration, you can update a resource that is on a FHIR server. To provide the updated values, add a data mapper step to the flow just before a FHIR connection that updates a resource. It is expected that previous steps in the flow provide the data that you want the updated resource to contain. Map fields in the previous steps to fields in the target resource that this FHIR connection updates.

Caution

The updated resource contains only the fields that you map to. In other words, in addition to mapping the fields whose values are changing, you must map the fields that you want to be in the resource and whose values are not changing. If you do not map a particular resource field then the connection deletes that field from the updated resource.

Be sure to map the resource ID from a previous step to the resource ID in this connection. This is the only resource field that the connection does not change. If the FHIR server does not already have a resource that has the resource ID for the resource to be updated, then the connection creates a new resource with that resource ID. This is the only way to add a new resource that has a resource ID that you choose.

To update or create a resource, add a FHIR connection to the middle of a flow, or as a simple integration’s finish connection.

Prerequisites

  • You created a connection to the FHIR server on which you want to update or create a resource.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to add a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. Click the FHIR connection that you want to use to update a resource on a FHIR server.
  3. On the Choose an action page, select Update.
  4. Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to update or create.
  5. In the Contained Resource Types field, if the resource type that you want to update or create contains other resource types, select them. Use the Ctrl key if you need to select more than one.

    Identifying contained resource types lets the data mapper display the fields that are in the contained resources. If you do not specify a contained resource type then you cannot map to or from any fields that are in the contained resource. There is no harm in selecting a resource that is not actually contained.

  6. Click Next to add this connection to the flow.
  7. If this flow needs additional steps to obtain the data that you want the updated resource to contain, add them before this FHIR connection.
  8. In the integration visualization, click the plus sign that is before the FHIR connection that updates a resource.
  9. Click Data Mapper.
  10. In the data mapper:

    1. Map a resource ID to the target resource ID. This is the only way to specify the resource ID for a new resource.
    2. Map to each resource field that you want the updated or new resource to contain. Be sure to map fields whose values are not changing, as well as fields whose values need to be updated.
    3. Click Done to add the data mapper step to the flow.

Result

The connection appears in the integration visualization where you added it. During execution, the connection updates or creates a resource on the FHIR server and returns a MethodOutcome resource that includes an id.idPart field. This field contains the updated/created resource’s ID, which you might want to map to a subsequent step in the flow.

9.6. Updating specified fields in a resource on a FHIR server

In an integration, you can update individual fields in a resource that is on a FHIR server. To do this, add a FHIR connection to the middle of a flow or as a simple integration’s finish connection.

Prerequisites

  • You created a connection to the FHIR server that has the resource that you want to update.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. Click the FHIR connection that you want to use to update the resource.
  3. On the Choose an action page, select Patch.
  4. Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of the resource whose fields you want to update.
  5. In the Number of Operations field, specify the number of fields that you want to update.
  6. Leave the Resource id field blank if you want to map the value from a previous step in the flow, which is typically what you want to do. Otherwise, specify the resource ID of the resource whose fields you want to update.

    Note: For the current release, the JSON patch option does not work. Instead, use the Data Mapper to update the fields as described in the following steps.

  7. Click Next to add this connection to the flow.
  8. Add a data mapper step:

    1. In the flow visualization, click the plus sign that is before the FHIR connection that you just added.
    2. Click Data Mapper.

      The Target panel displays a numbered folder for each field that you want to update. When you configured the Patch action, you specified how many fields to update. The data mapper displays this number of folders in the Target panel. For example, if you specified 3 as the number of fields to update, you would see three target folders with the labels 1, 2, and 3.

    3. For each field that you want to update, map to the fields in one target folder:

      1. In the Target panel, expand a folder to display three fields for op, path, and value.
      2. Map a source field, constant, or property to the target path field. The path identifies the resource field that you want to update. In a path value, a number indicates the index of a list field, and a slash leads to a child field. For example, map this path /name/1/given/1/value to update the value of the given name field.
      3. Accept the default update operation, which replaces the current value of the field, or map a source field, constant, or property to the op field to indicate how you want to update the field. For details about possible operations, see JSON patch operations.
      4. If you are updating a field to have a new value, then map a source field, constant, or property to the target value. This is the new value that you want the field to contain.
    4. If you did not specify a resource ID when you configured the Patch action, then map the resource ID to the target id field.
    5. Click Done to add the data mapper step to the flow.

Result

The connection appears in the integration visualization where you added it. During execution, the connection updates the specified resource field(s) and returns a MethodOutcome resource that includes an id.idPart field. This field contains the ID of the resource that was updated.

9.7. Creating resources of different types on a FHIR server

In an integration, you can create two or more resources on a FHIR server and each resource can be of a different type. For example, you can add a new patient resource and a new provider resource in one connection to a FHIR server. To do this, add a FHIR connection to the middle of a flow, or as a simple integration’s finish connection.

Prerequisites

  • You created a connection to the FHIR server that you want to add resources to.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. Click the FHIR connection that you want to use to create and add new resources to a FHIR server.
  3. On the Choose an action page, select Transaction.
  4. In the Included Resource Types field, select the resource types that this connection creates. Use the Ctrl key to select multiple resource types. The connection creates one resource of each type that you select.
  5. Click Next to add this connection to the flow.
  6. To populate fields in the new resources, add a data mapper step before this connection:

    1. In the flow visualization, click the plus sign that is before the connection that you just added.
    2. Click Data Mapper.
    3. In the data mapper, map source fields to the target resource fields. The new resources contain only the target fields that you map to.
    4. Click Next to add the data mapper step to the flow.

Result

The connection appears in the integration visualization where you added it. During execution, the connection adds all resources to the FHIR server or, if there is an error, the connection does not add any resources to the FHIR server. A successful action returns a transaction resource, which contains the resource ID for each new resource. You can map these resource IDs to subsequent steps in the flow.

9.8. Deleting a resource from a FHIR server

In an integration, you can delete a resource from a FHIR server. To do this, add a FHIR connection to the middle of a flow or as a simple integration’s finish connection.

Prerequisites

  • You created a connection to the FHIR server that has the resource that you want to delete.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to select a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. Click the FHIR connection that you want to use to delete the resource.
  3. On the Choose an action page, select Delete.
  4. Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to delete.
  5. In the Resource Id field, specify the resource ID of the resource that you want to delete or leave this field blank if you plan to map the resource ID from an earlier step in the integration.
  6. In the Resource version field, optionally specify a version ID for the resource. Leave this field blank to delete the most recent version of the resource or to map the version ID of the resource that you want to delete from a previous step.
  7. Click Next to add this connection to the flow. .

Result

The connection appears in the integration visualization where you added it. During execution, the connection deletes the specified resource on the FHIR server and returns a MethodOutcome resource that includes an id.idPart field. This field contains the resource ID for the deleted resource.

Next steps

To map a value to the Resource Id field or the Resource version field, add a data mapper step before this connection.