Samantha API

The Samantha client uses plug-in style “connectors” to implement the needed functionality allowing a Samantha user to interact with a supported EHR.  NoteSwift provides connectors for various EHRs as part of the Samantha product and also provides an API allowing 3rd parties to build additional EHR connectors.  This document describes the details required for implementing a cloud-based connector for Samantha.

Note that throughout this document the EMR and EHR terms are often used interchangeably, even if this may not be entirely accurate.  This is done for the most part to be consistent with the underlying module and class names in the code which use the EHR terminology by default.

Note on extensibility:  this document describes the Samantha functionality as it exists for other EHR systems today with a particular focus on the functions supported for communicating with those EHRs.  It is expected that there may be additional areas where the user experience would be greatly enhanced by taking advantage of functionality that we haven’t seen in other EHR/EMR systems.  The architecture and project plan are flexible enough to allow for implementation of such features and we’re interested in having any such discussions with interested parties.   

Architecture Overview

Samantha is a client-server product where the client connects to the EHR through a standard connector interface.  The client software automatically selects the appropriate connector plug-in at runtime based on the current license installed for the client.  In some cases the locally-installed connector plug-in contains all of the logic to connect to the EHR API.  However, in most cases the locally-installed connector plug-in is a generic “cloud EHR interface client” which makes standard calls to a web service implementation that implements all of the connector calls for a given EHR.  The client makes an early call to the connector to tell it which EHR to connect to on the back end and there is a handshake step allowing for proper authentication, generation of instance tokens, etc.  All of the calls made from the client to the cloud connector are RESTful.

Functional Blocks

In the cloud architecture the EHR Interface is broken into logical functional areas:

  • Version Management – This section handles the initial handshake between client and server and provides version and other identifying information the client can display to the user to help easily identify potential issues with the connection (e.g. accidentally loading an incorrect user profile pointing to the wrong EHR version)
  • Session / Authentication – These functions allow for authentication, creation of tokens to be used for a session with the connector, and other session management.
  • Medication / Prescription Handling – Get/Set current and past medications, search for medications, and add or update prescribed meds.  If supported by the EHR the functions here can also manage warnings for dosages, drug interactions, etc.
  • Patient Info – Demographic information about a given patient plus routines to search/select a patient and get information about the patient
  • Provider Info – Information about available providers in the practice or overall organization
  • Appointments / Encounters – Information about appointments for a provider/location in a given date range plus any associated encounters.  Includes the ability to create new encounters and set the current active encounter (if needed for the given EHR).
  • HPI / Reason for Visit / Exam / ROS – The functions in this block group together the logic for getting current information, searching for options, and setting new values in each of these sections.  These are logically grouped due to the similarity of underlying structures in these sections in many EHRs.
  • Problems / Diagnoses – Get/Search/Set functionality for problems and diagnoses in the chart
  • Orders – Get/Search/Set for Orders
  • Allergies – Get/Search/Set for Allergies
  • History – Get/Search/Set for History (social history, family history, etc.)

Client Options

The bulk of Samantha’s technology has been implemented in shared modules that have been installed on local client machines and have also been installed on servers that support cloud-deployment of services.  This provides options for how the Samantha client can be deployed in different scenarios.  The options are described below.

Windows PC Client

This is the current standard configuration for Samantha and is the mode by which all Samantha clients are currently deployed for customers in the field.  The Samantha windows client is built on WPF, installed using a light-weight installer, and includes logic to update automatically (with the user’s acceptance) when new versions are published online. 

The Windows install option provides the easiest configuration for connecting with locally installed speech recognition packages, which is the primary reason why this is the choice for all current customers.  This option gives complete, integrated functionality with supported end-user speech recognition systems.

Mobile Client

The Samantha architecture lends itself to development of such a client without any rework of the overall system structure.

Cloud/Web Client

The system architecture allows for straightforward development of this type of client, e.g. for integration directly into a cloud-based EHR.  However, additional specification will be required to make sure the client is compatible with the EHR interface and that the experience is seamless between the two.

EHR API Requirements

At a high level, the most important functionality API requirements on the EHR side include:

  • Authentication – the ability for the user to login using the EHR credentials they already know (e.g. using OAuth, although that specific architecture is not a requirement)
  • Chart access –
    • Read – the application needs access to current information in the patient’s chart in order to provide summary information for the provider, to speed up the matching process, and to help make decisions about the correct choices to make for new items going into the note
    • Write – the application needs the ability to update, remove, and add new items to each of the supported sections of the note/chart
  • Search Capability – Samantha will refine possible matches for the input to a single search string for each item to be entered and then use the EHR search capability to find the best match or matches for that item.  The more information that is returned with the searches the better for getting the correct result (e.g. if the EHR returns SNOMED or ICD10 codes with search terms then this can be used to match with the information Samantha has already collected for the given item)
  • Medications / Orders Workflow – One of the areas where Samantha users tend to save a lot of time is in the process of adding and updating medications and other orders.  This process can be greatly enhanced for the user the more access is available to the corresponding workflows via the EHR API.  For example, if medication interaction warnings are available via the API then those can be displayed in real-time for the user as they are entering new medication information.  As another example, if the APIprovides access to retrieve information about what optional and required information needs to be entered for each type of order then Samantha can help the user to fill in that information up-front instead of needing to fill in more information later. 
Scroll to Top