V1.x Documentation

https://www.modernintegration.com/

Overview

linkHIE was designed from the ground up to bring an HIE directly into your EMR. Our product was specifically designed with Mirth Results as the HIE, however, it can be customized to work with any HIE that supports web API calls and Single Sign-On.

Features

Web Views

Web pages are designed to be used as either stand alone or embedded in web enabled applications.

Web views can be embedded in numerous ways, however, it is recommended to use an iframe HTML element.

http://www.w3schools.com/tags/tag_iframe.asp

Examples of embedding will be shown later in this document.

HIE Integration

linkHIE can communicate securely with HIE software (using web services) to extract data for displayed in the native EMR Application.

Embed view integrated with Cerner MPages

Features

Single Sign-On

Our software interacts natively with Mirth Results Single Sign-On. This is achieved by a behind-the-scene process of communicating with HIE web services to accumulate the necessary information to launch directly into patient context (if applicable), and produce a trusted SAML Response transaction for the Single Sign-On consumer.

Our Single Sign-On process supports single click and LDAP authentication, described in more detail later in this document.

Server Installation

The web site was built in ASP.Net and requires a Windows Server operating system with an IIS web server and Microsoft SQL Server. Multiple instances can be installed on the same server at once. This number of instances is only limited by the power of the server.

Operating System Configuration

Windows Server 2008 is the minimum supported version of Windows Server. Testing has performed best with Windows Server 2012 R2.

After operating system installation is complete, launch the server configuration and click Add Role. Select Web Server (IIS) with all desired configurations including: Application Development: .Net Extensibility, ASP.Net 4.x.

Next, add role Application Server with .Net Framework 4.x and Web Server (IIS) Support selected.

Server Minimum Requirements

1 GHz Processor, 4 GB Ram, 100 GB Hard disk space

Server Recommended Requirements

2+ GHz Processor, 16+ GB Ram, 1+ TB Hard disk space

Required Software

Microsoft Windows Server 2008+, IIS Application Server, SSL Certificate issued by a trusted CA, Microsoft SQL Server 2008+

Note: Smaller implementations may be able to use SQL Server Express Editions, however this is not officially recommended due to database size limitations.

Software Installation

Our server code is intended to be simple to implement. The package just needs to be unpacked and IIS configurations are required to make the website available to users.

Unpack Software to Desired Location

Create a directory on the file system location to run the software.

Recommended location: C:\inetpub\wwwroot\<FOLDER>

If multiple instances are running on one server, make sure to uniquely name the folders to be easily recognizable.

Example: Running both Test and Production on a single server, name the two folders as:C:\inetpub\wwwroot\linkHIE-TESTC:\inetpub\wwwroot\linkHIE-PROD

Unpack the compressed file containing the application into the directory created.

Configure Application’s Web.Config

IIS Web Applications can be configured with a file called web.config. This file is located in the root folder of the web application.

Example: C:\inetpub\wwwroot\linkHIE-TEST\web.config

In the <appSettings> section there are required fields to be set for your unique instance of the application.

• DBConnectionString• Defines the connection string to Microsoft SQL Server. Exclude the database name in this string. Database user must have access to create and alter tables.• Example

• Server=localhost;User=dbuser;Password=dbuser;• DBName

• Database to use for this specific instance of linkHIE. It is recommended to have the same name for the database and the folder containing the web application.• If the database does not exist, then linkHIE will automatically create it with default parameters.• Example

• linkHIE-TEST

Configure Application’s Web.Config (Continued)

• Environment• Defines the environment the application is running under. Acceptable values are: TEST, PROD.• Example

• TEST• InstanceID

• This value is assigned by Modern Integration. It is used to uniquely identify the instance by a GUID (Globally Unique Identifier).• Example

• 4ddb91e4-e070-426c-bdbe-4b60193ce60e• LinkHIEHostname

• Sets the linkHIE hostname• This value is assigned by Modern Integration

• AccountID• A value assigned by Modern Integration that is used to login to linkHIE.• This (combined with Passcode) is case sensitive, and each account will have one account ID.

• Passcode• This value is case sensitive, and each account will have one passcode.

IIS Configuration

To put the site online a website must be created in IIS. If multiple instances are running on the same server it is required that each instance runs on a different port.

Create Website

In the IIS Manager, right click on the server and select Add Website.

Create Website (Continued)

Configure the website that best fits your needs. Here is a diagram showing a recommended configuration:

Site nameUse the same name as the directory that contains the web application.Physical PathThe directory that contains the web application.BindingHTTPS only, do not bind to a non secure port. Select the port number you wish to communicate on for this instance.SSL certificateSelect an installed certificate to use for the secured connection.

Configure Application Pool

IIS should create a new Application Pool with the same name as the website that was just created.

Configure Application Pool (Continued)

Right click on the Application Pool and select Advanced Settings.

Configure the settings that best fits the environment.

linkHIE requires a few configuration options to be set:

General: .Net CLR Version: v4.0General: Managed Pipeline Mode: IntegratedProcess: Model: Identity: NetworkService

At this point the application should be operational, however, it is still not useable yet.

Software Configuration

linkHIE is easily configurable by launching the Admin view in the specific instance that needs to be managed.

Example:https://hostname:8443/Admin.aspx

Login using your linkHIE account credentials. If this information is now known, contact Modern Integration support at support@modernintegration.com.

The configuration portal will be different depending on the version of linkHIE and what HIE it is interacting with.

When using the Admin portal it is required to run on a computer that has access to the instance of linkHIE that is being configured. This is necessary to sync the local instance with the configurations that are being modified on the Admin portal.

After the account is configured, linkHIE should be ready to go!

Web Views

linkHIE encapsulates multiple web views that are used for integrating with EMR & HIE software. Views will be different depending on the version of linkHIE that is running and what HIE it is designed to integrate with.

Web views are ASP.Net scripts that could be customized if necessary. It is recommended to use the views in tact due to overwriting of custom enhancements during upgrades.

/Admin.aspx Web View

Used to configure your linkHIE instance. Provides hooks into both linkHIE’scustomer portal and local instances. Changes made on this website will sync automatically if the user is using a computer that has access to the linkHIE instance.

/Embed.aspx Web View

Embeddable web view for the HIE. This component is different depending on the version of linkHIE. It can be used as a stand alone web page, or embedded in an EMR using simple HTML & JavaScript.

linkHIE CRISP Embed Example

Web Views (Continued)

/Login.aspx Web View

Login form to authenticate with local iDP. This form is capable of integrating with a variety of user management systems. Out-of-the-box this view integrates with LDAP.

/Logout.aspx Web View

Web page that destroys a user session, if one exists.

/Reload.aspx Web View

Forces the linkHIE instance to synchronize configuration.

/SSO.aspx Web View

View that performs single sign-on, and other automation tasks. User is updated at each phase of SSO, and is rejected if access isn’t allowed. This view can prevent users from accessing HIE’s if a training requirement is not completed, or provide instructions for how to gain access.

CRISP HIE

CRISP HIE

Chesapeake Regional Information System for our Patients, or CRISP, is a regional health information exchange (HIE) serving Maryland and the District of Columbia.

linkHIE CRISP is a specially deigned version of the product that works seamlessly with this HIE.

When using the Admin configuration page (Admin.aspx) your web browser is commutating directly with linkhie.com for storage of configuration information. When sections are saved, your local browser will send a request to the local instance to synchronize configuration.

Basic configuration allows administrators to manage the basics of their linkHIECRISP account.

Access to CRISP can be shutoff at a global scope as determined by administrators.

CRISP requires a trusted X.509 certificate to be used for digital signatures. In order to communicate with CRISP and access their Single Sign-on feature, either upload your own certificate in PKCS12 format or Modern Integration can generate one for you. The public certificate must be sent to CRISP to establish the application trust.

CRISP HIE Configuration

CRISP will provide your account a set of credentials that are necessary to access certain portions of their integration.

If you wish to notify your users that are accessing linkHIE’s embedded component, a notification text can be configured.

Select text color, background color, and whatever text to display. If no text is specified then no notifications will show in the embedded component.

Each [ENTER] key will result in spacing in the scrolling text.

CRISP HIE Configuration (Continued)

If a CRISP facility identifier is configured then it will be assumed with each patient search request. This is not required, however, it drastically improves response time when searching for patients. This value can be overridden if necessary by a parameter (explained later).

Your SAML Issuer is required to confirm the identity of your X.509 certificate. This value is stored in the format of a URL.

Configure linkHIE’s iDP to use LDAP by specifying the local domain controller, SSL option, and default domain. The ‘TEST LDAP’ button allows admins to test their configuration changes before saving.

Your Private Token is a value that is used for a simple application trust in order to implement Single Click SSO.

The method of authentication to select is based on the needs and demands of each organization.

CRISP HIE Configuration (Continued)

For auditing, it is very useful to know where SSO requests are coming from. Define your different clinical applications with linkHIE CRISP Integration, receive a unique identifier, and pass this along with SSO requests (explained later).

Username Translation is useful if the clinical application or a user authenticates to the iDP with a different user ID than their user ID in CRISP.

Your administrators will also have access to a simple audit view. This describes different CRISP SSO requests and the details of the event.

Additional data is available in your local database.

linkHIE CRISP Overview

Integrating ApplicationSoftware that is integratingwith linkHIE CRISP

Embeddable Web ViewComponent that integrates directly in web enabledapplications. Brings CRISP data directly intousers workflow screens and provides a method of SSO

Identity ProviderIdentify users on your local domain. Supports LDAP & Single Click options

Bridge IntegrationAutomated tasks that perform a seamless SSO Integration with CRISP

Single Sign-OnAt the conclusion of the process, the patient is launched in CRISP HIE

linkHIE Embedded View

Search for a patient in CRISPSave custom user configurations

Initiate SSOEmbed this view in your EMR Application. Patient and user context can be passed to the component form the data available in the embedding application.

Patient and user context is not required, however, this information will allow users to get the most value from the embedding.

Data from CRISP is presented to users that have the proper access.

At launch, PDMP data is available, and new tabs containing additional data will be forthcoming.

Example:https://hostname:8443/Embed.aspx?param1=value1&param2=value2

Configuration parameters can be used to customize the experience of your linkHIEinstance. For example, you can input user and patient context in order to maximize the value of the embeddable component. All web views accept the same set of parameters.

Parameter Name Description

user Application User ID.

app Application unique ID.Configured in Admin portal.

mrn Patient’s local MRN.

mrn_trim_start Character to trim from the start of a patient MRN.Useful if MRN in local system is stored as a string and has leading characters, and stored in CRISP as a number, with no leading characters.

subject_key CRISP patient identifier.If the embedding application has the CRISP patient ID then it can be passed along to linkHIE. Using this value drastically increases patient searching response times.

firstname Patient first name

lastname Patient last name

gender Patient gender

dob Patient date of birth

facility CRISP facility code

single_click_sso True or False value to activate single click SSO. False by default.If this value is set to TRUE then the public_token parameter must be configured.

public_token Public SSO token.Calculated using our public token algorithm. Explained in more detail later.

token_ts Public SSO token generation date timeParsable date time string that represents the instant the public token was calculated.

sso_launch_frame Embed view can launch SSO session in a different frame on the same web page.This parameter specifies the name of the frame to launch in.

sso_launch_target Embed view can launch SSO session in a different target.blank, parent, self, etc

sso_embed True or False value which dictates which CRISP view type to display. Set to True of space is limited in embedding application

custom Any custom data to send along with the SSO request.This data is just logged in your audit.

Parameters

Passing parameters from embedded application to linkHIE components is simple, using existing standards.

V 1.x supports Query String or URL Encoded Post or a combination of both.

Query String Example:https://hostname:8443/Embed.aspx?user=appuser&mrn=11122

XHTML Form Example:<form method="POST" action="https://hostname:8443/Embed.aspx">

<input type="hidden" name="user" value="appuser" /><input type="hidden" name="mrn" value="11122" />

</form>

Parameters (Continued)

EmbeddingDepending on your EMR the embedding process can be very simple. Modern Integration can work with your EMR vendor to implement the embedding component.

The simplest method of embedding is using our miCRISPEmbed JavaScript API.

Located locally at: https://hostname:8443/assets/js/miCRISPEmbed.jsLocated remotely at: https://crisp.linkhie.com/assets/js/miCRISPEmbed.js

This JS API provides the quickest implementation solution with very little development. Simply define a container in an HTML document in the embedding application (by element id), specify your parameters, and it should show up in the specified HTML element.

miCRISPEmbed requires jQuery. If the EMR does not have jQuery implemented it can be added with a script element. All parameters are consistent with the table on the previous page. The only exception is baseURL, which defines the base URL to your linkHIE Instance.

<div id="container"></div><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/jquery-1.8.3.min.js"></script><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/miCRISPEmbed.js"></script>

<script type="text/javascript">new miCRISPEmbed("container", {baseURL:"https://hostname:8443/",user:"appuser",mrn: "11122"

});</script>

iFrame embedding is another way to embed linkHIE into an application. Just like the previous example, the application must support custom HTML, and the ability to build a custom URL.

Query String Example:<iframe src="https://hostname:8443/Embed.aspx?user=appuser&mrn=11122"></iframe>

XHTML Form Example:

<iframe name="myiframe"></iframe>

<form method="POST" action="https://hostname:8443/Embed.aspx" target="myiframe"><input type="hidden" name="user" value="appuser" /><input type="hidden" name="mrn" value="11122" />

</form>

Embedding (Continued)

Single Click SSO TrustlinkHIE supports single click SSO using public tokens that are generated dynamically using a simple algorithm that is supported in most mainstream programming languages.

• Public Token• Generated by a simple algorithm, and keeps the private token hidden• Uses the application user ID, a time stamp, and the private token to

generate a public token that is sent with each SSO request along with the token timestamp

• Public tokens invalidate after15 minutes, and can only be used once

Generating a public token requires the following functionality:

• Username extraction from embedding application• Generation of a time stamp (parsable date time string)

• Represents the instant the token was generated• MD5 hashing

The public token should be generated on a server side script in order to keep the private token secret.

Single Sign-On Trust (Continued)

Pseudo code explaining the algorithm to generate public token:

var user = ‘APPLICATION_USERNAME’var private_token = ‘YOUR_PRIVATE_TOKEN’var token_dt = DateTime.Now // Example: 2020-01-01 06:30:01var public_token = MD5(private_token + user + token_dt)

/*public_token = ‘YOUR_PRIVATE_TOKENAPPLICATION_USERNAME2020-01-01 06:30:01’public_token = MD5(public_token)public_token = ‘c33ed7961d7f04ec2991a59d8b82eb4b’

*/

Full example of embedding component with public token

PHP

<?php$user = 'appuser';$private_token = 'TnPoKdCrGq2vCZVbnpqIUxgWyrOTry';$token_dt = date('c');$public_token = md5($private_token . $user . $token_dt);

?><div id="container"></div><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/jquery-1.8.3.min.js"></script><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/miCRISPEmbed.js"></script><script type="text/javascript">

$(document).ready(function(){new miCRISPEmbed("container", {

baseURL:"https://hostname:8443/",user:'<?php echo $user; ?>',mrn: "11122",single_click_sso:true,public_token:'<?php echo $public_token; ?>',token_dt:'<?php echo $token_dt; ?>'

});});

</script>

ASP.Net (C#)<%@ Page Language="C#" %><%

string user = "appuser";string private_token = "TnPoKdCrGq2vCZVbnpqIUxgWyrOTry";string token_dt = DateTime.Now.ToString();string public_token = "";using (System.Security.Cryptography.MD5 md5 = System.Security.Cryptography.MD5.Create()){

byte[] hashBytes = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(private_token + user + token_dt));for (int i = 0; i < hashBytes.Length; i++) {

public_token += hashBytes[i].ToString("X2");}

}%><div id="container"></div><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/jquery-1.8.3.min.js"></script><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/miCRISPEmbed.js"></script><script type="text/javascript">

$(document).ready(function(){new miCRISPEmbed("container", {

baseURL:"https://hostname:8443/",user:'<% Response.Write(user); %>',mrn: "11122", sso_launch_target:'blank',single_click_sso:true,public_token:'<% Response.Write(public_token); %>',token_dt:'<% Response.Write(token_dt); %>'

});});

</script>

Microsoft SQL Server (T-SQL)

DECLARE @user VARCHAR(255)DECLARE @private_token VARCHAR(255)DECLARE @token_dt VARCHAR(255)DECLARE @public_token VARCHAR(255)

SET @user = 'appuser'SET @private_token = 'TnPoKdCrGq2vCZVbnpqIUxgWyrOTry'SET @token_dt = SYSDATETIME()SET @public_token = CONVERT(nvarchar(32), HASHBYTES('MD5', CONCAT(@private_token, @user, @token_dt)), 2)

SELECT CONCAT('<div id="container"></div>', CHAR(10),'<script type="text/javascript" src="https://crisp.linkhie.com/assets/js/jquery-1.8.3.min.js"></script>', CHAR(10),'<script type="text/javascript" src="https://crisp.linkhie.com/assets/js/miCRISPEmbed.js"></script>', CHAR(10),'<script type="text/javascript">', CHAR(10),

'$(document).ready(function(){', CHAR(10),'new miCRISPEmbed("container", {', CHAR(10),

'baseURL:"https://hostname:8443/",', CHAR(10),'user:"', @user,'",', CHAR(10),'mrn:111222,', CHAR(10),'single_click_sso:true,', CHAR(10),'public_token:"', @public_token, '",', CHAR(10),'token_dt:"', @token_dt,'"', CHAR(10),

'});', CHAR(10),'});', CHAR(10),

'</script>', CHAR(10))

Single Sign-On Trust (Continued)

JavaScript Should not be used unless private token or source code can be hidden or obfuscated

<div id="container"></div><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/jquery-1.8.3.min.js"></script><script type="text/javascript" src="https://crisp.linkhie.com/assets/js/miCRISPEmbed.js"></script><script type="text/javascript" src="https://www.modernintegration.com/js/generic.js"></script><script type="text/javascript">$(document).ready(function(){var user = 'appuser';var token_dt = epochToHuman(new Date().getTime() / 1000);var privateToken = 'TnPoKdCrGq2vCZVbnpqIUxgWyrOTry';var public_token = privateToken + user + token_dt;

md5Hash(public_token, function(public_token) {new miCRISPEmbed("container", {baseURL:"https://hostname:8443/",user:user,mrn:"111222",single_click_sso:true,public_token:public_token,token_dt:token_dt

});});

});</script>

Cerner mPage Workflow Embedding Example<div>

<iframesrc="https://crisptest.linkhie.com/assets/component/loading.html"linkhie="crisp"frameborder="1"style="width:100%;height:600px;"onload="

var iframe=this;$(this).attr('src_root', this.src.split('/')[2]);$.getScript('https://'+$(this).attr('src_root')+'/assets/component/js/mpage_workflow.js')

.done(function(){setTimeout(function(){linkHIELoad($(iframe));}, 2000);});"linkHIE_baseURL="https://linkhie-instance-root"linkHIE_single_click_sso="true"linkHIE_private_token="SsOpRiVaTeToKeN"linkHIE_sso_embed="true"linkHIE_app="aPpLiCaTiOnKeY"linkHIE_user="appusername"linkHIE_firstname="patientFirstName"linkHIE_lastname="patientLastName"linkHIE_gender="patientGender"linkHIE_dob="patientBirthDate"linkHIE_mrn="patientMRN"linkHIE_facility="crispFacilityCode"

></iframe>

</div>

The above source code will be implemented with Cerner’s mPage CCL (jQuery is required). linkHIE uses an iframe component and custom attributes to drive JavaScript logic. The div element is used to contain the iframe, and other items that will appear when the JavaScript code loads.

iFrame can be customized using CSS file or style attribute to create the desired appearance.Standard Attributes

• src• Initial value is set to linkHIE remote

hosted server to use for custom code import

• By default, this value should be set to the component loading view

• onload• Contains code that dynamically loads

JavaScript logic from linkHIE server• If any errors are present, the JavaScript

can be imported using <script> tags

• This logic will automatically launch JavaScript that will drive the process going forward

Cerner mPage Workflow Embedding Example (Continued)

Custom AttributesAttributes that start with linkHIE_ are interpreted as standard application parameters (documented previously). The only non standard parameter is linkHIE_root_url. Any attributes can be used to customize the user experience. This example showcases recommended minimum configuration options for optimal performance.

• linkHIE_baseURL• linkHIE instance base URL

• linkHIE_single_click_sso• JavaScript logic performs public key single sign on by default. If this

is desired, set value to TRUE• linkHIE_private_token

• Single Sign-On private token• Configured in your admin portal

• linkHIE_sso_embed• Toggle value to determine what CRISP view to display in component• For minimalized embedded view, set value to TRUE• For full view set value to FALSE or simply remove it entirely

• linkHIE_app• Application unique Identifier• This value is not necessary to set unless

• Username translations are defined for application• Auditing requires the source application to be logged

• linkHIE_user• Application username

• linkHIE_firstname• Patient first name

• linkHIE_lastname• Patient last name

• linkHIE_gender• Patient gender

• linkHIE_dob• Patient birth date

• linkHIE_mrn• Patient local MRN

• linkHIE_facility• Patient facility code• Assigned to your facility by CRISP• If a static facility code is desired, and the global facility code is

configured in admin portal, delete this attribute

Cerner mPage Workflow Embedding Example (Continued)

Network Connectivity

If the embedding environment is resting behind firewalls or other forms of network controls then the network routing must be configured to access a few outbound server connections.

• Local linkHIE instances• Server(s) containing local installation of linkHIE software

• Remote CRISP linkHIE server• This will be assigned by Modern Integration once your account is initially

set up• Server stores configuration information, stores basic audit information (no

patient data), and collects statistics of usage so that Modern Integration can monitor usage to make sure enough server resources are assigned

• CRISP Servers• crisphealth.org• crisphealth.force.com• test.crisphealth.org• portal.crisphealth.org