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
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 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.
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. Install OpenSSL from these binaries: OpenSSL for Windows Pre-compiled Win32/64 at https://wiki.openssl.org/index.php/Binaries. Make a directory where you want your .PEM and .PFX files to be created. Copy makecert.bat to that directory. Open a command window and navigate to the directory where you put makecert.bat. 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. 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. At the command prompt, enter the password, and then confirm the password, as seen in the image below.
Enter “dir” at the command prompt. The following files should appear:
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.
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:
Client ID - a unique EMR-assigned key that identifies the CAREWare PDI FHIR Datasource you plan to use at the EMR’s authentication server
Non-production Client ID
Any URL information (if it is provided at this time)
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.
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.
Login to the Central Administration domain of CAREWare.
Click, “Administrative Options.”
Click, “Provider User Manager.”
Click, “Manage Providers.”
Click on the provider domain that will be facilitating the FHIR interface to highlight the row, then click, “Manage.”
Click, “Manage Permissions.”
Type “FHIR” into the search bar and grant the two following permissions:
Setup FHIR App
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.
From the Central Administration domain:
Click, “Administrative Options.”
Click, “Provider User Manager.”
Click, “Manage Providers.”
Click on the provider domain that will be facilitating the FHIR interface to highlight the row, then click, “Manage.”
Click, “Manage Users.”
Click on the user that needs access to the FHIR interface to highlight the row, then click, “Manage.”
Click, “Manage Permissions.”
Type “FHIR” into the search bar and grant the two following permissions:
Setup FHIR App
Setup FHIR Resource
Repeat steps f-h for each user who needs access to the FHIR interface.
From the provider domain:
Click, “Administrative Options.”
Click, “Provider User Manager.”
Click, “Manage Users.”
Click on the user that needs access to the FHIR interface to highlight the row, then click, “Manage.”
Click, “Manage Permissions.”
Type “FHIR” into the search bar and grant the two following permissions:
Setup FHIR App
Setup FHIR Resource
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.
Login to the CAREWare provider domain that will facilitate the FHIR interface.
Click, “Administrative Options.”
Click, “Data Import and Export Features.”
Click, “Provider Data Import.”
Click, “Import Settings.”
Click, “Add.”
Select “FHIR” as the Source Type.
Enter “Default FHIR” as the Source Name field.
Click, “Next.”
Click, “FHIR Client Set Up.”
Click, “FHIR App Setup.”
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
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. PDI - Provider Data Import. RSR - Ryan White Services Report.