[vc_row][vc_column][/vc_column][/vc_row][vc_row full_width=”stretch_row” css=”.vc_custom_1645127269544{margin-bottom: 30px !important;padding-top: 50px !important;padding-bottom: 50px !important;background-image: url(https://carefluence.com/wp-content/uploads/2018/04/Documentation.jpg?id=530) !important;}”][vc_column width=”3/4″][vc_column_text]
Carefluence OpenAPI Documentation
[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Carefluence OpenAPI Version 1.0
This document discusses Carefluence OpenAPI Version 1.0 and its methods to connect to the OpenAPI Server and query patient data from EHRs, in the context of meeting the Meaningful Use Stage 3 requirements.[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Terms and Conditions of Use
This section discusses the terms and conditions of using OpenAPI version 1.0.
Documentation of Carefluence OpenAPI portal and materials including Carefluence support of the FHIR® Specification (referred to as the “Materials”) have been made available to developers for development and testing. The Materials are provided to developers as-is with no other warranties expressed or implied. Developers may use the Materials with adherence to the below terms and conditions:
- Carefluence OpenAPI portal has the most up-to-date documentation. Developers may keep copies of the Materials; however, they may not be distributed. Developers wishing to share the Materials may do so via linking other developers to the Materials hosted on the Carefluence OpenAPI portal.
- Developers own developments using the Materials. Carefluence owns the Materials, as well as any improvements to or derivatives of the Materials, such as enhancements to the testing tools or documentation. A dynamic developer environment is encouraged. Any suggested improvements of the Materials may become part of the Materials without any obligation or notice to the submitter.
- Developers are responsible for the products developed and how the products connect to the community members’ software. Developers are also responsible for complying with all applicable laws, including not infringing on Carefluence’s or others’ intellectual property rights. Some interfaces listed on the Carefluence OpenAPI portal may require a customer to license additional functionality or build additional workflows, so developers are encouraged to work closely with Carefluence and mutual customers in order to avoid unfavorable results.
- Developers interested in advertising products using Carefluence OpenAPI, Carefluence’s name, or Carefluence’s logo, please contact info@carefluence.com to obtain permission.
Last Updated: Friday, May 13, 2016
[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
About Carefluence OpenAPI Server
This section briefly discusses the Carefluence OpenAPI Server and its components.
The Carefluence OpenAPI server adopted HL7 FHIR® in its core strategy to offer innovative solutions as the Internet of Interoperable Things™ services around any healthcare system or medical device.
The FHIR® Standard has brought a resource approach to the Carefluence OpenAPI server information model (ie., Patient, Condition, Procedure, or Immunization), which is more granular than any other standard and fast to learn, develop, and implement solutions.[/vc_column_text][vc_single_image image=”597″][vc_column_text]Carefluence OpenAPI Server: Carefluence OpenAPI server adopted HL7 FHIR® in its core strategy to offer innovative solutions as the Internet of Interoperable Things™ services around any healthcare system or medical device. The FHIR® Standard has brought a resource approach to the Carefluence OpenAPI server information model (ie., Patient, Condition, Procedure, or Immunization), which is more granular than any other standard and fast to learn, develop, and implement solutions.
- Authorization Service: Web-based SMART authorization and resource retrieval service developed on OAuth 2.0 specification.
- RESTful Resource API: Healthcare data (ie., Patient, Condition, Procedure, or Immunization) is securely hosted as resources on a web server. All of these resources can be searched and operations such as update, create or delete are implemented as specified by FHIR® DSTU2 Standard.
- FHIR® Transformer: Server side component that takes CCDA or HL7 V2 messages as input and convert them into FHIR® resources accessible via RESTful Resource API.
- Embeddable Viewer Plugin: A default embeddable patient data viewer is provided and can be customized using CSS and XSLT.
- HL7 Interface Engine Plugin: Add-on modules to use with Mirth Connect or InterSystems Caché as the HL7 interface engine.
- OpenAPI Database: Database agnostic storage for the Carefluence platform that is tested with MS SQL server and Caché. Based on the Carefluence implementation strategy, there is an option to choose Oracle, MySQL, or PostgreSQL.
- Authorization Database: MS SQL Server data store to manage OAuth tokens and client application registrations with their authorization statuses.
[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Carefluence OpenAPI Client Library and Configuration
This section briefly discusses FHIR®, RESTful APIs, library and other dependent libraries.
Carefluence OpenAPI is a RESTful API, therefore presenting predictable, resource-oriented URLs. OpenAPI supports CRUD operation paradigm and uses built-in HTTP capabilities to pass parameters. Every request to the OpenAPI server responds with standard HTTP response codes to indicate errors and returns data back in either JSON or XML.
The Carefluence team has published a client library for .NET developers and have plans to support other languages like Java and Objective-C. Developers may use our libraries, or favorite HTTP/REST libraries (ie., RESTSharp) available for the programming language, to make HTTP calls to the Carefluence OpenAPI server.
The Carefluence OpenAPI .NET client library can be accessed from Visual Studio directly. The Carefluence OpenAPI .NET client library has methods to connect to the OpenAPI Server and query patient data from EHRs, in the context of meeting the Meaningful Use Stage 3 requirements.
To install Carefluence OpenAPI .NET client library, run the following command in the Package Manager Console of Visual Studio
Install-Package Carefluence
Link to Carefluence OpenAPI .NET client library page on nuget.org https://www.nuget.org/packages/Carefluence/
Note: Installing Carefluence OpenAPI client library from Visual Studio shall download the following libraries:[/vc_column_text][vc_single_image image=”611″][vc_column_text]Carefluence.dll contains all the necessary methods to connect, search and access the patient’s common clinical dataset.
DotNetOpenAuth.dll contains all the necessary methods to securely connect to the Carefluence Authorization service to authenticate users and authorize users to access the OAUTH2 tokens.
HL7.Fhir.Core.dll contains all the necessary FHIR® resource models as C# objects and also methods to parse and serialize the objects as per the FHIR® DSTU2 0.5.0.5149 specifications. This library helps developers save a lot of time by parsing data as FHIR® resource models as opposed to parsing the response as raw xml or JSON data.
Log4net.dll contains all the necessary methods to log errors, information and exceptions for debugging purposes.
RESTSharp.dll contains all the necessary methods to consume RESTful APIs for GET, POST, DELETE and PUT methods and also handle the responses.[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Carefluence OpenAPI User Management
This section briefly discusses how Health IT developers can develop an app to connect to the OpenAPI server and how the user authentication and authorization process works.
The Carefluence OpenAPI portal offers functionality to create application users with their profile information, credentials such as usernames and passwords, and also assign roles as Patient/Client/Admin. Note: User Registration RESTful API is available for external applications to register users.[/vc_column_text][vc_single_image image=”615″ img_size=”medium”][vc_column_text]Carefluence OpenAPI server users are typically patients, family members of patients, service providers, social workers or IT administrators.
User Authentication – OAUTH2
Authenticate
Authenticates user with passed credentials and returns JSON data containing API consumer keys, user scope and allowed permissions.
- URL
/Authenticate
For example, if base URL is https://sap.modulemd.com/carefluence.ioit1/OAuth then the URL is https://sap.modulemd.com/carefluence.ioit1/OAuth/Authenticate - Method:
POST - URL Params
Required:
Content-Type=”application/x-www-form-urlencoded charset=utf-8″
grant_type=”client_credentials”
Optional: none - Data Params
{ UserId : “patient”, password : “passwd” } - Success Response:
Code: 200
Content: [{ “UserName”:null,
“Name”:”provider”,
“Id”:”APIKey”,
“ClientSecret”:”APISecret”,
“CallBack”:”RedirectURL”,
“appName”:”sample.app”,
“desc”:”Sample Application”,
“appType”:”Restful Web Application”,
“appUse”:”Accesses Patient data in Read only mode”,
“url”:null,
“status”:”0″,
“authorizationStatus”:”Granted”,
“createdDate”:”06/13/2016 09:22:47″,
“scope”:”user/*.read” }] - Error Response:
Code: 401 UNAUTHORIZED
Content: { error : “Log in” }
The Carefluence OpenAPI client library has a class called myAPI, using an instance of this class, the developer would call the Initialize method to get the RESTful API for authentication and the call returns the user’s API consumer key, consumer secret and scope with permissions allowed. Here is the snippet of the code.
[/vc_column_text][vc_single_image image=”619″ img_size=”large”][vc_column_text]
User Authorization – Roles, Scopes and Permissions: OAuth2
Once the user is authenticated with the Authenticate API, Authorization is granted as per the scope and permissions allowed. The following roles define some default OAUTH2 scopes:
Patient role
gives the user read-only access (by default) to a specific patient record only. Typically this user is either a patient or an authorized user (family member, friend, guardian) who is allowed to access the patient’s record.
- Scope: Patient/*.read-PatientID where PatientID is the internal ID of the Patient record in the Carefluence OpenAPI server and allowing the user to access a specific patient data.
Client role
gives the user read-only access (by default) to any patient record. Typically this user is either a care coordinator, provider or social worker.
- Scope: User/*.read allowing the user to read any patient data.
Admin role
gives the user read and write access (by default) to manage all patient records.
- Scope: User/*.read User/*.write allowing the user to read or write on any patient data.
The Carefluence OpenAPI portal allows administrators to edit the scope of a user and it supports adding multiple scopes. Once the scope is modified, there is a functionality to re-authorize the user with the new modified scopes.
Token
Returns Authenticated user’s OAUTH2 token. This token is used to add every request to the Carefluence OpenAPI server.
- URL
/Token
For example, if base URL is https://sap.modulemd.com/carefluence.ioit1/OAuth then the URL is https://sap.modulemd.com/carefluence.ioit1/OAuth/Token - Method:POST
- URL ParamsRequired:
Content-Type= “application/x-www-form-urlencoded charset=utf-8”
grant_type= “client_credentials”
ConsumeKey= “APIKeyReturnedbyAuthenticateAPI”
ConsumeSecret= “APISecretReturnedbyAuthenticateAPI”
Scope= “ScopeReturnedByAuthenticateAPI” - Optional: none
- Data Params
None - Success Response:
Code: 200
Content:
{
“access_token”:”UserTokenReturnedByAPI”,
“token_type”:”bearer”,
“expires_in”:1781706597,
“scope”:”user/*.read user/*.write”
} - Error Response:
Code: 402 UNAUTHORIZED
Content: {error: “Unauthorized: Access is denied due to invalid credentials.”}
The Carefluence OpenAPI client library has a class called myAPI, using an instance of this class, the developer would call the GetAccessToken method to get the access token as shown above.[/vc_column_text][vc_single_image image=”627″ img_size=”large”][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Carefluence OpenAPI Methods for Meaningful Use Stage 3 Requirements:
This section discusses how apps can access patients’ common clinical datasets from EHRs using the Carefluence OpenAPI platform.
At the heart of the Carefluence OpenAPI platform, HL7 FHIR® DSTU2 Standard is rooted and adopted completely to offer the Internet of Interoperable Things™ services. EHR companies can license the Carefluence OpenAPI platform and configure it to work seamlessly to meet Meaningful Use Stage 3 requirements as listed below:
- OpenAPI allows other health IT applications to make read-only data requests for patient health information that is part of the Common Clinical Data Set.
- API interface will utilize the requirements set forth in §170.315(d)(1) Access Control and Authorization and §170.315(d)(9) Trusted Connection to securitize external connections to verify requests originate from trusted and authorized sources, and provide for privatized responses.
- OpenAPI is responsible per §170.315(d) (10) Auditing Actions on Health Information to audit events associated with external API access.
- §170.315(g)(7), §170.315(g)(8) and §170.315(g)(9) – API interface would allow a request for “all” the patient data, or specific “by specific data category.” Available data via the API interface is limited by the data defined by the Common Clinical Data Set.
- Provides technical documentation of API that would include, at a minimum, API syntax, function names, required/optional parameters and their data types, return variables and types/structures, exceptions and exception handling methods and their return types.
[/vc_column_text][vc_column_text]Carefluence OpenAPI server maps FHIR resources to Common Clinical Datasets
| Common Clinical Dataset | FHIR Resource | Resource Reference Documentation |
|---|---|---|
| Patient Demographics including Race/Ethnicity | Patient | Refer to Patient resource on HL7.org |
| Information regarding the Visit | Encounter | Refer to Encounter resource on HL7.org |
| Problem List | Condition | Refer to Condition resource on HL7.org |
| Procedures Performed | Procedure | Refer to Procedure resource on HL7.org |
| Smoking Status | Observation | Refer to Observation resource on HL7.org |
| Vital Signs | Observation | Refer to Observation resource on HL7.org |
| Lab Results | Observation | Refer to Observation resource on HL7.org |
| Goals defined | Goal | Refer to Goal resource on HL7.org |
| Immunizations Information | Immunization | Refer to Immunization resource on HL7.org |
| Treatment Plan | Care Plan | Refer to CarePlan resource on HL7.org |
| Health Concerns | Encounter | Refer to Encounter resource on HL7.org |
| Medications Information | MedicationStatement | Refer to MedicationStatement resource on HL7.org |
| Allergies | AllergyIntolerance | Refer to AllergyIntolerance resource on HL7.org |
| Medical Devices used by Patient | Device | Refer to Device resource on HL7.org |
| Clinical Summary Document as C-CDA | Binary | Refer to Binary resource on HL7.org |
[/vc_column_text][vc_column_text]The Carefluence OpenAPI client library has a class called myAPI, using an instance of this class, the developer would be able perform operations to CREATE, READ, UPDATE, and DELETE resources as shown. Refer to the mapping table to selection the appropriate common clinical dataset.[/vc_column_text][vc_single_image image=”637″ img_size=”large”][vc_column_text]
Example 1: Search and Read the patient by MR number
[/vc_column_text][vc_single_image image=”638″ img_size=”large”][vc_column_text]In the above example, we are using the Carefluence.dll library to search the patient with the search parameter “identifier=MRNo” where MRNo is the number of the patient for whom you are searching. MyAPI class has SearchResource method which takes list of search parameters and the type of the resource for which you want to search. The response is returned as a Bundle Resource (refer to Bundle Resource on HL7.org) serialized as XML data.
The example used Hl7.Fhir.core.dll library to parse the xml data into a FHIR® Bundle Resource model available to use in C# code. We can loop through the bundle entry items and, in this case, it has one item as the result has only one patient. Bundle entry item is casted as Patient resource model to use further in C# code.[/vc_column_text][vc_column_text]
Example 2: Search Problem List related to a specific Patient
[/vc_column_text][vc_single_image image=”640″ img_size=”large”][vc_column_text]In example 2, we are using the Carefluence.dll library to search the condition with the search parameter “patient=PatientID” where PatientID is ID of the Patient resource searched. MyAPI class has SearchResource method which takes list of search parameters and the type of the resource for which you want to search. The response is returned as a Bundle Resource (refer to Bundle Resource on HL7.org) serialized as XML data. This example used Hl7.Fhir.core.dll library to parse the xml data into a FHIR® Bundle Resource model available to use in C# code. We can loop through the bundle entry items and each item could be type casted as Condition resource model to use further in C# code.
Note: In the Carefluence.dll library, we gave a utility class called MyOpenAPIUtility that has convenient methods to search by category all mapped Common Clinical datasets related to a Patient.[/vc_column_text][vc_column_text]
Example 3: Search Problem List diagnosed within a date range of Jan 1 2011 to December 31 2011 related to a specific Patient with MR number 113243335
[/vc_column_text][vc_single_image image=”643″ img_size=”large”][vc_column_text]In example 3, we are using the Carefluence.dll library to search the condition with the search parameter “patient=PatientID” and passed fromdate and todate as additional parameters. MyAPI class has SearchResource method which takes list of search parameters, date parameters, and the type of the resource for which you want to search. The return response is a problems diagnosed within the specified range for a Specific patient and the response is returned as a Bundle Resource (refer to Bundle Resourceon HL7.org) serialized as XML data. This example used Hl7.Fhir.core.dll library to parse the xml data into a FHIR® Bundle Resource model available to use in C# code. We can loop through the bundle entry items and each item could be type casted as Condition resource model to use further in C# code.[/vc_column_text][vc_column_text]
Example 4: Query for consolidated clinical summary as a CCDA document containing data within a certain date range for a specific Patient with MR number 113243335
[/vc_column_text][vc_single_image image=”645″ img_size=”large”][vc_column_text]In example 4, we are using the Carefluence.dll library to search the Binary resource with the search parameter “patient=PatientID” and passed fromdate and todate as additional parameters. MyAPI class has SearchResource method which takes list of search parameters, date parameters, and Binary resource for which you want to search. The return response is a list of CCDA documents generated for a specified date range for a specific patient, and the response is returned as a Bundle Resource (refer to Bundle Resource on HL7.org) serialized as XML data. This example used Hl7.Fhir.core.dll library to parse the xml data into a FHIR® Bundle Resource model available to use in C# code. We can loop through the bundle entry items and each item could be type casted as Binary Resource model to use further in C# code. This example actually downloads the CCDA documents to a directory.[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Reference Implementation of Internet of Interoperable Things™ Services
[/vc_column_text][vc_column_text]
This section discusses how FHIR® standards and the Carefluence OpenAPI platform helped in developing the Internet of Interoperable Things™ services. This implementation example includes a SMART EHR using OpenAPI and ‘SMART on FHIR®’ applications in connection with the Carefluence OpenAPI platform, working together to provide real-time evidence-based clinical decision support for patients.
The following diagram is a representation of the implementation of Carefluence and Internet of Interoperable Things™ services. This is a real-world implementation of accessing patient data from EHR and providing, in real time, evidence-based clinical decision support for that particular patient.
[/vc_column_text][vc_single_image image=”651″ img_size=”large” title=”Actors in the Reference Implementation of Internet of Interoperable Things™ Services”][vc_column_text]In the current implementation of evidence-based clinical decision support, Carefluence has the following actors. The Carefluence OpenAPI platform with HL7 FHIR® DSTU2 Standard was used to accomplish the complete use case.
- ModuleMD EHR was enhanced to add the following capabilities:
- Included Carefluence FHIR® server as a native FHIR® component and implemented limited resources to be searched or queried from any SMART on FHIR® client. This feature helped the ModuleMD® EHR to connect with the Carefluence OpenAPI platform and respond to read requests for Patient, Condition, Procedure, Practitioner and Appointment resources.
- From the clinical summary of a patient chart, a CCDA was sent to the Carefluence OpenAPI platform. A trigger automatically launched the FHIR® transformer component of the Carefluence OpenAPI platform. This resulted in the conversion of the segments of CCDA into an equivalent FHIR® resource. In both the cases, the patient data from the EHR was instantly made available for other connected SMART apps.
- ‘SMART on FHIR®’ Applications were developed to connect with the Carefluence OpenAPI platform to authorize and access the patient data from the EHR and retrieve the corresponding suggestions from the Rules Repository authored with another ‘SMART on FHIR®’ app called Carefluence Process Modeler.
- Carefluence Patient Portal App: Single patient record from EHR and suggestions corresponding to that patient
- Carefluence CDS App: Evidence-based clinical decision support for multiple patients and full search capability on all supported FHIR® resources
- Carefluence OpenAPI platform is an essential actor in the middle of the Internet of Interoperable Things™ services (for more details, refer to the components of platform – section 3).
[/vc_column_text][vc_zigzag][/vc_column][/vc_row][vc_row][vc_column][vc_empty_space][vc_column_text]
Summary
[/vc_column_text][vc_column_text]
This section discusses the value of using the Carefluence OpenAPI server and the benefits of implementing the FHIR® Standard to provide true interoperability on the Internet of Interoperable Things™ services
- The Carefluence OpenAPI platform adopted HL7 FHIR® Standard as its core interoperability strategy. Besides supporting backward compatibility with HL7 V2 and CCDA formats, everything will be normalized as appropriate FHIR® resource. This standard brought simplicity and flexibility to the Carefluence platform. The word Fast in FHIR® truly means fast; faster to learn, develop, and implement. Carefluence was able to successfully adopt the FHIR® Standard within just one year.
- The “SMART on FHIR®” application paradigm is followed while connecting with the Carefluence OpenAPI platform and, therefore, applications are substitutable and quick to integrate.
- The Carefluence OpenAPI server is aimed at helping EHRs to achieve standards-based OpenAPI capability.
[/vc_column_text][message_box text=”Copyright © 2016 Carefluence. All rights reserved. HL7, CDA, CCD, FHIR, and the FHIR `{`FLAME DESIGN`}` are the registered trademarks of Health Level Seven International. ONC CERTIFIED HIT® is a registered trademark of HHS” bar_color=”transparent”][vc_empty_space height=”64px”][/vc_column][/vc_row]