> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md).

# Set Up FHIR in Kizen

Learn how to configure the FHIR integration in Kizen to use live FHIR data in Agentic Workflows.

{% hint style="success" %}
**Audience:** Admins, Developers, Solution Architects

**Purpose:** Explains how to configure the FHIR integration to use live FHIR data in <code class="expression">space.vars.automations</code>
{% endhint %}

## Overview

{% hint style="warning" %}
**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.
{% endhint %}

To use FHIR® data in <code class="expression">space.vars.automations</code>, you must first connect <code class="expression">space.vars.Kizen\_company\_name</code> 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 <code class="expression">space.vars.Kizen\_company\_name</code>

***

## Set Up FHIR in Kizen

To set up FHIR in <code class="expression">space.vars.Kizen\_company\_name</code>:

{% stepper %}
{% step %}

#### Configure your FHIR server to work with Kizen

To configure your FHIR server to work with <code class="expression">space.vars.Kizen\_company\_name</code>:

1. Launch your FHIR developer portal.
2. 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.&#x20;
3. Generate an RSA key pair. For signing, use RS384 (recommended) or RS256.
4. Upload the public key in JWKS format to the FHIR server.
5. 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](#enter-your-fhir-connection-credentials) below.
   {% endstep %}

{% step %}

#### Go to the App Marketplace

In <code class="expression">space.vars.Kizen\_company\_name</code>, go to the global navigation, and select **Platform** > **App Marketplace**.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F84HmbtmrINSDYZqyn5km%2Fglobal_platformappmarketplace.png?alt=media&amp;token=9a582466-b2ae-4f8b-8d50-c0958e5f9d28" alt="The App Marketplace menu item under the Platform group in the global navigation" width="375"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Activate FHIR

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

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F3j035RwDnjZamLCCxA8J%2Ffhir_turnon_fhirbeta.png?alt=media&amp;token=678844f6-c752-4f8c-9827-6bb5e191ba77" alt="The FHIR card in the App Marketplace" width="375"><figcaption></figcaption></figure></div>

The Update Integration Secret modal appears.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FzuPVwhDHPpyapouTOEGK%2Ffhir_updateintegrationsecret.png?alt=media&amp;token=ba6037bc-33e3-49ea-920b-091cfc3fb641" alt="The Update Integration Secret modal" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**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 <code class="expression">space.vars.Kizen\_company\_name</code>, 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.
{% endhint %}
{% endstep %}

{% step %}

#### 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:

```json
{
  "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:

```json
{
  "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"
  }
}
```

{% hint style="info" %}
**Note:** The private key is an RSA key. Be sure to encode it in the secret in Privacy-Enhanced Mail (PEM) format.
{% endhint %}

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` | <p>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.<br></p> |
| `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.                                                                                                                                                                        |

{% endstep %}

{% step %}

#### Save the integration secret

Select **Save**.
{% endstep %}

{% step %}

#### Create Objects as needed

If you intend to create <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entities</code> from FHIR resources, either one at a time or through batch import by way of a <code class="expression">space.vars.smartconnector</code>, you must first create <code class="expression">space.vars.objects</code> in <code class="expression">space.vars.Kizen\_company\_name</code> and map the <code class="expression">space.vars.fields</code> of these <code class="expression">space.vars.objects</code> to the corresponding fields of the FHIR resource.

{% hint style="info" %}
**Note:** Creating <code class="expression">space.vars.objects</code> is necessary for the Create <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entity</code> and Parse FHIR Resource actions in an <code class="expression">space.vars.automation</code>. Skip this step for any other action.

For more information, see [Synchronize Data Between FHIR and Kizen in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/synchronize-data-between-fhir-and-kizen-in-an-agentic-workflow.md).
{% endhint %}

To create an <code class="expression">space.vars.object</code> in <code class="expression">space.vars.Kizen\_company\_name</code>, choose **Data** > **Custom Objects** from the global navigation, and select **New Object** on the page of <code class="expression">space.vars.objects</code> that appears. To configure the new <code class="expression">space.vars.object</code>, fill out the multi-step form.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FM0w1yCGgqiXjYzy4c4tp%2Ffhir_newobject.png?alt=media&amp;token=4acf5ad2-b1da-4863-8393-3f5df8ebc1e6" alt="The first page of the New Object form" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**Note:** The API name of the <code class="expression">space.vars.object</code> in <code class="expression">space.vars.Kizen\_company\_name</code> must match the FHIR resource type, but in snake\_case, not in camelCase, as it is in FHIR.
{% endhint %}

On the Customize Fields step, add <code class="expression">space.vars.fields</code> to the <code class="expression">space.vars.object</code> to match the fields on the FHIR resource. Set the name of each new field to describe the FHIR field that it represents.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Fdle3mxK3y7wQwqwsa82S%2Ffhir_addnewfield.png?alt=media&amp;token=222ef0c8-28f1-4f93-808a-27a18e093477" alt="The Field Name entry field in the Field Settings step of the New Object form" width="563"><figcaption></figcaption></figure></div>

In the description of the <code class="expression">space.vars.field</code>, enter the FHIR mapping information.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FG9HY6Q5MXnxgfuukF9tW%2Ffhir_addnewfield_description.png?alt=media&amp;token=728a34eb-0262-49f1-b5bc-5a399e045485" alt="The Description field in the Field Settings step of the New Object form" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**Note:** You can include additional text in the description of the <code class="expression">space.vars.field</code> alongside the mapping information.
{% endhint %}

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` |

{% hint style="info" %}
**Note:** Always convert the kebab-case and camelCase of FHIR extensions and resource types to snake\_case for use in <code class="expression">space.vars.Kizen\_company\_name</code>.
{% endhint %}

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 <code class="expression">space.vars.Kizen\_company\_name</code> field type:

<table data-search="false"><thead><tr><th>Field type</th><th>Value transformation</th></tr></thead><tbody><tr><td><code>Text</code>, <code>Long Text</code>, <code>Email Address</code></td><td>To a string</td></tr><tr><td><code>Number (Whole)</code>, <code>Number (Decimal)</code>, <code>Price</code>, <code>Rating</code></td><td>To a floating decimal</td></tr><tr><td><code>Checkbox</code>, <code>Checkboxes</code>, <code>Yes/No Question</code></td><td>To a boolean value</td></tr><tr><td><code>Dropdown</code>, <code>Radio Buttons</code></td><td>To a string wrapped in a JSON object</td></tr><tr><td><code>Dynamic Tags</code></td><td>To a string wrapped in a JSON object when you create a <code class="expression">space.vars.Kizen_company_name</code> <code class="expression">space.vars.entity</code>, or to a comma-separated string when you parse a FHIR resource for import into <code class="expression">space.vars.Kizen_company_name</code></td></tr><tr><td><code>Phone Number</code></td><td>To a string normalized in E.164 format</td></tr><tr><td><code>Date</code>, <code>DateTime</code></td><td>No transformation</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

***

## 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](/docs/integrations-and-plugins/integrations/fhir-beta/authenticate-to-a-fhir-server-in-an-agentic-workflow.md).

<details>

<summary><strong>Related Topics</strong></summary>

* [FHIR - Beta](/docs/integrations-and-plugins/integrations/fhir-beta.md)
* [Authenticate to a FHIR Server in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/authenticate-to-a-fhir-server-in-an-agentic-workflow.md)
* [Read and Write FHIR Data in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/read-and-write-fhir-data-in-an-agentic-workflow.md)
* [Synchronize Data Between FHIR and Kizen in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/synchronize-data-between-fhir-and-kizen-in-an-agentic-workflow.md)
* [Troubleshoot FHIR](/docs/integrations-and-plugins/integrations/fhir-beta/troubleshoot-fhir.md)

</details>

***

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.