ClinSpark Agent

Summary

The ClinSpark Agent is a patented separate / companion application to ClinSpark that enables deep integrations between the web application and peripheral systems running a Microsoft Windows operating system. The Agent application runs on a local user’s desktop and allows integration with devices such as Zebra label printers, ECG devices, vital sign machines, high precision scales, chroma meters, and much more.

Open

Downloading the Agent

Controlled access to the Agent installer MSI files are available to registered users in our Service Desk support portal.

Open

Installation

The Agent Window Installer package (MSI) is provided via a protected ZIP directory. The MSI package is intended for use on a Microsoft Windows computing device. More details about recommended computing devices for Agent use can be reviewed here: https://foundryhealth.atlassian.net/wiki/spaces/DOCS/pages/3707666674

The decrypt password for the ZIP directory is 0214.

Users will be guided through an automated installation procedure when invoking the MSI file. It’s recommended that the default install settings be used.

Across our customers, we typically see ClinSpark system administrators working closely with their site IT teams to ensure the install is done by a user with proper permissions.

It is strongly recommended that the Agent be installed under elevated (administrative) user account privileges to avoid any permissions based issues during standard use.

Verifying Agent version

Users at any time can verify what version of the Agent is installed on their computer. The version is displayed in the ‘About’ menu item, accessible via the Agent system tray icon.

Additionally, each time the Agent ‘starts’ it will write an entry to the log file about the version invoked along with some environment variables used for debugging purposes.

Enforcing version requirements

To help ensuring there is an appropriate match between ClinSpark and the Agent being used on local user workstations, a global system setting in Administration > General Settings > Data Collection establishes version requirements anywhere in ClinSpark the Agent may be used.

Latest versions of ClinSpark and Agent continue to introduce new device integrations and capabilities. Some of these features are not always “backwards compatible” with previous releases. It’s recommended that as customers upgrade to newer ClinSpark releases that they also consider updating their Agent versions as well, in order to take advantage of the latest capabilities. Questions about this process can be raised on the service desk.

Supporting multiple versions

Customers can use different ClinSpark Agent versions across their organization to meet different interface requirements across studies & sites. To accomplish this, the ‘Required ClinSpark Agent Version’ system configuration setting can be set to allow multiple Agent versions defined.

When multiple versions are defined, ClinSpark will ensure that device support is properly met with the Agent version being used by local users. For example, if a local user is running Agent version 1.2 and attempts to invoke a Glucose device workflow only supported by Agent 1.3, they will be prevented from doing so in the ClinSpark interface. However any other existing device workflows supported in Agent 1.2 (such as ECG or vital signs devices) will continue to function normally.

This ClinSpark system setting allows customers the flexibility & opportunity to establish an upgrade strategy for installed Agent versions across site workstations in parallel to ClinSpark upgrades. The goal is to ensure there is little disruption to study conduct while ClinSpark and Agent upgrades are evaluated and rolled out to customers.

Agent Permissions

The Agent executable runs under the same account privileges of the Windows user that invokes the executable file. The Agent executable is setup to be invoked upon user login, and therefore we typically see across our customers standard (non-administrative) Windows user accounts logged in to data collection PCs for use. These permissions may be necessary to consider for certain integrations that invoke other executables or processes required for various workflows.

Common Error Conditions & Troubleshooting Scenarios

Incompatible Version

In areas of ClinSpark that the Agent may be required for certain functionality, users may notice an error message indicating that the Agent could not be loaded due to version incompatibility.

“Could not load ClinSpark Agent. Required version: X.X, Version present: X”

This message implies that the Agent was detected, but not the version required as specified via the global system settings.

Agent not detected

A similar error message will show when ‘Version Present’ returns no value.

Under this condition, ClinSpark is unable to detect the Agent running on the local computer accessing ClinSpark. It’s possible that the Agent is either not installed, or, is not running. If the Agent is not running, usually restarting the data collection machine will reload the Agent. Otherwise, the application executable can be manually invoked in the following directory: C:\Program Files\Foundry Health\ClinSparkAgent

Loading of Agent is Disabled

An advanced global system setting called ‘Direct Device Interface’ will determine if certain bedside device integration capabilities are supported across a given instance. If disabled, users will receive a notification that ‘Loading of ClinSpark Agent has been disabled’ in several areas (such as Data Collection).

Concurrent Windows Users

The ClinSpark Agent has been designed for deployment and use in a Windows environment where a single user is logged into a PC at a given time.

When users ‘share’ a PC for ClinSpark/Agent interactions, where multiple users are logged in currently, the Agent may not start function properly for each user. Additionally, Agent interactions will not be written to local log files properly depending on who the current user is, making further troubleshooting difficult.

The recommended workflow for sites is to ensure that when a user is done with their work, they log out. This will ensure that the next user who logs into the PC, the Agent properly starts. Similarly, some site IT teams deploy an automated logout mechanism that ensures that when the system is inactive for a certain period the current user is automatically logged out. This can help ensure that whenever the computer is used for activities in ClinSpark, it’s done so with a user logging in an invoking the Agent executable without a concurrent session.

The following screencast demonstrates this scenario end to end, and explains some of the challenges with concurrent user setups.

Web Communications

The Agent communicates with ClinSpark web servers using HTTPS on port 8070, and other device interfaces using TCP/IP network communication protocol. Sites that enforce strict network policies may restrict these communications, which could lead to issues with certain features in ClinSpark/Agent that communicate through web services.

When the Agent is installed and run for the first time, Windows may prompt users with a message asking that network connections be allowed through the Agent. This must be accepted/allowed in order for the web communications to occur successfully.

Sites should verify that network connections for the Agent are allowed through Windows Firewall, and all necessary traffic ports. These settings can be configured within the Control Panel.

As an additional troubleshooting step, site administrators can confirm that the web socket connection is active while the Agent is running by visiting https://localhost:8070/ssl in a web browser. The confirmation of an ‘OK’ message in the browser window will indicate that the Agent is running properly and able to send/receive communications.

After that, further troubleshooting steps should be taken on the local PC and sites to review network and firewall configurations, ultimately to determine if communications inbound/outbound are allowed for the Agent.

Browser Extension Conflicts

Users may have browser extensions installed that interfere with communications that must take place between ClinSpark/Agent for interface workflows. More details on browser extensions are here: https://foundryhealth.atlassian.net/wiki/spaces/DOCS/pages/3700260899/Overview#Browser-Extensions

If users are unable to invoke device workflows, they should check to see if extensions are part of the cause. Using Chrome Developer tools for example, errors like the following may be present in the console:

In this example, a browser extension is blocking interactions between browser and the Agent, forcibly closing connections. This is accompanied by this message in ClinSpark:

This condition is symptomatic of ClinSpark being unable to communicate with the Agent on the local PC.

We’ve seen this observed with browser features/extensions that act as wide-spectrum content blockers (like uBlock, AdBlock, etc). Additionally, certain endpoint protection services that enterprise IT enforce on site machines may also cause this condition to occur if they are reporting communications between ClinSpark (browser) and Agent (local PC) as a false positive.

Device Dependencies on Visual C++ Runtime 2013

Dexcom and Microlife device interfaces require Visual C++ Runtime 2013 libraries to be present on the site PC. For Microlife, this is required in Agent version 1.5.2 onwards. For Dexcom, this is required in Agent version 22.2 onwards.

The runtime libraries are not bundled with the Agent MSI installer and may not be present on site PC prior to use of the interface.

Sites that experience issues invoking device workflows reliant on these libraries may see certain error messaging in Agent logs as well. These can help determine if these dependencies are missing:

The correct runtime libraries, either x86 or x64, need to be installed in order for the interface to function properly. This will depend on the JDK/JRE architecture in use by the Agent.

In order to verify, Agent logs can be inspected to verify the sun.arch.data.model property. When the Agent is first invoked (during computer reboot, or, manual restart of the executable) this environment variable is provided as part of the startup debug statements. It will indicate the presence of either a 32-bit or 64-bit JVM.

If the value is 32, then the x86 package should be installed.

If the value is 64, then the x64 package should be installed.