Summary
The ClinSpark Agent is a patented separate / companion application to ClinSpark that enables deep integrations between the web application and peripheral systems. 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.
Prerequisites
Workstations, laptops and select tablet devices are supported running the Agent as long as they meet these minimum requirements:
Microsoft Windows 10 or later
Minimum 4 GB RAM
Minimum 1 GB hard drive space
Downloading the Agent
Controlled access to the Agent installer MSI files are available to registered users in our Service Desk support portal.
Installation
The Agent Window Installer package (MSI) is provided via a protected ZIP directory.
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. Sites that enforce strict network policies may restrict communications over this port, 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.
As a 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 can be taken on the local PC to review network and firewall configurations, ultimately to determine if communications inbound/outbound are allowed on that port via the Agent.
Device Dependencies on Visual C++ Runtime 2013
Starting in Agent version 22.2, the certain glucose device interfaces will require Visual C++ Runtime 2013 libraries to be present on the site PC. These libraries are not bundled with the Agent installer and may not be present on site PC prior to use.
Sites that experience issues invoking certain interface workflows may also see certain error messaging in Agent logs, to 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.