0.1.0 - ci-build

CAREWareFHIRDataDictionary - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

CARE Ware FHIR Overview

CAREWare FHIR API

User Guide

Published June 2025

​alt_text

Table of Contents

Purpose

This document contains the information needed to implement the CAREWare FHIR API at Ryan White organizations.

Introduction

FHIR stands for Fast Healthcare Interoperability Resources. It’s a set of rules and standards to transmit data from EHRs (electronic health records) to third-party applications, like CAREWare. Data is exchanged through an API (application programming interface).

Currently, even the smoothest of data imports in CAREWare can take a significant amount of time from making secure connections, to mapping data, and ultimately to ensuring data quality. The CAREWare FHIR API simplifies the import process by leveraging standardized codesets used in EHRs, and automatically identifying and mapping incoming RSR data. It allows users to regularly query RSR data from their EMR, resulting in increased report completeness and reduced duplicative data entry.

The diagram below illustrates, at a high level, how the CAREWare FHIR API imports data from an EHR.

This user guide will provide instructions on how to set up and configure the CAREWare FHIR API for Epic and Athena EHRs.

Set Up Process

This section contains technical instructions for IT Administrators to set up and configure the CAREWare FHIR API.

Approval

The first step in the process is obtaining approval from organizational leadership, IT Administrator, and EMR staff to set up the CAREWare FHIR API. The EHR team or IT Administrator will need to ensure the CAREWare FHIR app is available for use in your organization’s EHR. The image below is an example of the CAREWare RSR Connector app in Epic.

Generate the Public & Private Keys

After the CAREWare FHIR app is approved in your EHR, the IT Administrator will follow the instruction below to generate public & private RSA keys for connecting the CAREWare PDI FHIR Datasource with your organization’s EMR FHIR App.

  1. Install OpenSSL from these binaries: OpenSSL for Windows Pre-compiled Win32/64 at https://wiki.openssl.org/index.php/Binaries.
  2. Make a directory where you want your .PEM and .PFX files to be created. Copy makecert.bat to that directory.
  3. Open a command window and navigate to the directory where you put makecert.bat.
  4. Enter “openssl” at the command prompt to check if the openssl bin folder is in your environment variable PATH list. You should receive a list of available openssl commands. If that doesn’t occur, check your openssl installation.
  5. Enter “makecert” at the command prompt. Your command window should prompt you for your pfx password, which you will later need to set up your CAREWare PDI FHIR Data Source.
  6. At the command prompt, enter the password, and then confirm the password, as seen in the image below.

​alt_text

  1. Enter “dir” at the command prompt. The following files should appear:
    1. rsaCwFhirApp.pfx - This is a password-protected file which contains the randomly generated public key and the private key that match the data in the two .PEM files. This .PFX file, along with the password, is required to set up a PDI FHIR Datasource on the CAREWare side.
    2. publicKey509CwFhirApp.pem - This is what you use at your EHR’s FHIR App setup screen when it asks for the public key. During this setup of the FHIR App on the EHR side, save the following key information that CAREWare will need:
      1. Client ID - a unique EMR-assigned key that identifies the CAREWare PDI FHIR Datasource you plan to use at the EMR’s authentication server
      2. Non-production Client ID
      3. Any URL information (if it is provided at this time)
    3. privateKeyCwFhirApp.pem - This file is only created as a step in the process to make the pfx file. It should be safely stored with the other keys or deleted. If a bad actor obtains your private key, they can use FHIR to get medical information from your EMR under your name. You can always get your private key again using OpenSSL and your .PFX file as long as you have your password.
  2. These three .PEM and .PFX files only work with each other. If you need another PDI FHIR Datasource to connect to another EMR instance, you should use makecert.bat and make a fresh set of keys to use for that connection. If you do not have makecert.bat, then you can make your own batch file with the following text:
    • set certname=CwFhirApp
    • openssl genrsa -out privateKey%certname%.pem 2048
    • openssl req -new -x509 -key privateKey%certname%.pem -out publicKey509%certname%.pem -subj /CN=%certname% openssl pkcs12 -inkey privateKey%certname%.pem -in publicKey509%certname%.pem -export -out rsa%certname%.pfx

Grant CAREWare Permissions

The CAREWare Administrator will start by granting two necessary provider permissions.

  1. Login to the Central Administration domain of CAREWare.
  2. Click, “Administrative Options.”
  3. Click, “Provider User Manager.”
  4. Click, “Manage Providers.”
  5. Click on the provider domain that will be facilitating the FHIR interface to highlight the row, then click, “Manage.”
  6. Click, “Manage Permissions.”
  7. Type “FHIR” into the search bar and grant the two following permissions:
    1. Setup FHIR App
    2. Setup FHIR Resource

Next, the CAREWare Administrator will grant necessary user permissions. This can be completed in the Central Administration domain or in the provider domain that will be facilitating the FHIR interface. Separate instructions are provided below for each scenario.

  1. From the Central Administration domain:
    1. Click, “Administrative Options.”
    2. Click, “Provider User Manager.”
    3. Click, “Manage Providers.”
    4. Click on the provider domain that will be facilitating the FHIR interface to highlight the row, then click, “Manage.”
    5. Click, “Manage Users.”
    6. Click on the user that needs access to the FHIR interface to highlight the row, then click, “Manage.”
    7. Click, “Manage Permissions.”
    8. Type “FHIR” into the search bar and grant the two following permissions:
      1. Setup FHIR App
      2. Setup FHIR Resource
    9. Repeat steps f-h for each user who needs access to the FHIR interface.
  2. From the provider domain:
    1. Click, “Administrative Options.”
    2. Click, “Provider User Manager.”
    3. Click, “Manage Users.”
    4. Click on the user that needs access to the FHIR interface to highlight the row, then click, “Manage.”
    5. Click, “Manage Permissions.”
    6. Type “FHIR” into the search bar and grant the two following permissions:
      1. Setup FHIR App
      2. Setup FHIR Resource
    7. Repeat steps d-f for each user who needs access to the FHIR interface.

Configure FHIR Interface Settings

A user who has access to the FHIR interface in CAREWare will configure the FHIR interface settings.

  1. Login to the CAREWare provider domain that will facilitate the FHIR interface.
  2. Click, “Administrative Options.”
  3. Click, “Data Import and Export Features.”
  4. Click, “Provider Data Import.”
  5. Click, “Import Settings.”
  6. Click, “Add.”
  7. Select “FHIR” as the Source Type.
  8. Enter “Default FHIR” as the Source Name field.
  9. Click, “Next.”
  10. Click, “FHIR Client Set Up.”
  11. Click, “FHIR App Setup.”

​alt_text

  1. In the field, “PFX File Path,” enter the file path location where the PFX file is stored.
  2. Enter the PFX file password in the field, “PFX Password.”
  3. If using Epic, skip this step. If using Athena, enter the scopes that will be utilized in the, “Scopes in use,” field. Scopes are set through the developer console for Athena and should contain the following: 1. system/Medication.read 2. system/MedicationRequest.read 3. system/Condition.read 4. system/Observation.read 5. system/Patient.read
  4. Enter the EHR ID into the, “Client ID,” field. This will be provided by IT Admin or EHR Admin.
  5. Enter the URL for the oAUTH2 authentication where the token comes from in the, “oAUTH URL,” field. This will be provided by IT Admin or EHR Admin.
  6. Enter the R4 URL in the, “R4 URL,” field. This will end in, “FHIR/R4,” and will also be obtained from IT Admin or EHR Admin.
  7. Click, “Save.”
  8. Click, “FHIR CWFP Files.”
  9. Complete the following steps for each CWFP file to be included in the FHIR imports:
    1. Click, “Upload CWFP File.”
    2. Click, “Choose File,” and select the CWFP file to be uploaded.
    3. Click, “Upload CWFP File.” The file should now be displayed on the FHIR CWFP Files page.
  10. Click, “FHIR Resources.”
  11. Complete the following steps for each resource to be included in the FHIR imports:
    1. Click, “Add.”
    2. The, “Resource Name,” field is user defined. Enter a name for the resource here.
    3. Select the CWFP file that contains the resource in the, “CWFPFileName,” dropdown. This dropdown is populated with the files uploaded in step 20.
    4. Reference the resource in the Implementation Guide and enter the corresponding, “FHIR Query String.”
    5. In the, “Number of Days from Date Range,” field, enter the number of days back the resource should pull data from. Please note that this field is not applicable to all resources, only those that reference a date range.
    6. In the, “Query Param CSV File Dir,” field, enter the filepath to the CSV file containing the FHIR IDs that should be included in the imports. The CSV file is generated through a scheduled custom report. The filepath should be the folder where the report is exported to.
    7. The, “Purpose,” field is user defined. Enter a summary of the resource purpose here.
    8. Reference the resource in the Implementation Guide and enter the corresponding, “PDI CSV File Name.”
    9. To include the resource in FHIR imports, check the, “Activated,” box.
    10. Check the, “Used for Query Result” box if the resource is located in an Epic smartform. Reference the Other CWFP File column in the Data Dictionary to determine if the resource is located in an Epic smartform.

Understanding the Data Dictionary

The CAREWare FHIR API data dictionary defines each data element available in the dataset. There is a unique data dictionary for Epic and Athena EHRs.

The Athena data dictionary contains the following information for each data element:

  • Data Element Name - The name of the RSR data variable in CAREWare.
  • FHIR Resource Name - Resource name as defined by HL7 FHIR R4.
  • **FHIR Resource Element Name - **Name of the node in the JSON CWFP file.
  • FHIR Resource Example - Sample of the JSON output.
  • **FHIR Resource Path - **The API URL to obtain the JSON output.
  • **US Core Coding System - **The medical terminology standard set by US Core.
  • **Comments - **Additional information from jProg about the FHIR resource.
  • **CAREWare User Interface Element Location - **Page location of the data element in the CAREWare user interface.
  • PDI Table Name - The name of the CAREWare PDI template table where the data element can be found.
  • PDI Column Name - The name of the column in the CAREWare PDI template table that corresponds to the data element.
  • CWFP Source File - Name of the CWFP source file used for the FHIR resource.
  • **CWFP Reference Column - **Name of the CAREWare PDI column.
  • CWFP Comments - Additional information from jProg on the CWFP file.
  • **CWFP Code Exert - **Code from the CWFP file specific to the FHIR resource.
  • **Loop/Separate CWFP Name - **Location of the beginning of the loop in the CWFP code.
  • **CWFP Loop Code Exert - **Describes the looping mechanism for the resource.

Using the CAREWare FHIR Connection

Glossary

ADR - ADAP Data Report.

**API - **Application Programming Interface.

**Athena - **

**CAREWare - **A free software used by Ryan White programs to collect and report data. It produces the RSR and the ADR, and can be used to monitor and improve service utilization and client health outcomes. The software was developed, and is maintained, by jProg.

**CAREWare Administrator - **This staff member is responsible for the implementation and management of CAREWare at their organization.

EHR - Electronic Health Record.

Epic -

FHIR - Fast Healthcare Interoperability Resources.

FHIR Resource -

**IT Administrator - **Organizational leadership staff member with IT oversight.

**jProg - **The software development company that created, and maintains, CAREWare.

PDI - Provider Data Import.

RSR - Ryan White Services Report.