Summary
ClinSpark Agent version 1.3.1 introduced a ‘properties’ file as a configurable mechanism to enhance certain integrations and capabilities with Zebra printer devices. Starting in Agent version 1.5.0, there is now improved support for implementation and use of the Agent ‘properties’ file across site installations.
Today sites commonly rely on the properties file to setup network printing configurations that can be shared across data collection machines. Full details on networked printing setups are documented in this article.
Prior to Agent 1.5.0, use of the Agent installation and upgrade process would replace any existing .properties file with defaults contained in the installation MSI. If needing to retain previously established property files, sites would need to manually update or replace the file, and repeat this process across all of PCs where the Agent is installed/upgraded.
Those challenges have now been alleviated, and customers who use Agent 1.5.0 or greater can now pick a strategy to manage the properties file in a way that best meets their needs.
File locations
ClinSpark Agent versions 1.3.1 through 1.4.1 will create and use the properties file located in the default installation directory:
C:\Program Files\Foundry Health\ClinSparkAgent
Starting in ClinSpark Agent 1.5.0 and greater, the properties file will now be managed based upon certain Windows Environment Variables (see below).
It’s important to note that when upgrading from Agent 1.3.1 through 1.4.1 to the latest release, any previously established properties file in the default installation directory will be removed. If sites wish to retain any existing properties file from a given install, they must backup/manage those files accordingly.
For most sites, the location of the properties file will be the local user AppData\Roaming directory, which is the same directory that the Clinspark Agent log file is located . For example:
C:\Users\SiteUser\AppData\Roaming
Windows Environment Variables
Starting in Agent 1.5.0 and greater, the installation/upgrade process using the MSI no longer builds and creates the properties file. Instead, the Agent during startup will look for any existing properties file in certain known locations. If a properties file does not exist in any of the known directories, a new (default) properties file will be created and used.
This logic is reliant upon directory locations defined by Windows system properties called environment variables. The Agent will look in the following order:
%CLINSPARK_CONFIG%
%APPDATA%
Current directory of ClinSparkAgent.exe (default install directory)
%CLINSPARK_CONFIG%
It is expected that this environment variable will not be present on PCs by default, as it would be established specifically by a system administrator.
Use of this environment variable is highly valuable for configurations where a properties file would want be shared across multiple computers. For example, this variable could point to a shared/network drive that could be referenced across one or more PCs configured with the variable. Additionally, it could be defined as a single directory on a local workstation that multiple users who are logging in and accessing Agent functions could reference from.
Further details about how this variable can be used for networked printing can be found in this article.
%APPDATA%
Overwhelmingly this environment variable will be present on local workstations and will likely be the default location of the properties file.
Based on Windows default behavior, this variable it is established at user login and originates from a registry setting. The file path is almost always the following:
C:\Users<user>\AppData\Roaming
In the above example, the will be the current user logged into the PC.
Unless sites rely on a group policy object (GPO) or workstation configuration that modifies this environment variable from default, users can expect to see Agent installations writing and using the properties file in that directory.
Current executable directory
If the %CLINSPARK_CONFIG% or %APPDATA% environment variables do not exist or cannot be read, the Agent will attempt to use a properties file from the same location that the executable is invoked. This will likely be the default Agent installation directory (C:\Program Files\Foundry Health\ClinSparkAgent).
Opening and modifying
The properties file is given a file extension of .properties. By default, Windows will likely not recognize this file type and not have a default application set to open and review it’s contents. This is typical of most installations.
The file however can be opened by a standard text editor (such as Notepad). When modifying the contents, it should be done with a user with elevated (Administrative) privileges on the machine. This ensures that edits made are properly saved and written to the file system.
It’s also recommended that this file be modified when the Agent executable is not running. Simply exit the Agent via the system tray icon before modifying, and then upon restart of the executable, the Agent will load in the latest settings from the file.
Agent Logs
The Agent logs will produce statements whenever it’s able to locate and use an existing properties file. This occurs every time the Agent executable file is invoked and used. The log statement will clearly show the location of the file. Additionally, statements will be written if no properties file can be found based on the standard logic. If a new properties file is created, it will be noted in the logs as well including the location it’s written to.
Technical Demonstration
Customers wanting to see a technical demonstration of this topic can review the following screencast.
Using SET commands
In the screencast, use of the SET command is demonstrated. However, when using the SET command in command prompt to establish environment variables, they are only being written for the current shell session.
While it is helpful to see this demonstrated for review/testing purposes, it’s expected that site IT groups determine the best way to establish these variables for long term use. They can also be added as a user variable or a system variable through the System properties dialogue.
Additionally, the SETX command can be used in shell sessions to write it to the registry and set permanently, depending on use.
Troubleshooting
Windows environment variables only function on PCs if the specified variable path exists and is valid. It’s good to ensure that any directory paths defined in the variables are accessible first via the Windows file browser before considering their use.
If an environment variable exists, but the path defined does not, the Agent considers this scenario as a variable not being defined and then moves on to the next choice in logical sequence (either %APPDATA% or local).