Set Up FHIR in Kizen

Audience: Admins, Developers, Solution Architects

Purpose: Explains how to configure the FHIR integration to use live FHIR data in Agentic Workflows

Overview

Caution: This setup reflects Kizen's default configuration. Your administrator may have customized your layout, so columns or navigation may appear differently. Trial accounts may have limited features.

To use FHIR® data in Agentic Workflows, you must first connect Kizen to your FHIR server.

Before You Begin

To set up the FHIR integration, ensure you have:

FHIR server access, with a FHIR R4-compliant API endpoint
An administrator account in Kizen

Set Up FHIR in Kizen

To set up FHIR in Kizen:

Configure your FHIR server to work with Kizen

To configure your FHIR server to work with Kizen:

Launch your FHIR developer portal.
Register a SMART Backend Services client application, and grant it the appropriate FHIR access scopes. Use system/*.read for read access and system/*.write for write access. Not all EHR systems support all access scopes.
Generate an RSA key pair. For signing, use RS384 (recommended) or RS256.
Upload the public key in JWKS format to the FHIR server.
Note the ID of your client application, your key ID, and the base URL of the FHIR server, and confirm your FHIR access scopes. You need this information for the connection credentials in Step 4 below.

Go to the App Marketplace

In Kizen, go to the global navigation, and select Platform > App Marketplace.

The App Marketplace menu item under the Platform group in the global navigation

Activate FHIR

In the App Marketplace, find the FHIR card, and select the slider to activate the integration.

The Update Integration Secret modal appears.

Note: If the Update Integration Secret modal doesn't automatically open when you turn on the slider, select Manage Secrets in the FHIR card to open the Integration Secrets Manager in Kizen, and add the FHIR secret from this interface. Don't attempt to add the secret by editing the configuration of the FHIR integration itself. Always use the Integration Secrets Manager for the FHIR integration.

Enter your FHIR connection credentials

In the Integration Secret field of the modal, enter your FHIR connection credentials as a JSON object. Structure the JSON object like this:

{
  "base_url": "https://ehr.example.com/FHIR/R4",
  "auth_method": "smart_backend",
  "client_id": "your_client_id",
  "kid": "your-key-id",
  "scopes": "system/*.read system/*.write",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

Store multiple environments as nested JSON objects, like this:

{
  "prod_hospital": {
    "base_url": "https://ehr.example.com/FHIR/R4",
    "auth_method": "smart_backend",
    "client_id": "your_client_id",
    "kid": "your-key-id",
    "scopes": "system/*.read system/*.write",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  },
  "staging_hospital": {
    "base_url": "https://ehr.example.com/FHIR/R4",
    "auth_method": "smart_backend",
    "client_id": "your_client_id",
    "kid": "your-key-id",
    "scopes": "system/*.read system/*.write",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  }
}

Note: The private key is an RSA key. Be sure to encode it in the secret in Privacy-Enhanced Mail (PEM) format.

For descriptions of the fields, see the following table:

Key

Type

Description

base_url

String

The base URL of your FHIR server.

auth_method

String

The authorization method. At this time, the integration uses only SMART Backend Services for authorization, so the value of this field is always smart_backend.

client_id

String

Your SMART client application ID.

kid

String

The key ID for the header of the JSON Web Token that the integration presents to the FHIR server. This ID must match the one registered for this key in the FHIR server's JSON Web Key Set.

scopes

String

A space-separated list of the necessary FHIR access scopes. For read access, use system/*.read. For write access, use system/*.write.

private_key

String

Your private key in PEM format.

Save the integration secret

Select Save.

Create Objects as needed

If you intend to create Kizen Records from FHIR resources, either one at a time or through batch import by way of a SmartConnector, you must first create Objects in Kizen and map the Custom Fields of these Objects to the corresponding fields of the FHIR resource.

Note: Creating Objects is necessary for the Create Kizen Record and Parse FHIR Resource actions in an Agentic Workflow. Skip this step for any other action.

For more information, see Synchronize Data Between FHIR and Kizen in an Agentic Workflow.

To create an Object in Kizen, choose Data > Custom Objects from the global navigation, and select New Object on the page of Objects that appears. To configure the new Object, fill out the multi-step form.

Note: The API name of the Object in Kizen must match the FHIR resource type, but in snake_case, not in camelCase, as it is in FHIR.

On the Customize Fields step, add Custom Fields to the Object to match the fields on the FHIR resource. Set the name of each new field to describe the FHIR field that it represents.

The Field Name entry field in the Field Settings step of the New Object form

In the description of the Custom Field, enter the FHIR mapping information.

The Description field in the Field Settings step of the New Object form

Note: You can include additional text in the description of the Custom Field alongside the mapping information.

Follow the general syntax of fhir_mapping:path, where path is the dot-separated sequence of path segments that leads to the corresponding field on the FHIR resource. For examples, see the following table:

Pattern

Example

Maps to

A direct field on a FHIR resource

fhir_mapping:gender

The gender field of the FHIR resource

The property of an array with a discriminator

fhir_mapping:name.official.family

The family property of the name field where use equals official

The property of an array without a discriminator

fhir_mapping:address.city

The city property of the first element of the address array

A direct FHIR extension

fhir_mapping:ext.us_core_race.omb_category

The ombCategory value in the us-core-race extension of the FHIR resource

An extension as an element in an array

fhir_mapping:address.home.ext.geolocation.latitude

The geolocation.latitude property of the address field where use equals home

Note: Always convert the kebab-case and camelCase of FHIR extensions and resource types to snake_case for use in Kizen.

The discriminator in the mapping syntax depends on the field of the FHIR resource:

FHIR field

Discriminator

Example values

name

use

official, usual, nickname

telecom

system

phone, email, fax

address

use

home, work, temp

identifier

type.coding[0].code

MR, SS, DL

The integration transforms the value of the field depending on its Kizen field type:

Field type

Value transformation

Text, Long Text, Email Address

To a string

Number (Whole), Number (Decimal), Price, Rating

To a floating decimal

Checkbox, Checkboxes, Yes/No Question

To a boolean value

Dropdown, Radio Buttons

To a string wrapped in a JSON object

Dynamic Tags

To a string wrapped in a JSON object when you create a Kizen Record, or to a comma-separated string when you parse a FHIR resource for import into Kizen

Phone Number

To a string normalized in E.164 format

Date, DateTime

No transformation

What's Next

You've set up the FHIR integration. Now you're ready to authenticate to your FHIR server. To learn how, continue to Authenticate to a FHIR Server in an Agentic Workflow.

HL7, FHIR, and the FHIR FLAME DESIGN are the registered trademarks of Health Level Seven International, and their use does not constitute endorsement by HL7.

PreviousFHIR - Beta

NextAuthenticate to a FHIR Server in an Agentic Workflow

Last updated 11 hours ago

Was this helpful?