Contents
Information
The eLynx WebHost may be installed on any Windows computer that has a network connection that can reach both the SCADA/Database Server where the data currently resides, and the Internet to transmit the data to the eLynx system. While it is not a rule, we do recommend not installing the WebHost on the same computer as the SCADA/Database Server. We also recommend that the computer be running a recent supported version of Windows Server, but it will run on desktop versions of Windows as well.
There are two Windows Services that will be installed on your computer:
eLynx WebHost Snapshot Service – This service connects to your SCADA server or Database Server and issues queries for data that should be sent to the eLynx Service. The data from the query is “packaged” into XML files and stored temporarily on your hard drive. We support connections to MS-SQL Server, Oracle server, or most other systems that can be accessed via an OLEDB or ODBC connection.
eLynx WebHost Transport Service – This service takes the files created by the eLynx WebHost Snapshot Service, reduces the size by packing the files into .zip archives then sends those .zip files to the eLynx servers via an encrypted connection. Once the files are sent to eLynx they are stored for a few days on your hard drive, then deleted.
Assistance
We are here to help, while the actual installation is not difficult, our support team is available to assist in both installing and configuring the WebHost software for use in your system.
Acquiring the Installer
The installation software may be downloaded via our FTP server or may be sent via other methods. Our support team can provide you with the details for the FTP server or assist with finding another method to get the installation file to you.
Security
The installation software has been digitally signed by eLynx to verify authenticity.
Upgrading
When upgrading the prior version must be uninstalled first (either re-run the original installer and select “Remove”, or use Add/Remove programs in Windows Settings. Warning uninstalling will remove configuration files, please see the section below on upgrading for instructions on how to preserve your configuration files before performing the Uninstall / Re-install to upgrade.
Installing
The installer is an executable that is typically delivered inside a .zip archive. You do NOT need to extract the installer from the .zip to run it, just double-click on the .zip file (the name will be eLynxWebHostServiceInstaller-x.x.xx where the x’s represent the version number.) then double click the eLynx WebHost Service Installer.exe file inside the .zip to install the application.
The installer starts with a welcome screen, just click the Next button to proceed.
The installer will advance to the Install Location Screen, for most users the default location of c:\Program Files (x86)\eLynx\Webhost\ will be acceptable, however if your requirements are that the programs be installed elsewhere you can change that here by either typing in the full path, or clicking the … button and browsing to the install location.
The eLynx WebHost runs as a service under Windows, by default it users the LocalSystem account (built into Windows) however, if your Database system requires full built in Windows authentication you may enter appropriate user name, Domain, and password into this screen and we will set the services to run with this account. This user account will require permission to run as a service. If this account does not already have run services permission it might be easier to leave it as default and then “change” the login information in the Services Manager where it will confirm and then set that permission for the user account.
Clicking the Install button may bring up the User Access Control screen to verify authority to do the install, click the “Yes” button, and, if required login with an administrator account to finish the installation.
Once the installation is complete a final confirmation window will be shown (with a link to a ReadMe file). Click the “Finish” button to close the window. You are now ready to proceed with the configuration of the services.
Configuration
Configuring the eLynx WebHost Transport service.
If you did not change the installation directory when installing the software then the eLynx WebHost Transport service will be located in the folder:
C:\Program Files (x86)\eLynx\WebHost\WHTransport
Inside that folder you’ll want to edit the file named “WebHostTransportService.exe.config”
Please note that by default this file will require Administrator privileges to save any changes you make. For this reason it is often easiest to copy the file to another location (like your desktop), edit the file there, then copy it back. Copying the file back will prompt for administrative authority.
The .config file itself uses a series of parameters to control what files get sent, how often they get sent, and how long to keep the sent files (for backup purposes) before automatically deleting them.
Near the top of the file you’ll see several lines that start with <add key= these are the only lines that should ever need to be changed.
Key | Purpose | Default Value |
RunEveryXMinutes | Sets how often the service checks for new files to transfer to the eLynx system. | 5 |
WatchDirectory | Sets the folder name where new files will be placed that need to be sent. | C:\eLynx\WH\WatchDirectory |
CompressedDirectory | Sets the folder where the smaller .zip files are stored to be transferred to the eLynx system. | C:\eLynx\WH\CompressedDirectory |
ArchiveDirectory | Sets the folder where files are stored after they are successfully transferred to the eLynx system. | C:\eLynx\WH\ArchiveDirectory |
FileIdentifier | Sets the “prefix” that will be used for the .zip files, we recommend changing this to something that will help us identify where the files came from in the event we need to resolve issues with the files. | EWH_ |
FilesToTransfer | This is the filename wildcard that will be used when scanning the WatchDirectory to determine if a file should be sent to the eLynx system. | *.xml |
While there are other parameters in the configuration file, we recommend you only make changes to other parameters in consultation with the eLynx Support Team.
Configuring the WebHost Snapshot Service
If you did not change the installation directory when installing the software then the eLynx WebHost Snapshot service will be located in the folder:
C:\Program Files (x86)\eLynx\WebHost\WHSnapshott
Inside that folder you’ll want to edit the file named “WebHostSnapshotService.exe.config”
Please note that by default this file will require Administrator privileges to save any changes you make. For this reason, it is often easiest to copy the file to another location (like your desktop), edit the file there, then copy it back. Copying the file back will prompt for administrative permissions.
This file is where we will store all the information for how to connect to the SCADA/Database servers and the queries that are needed to extract the data to be sent to the eLynx system.
This file can get fairly complex if you need to query data from multiple tables in your database, and if you are not familiar with the XML file format and writing SQL queries we strongly recommend you contact eLynx Support for assistance.
This document will not cover the configuration in detail. A few lines into the file there is a large section that starts with “DataQuery configuration parameters” that covers all the parameters that may need to be set for each query along with information on what the parameter is used for, and in some more complex cases examples of usage.
Auto Daily Mode
Most queries will have two query lines “sqlquery” and “sqlqueryautodailymode” these will be very similar queries but provide parameters that can be used to limit the size of the query result by allowing you to include parameters to a WHERE clause in the query that set start and end timestamps for the data to be retrieved.
The system will automatically use the second “sqlqueryautodailymode” query if it has not been run for more than the value specified in autodailymodeindays, and we’ll run the query once for each day it has been since it last ran. This is done to minimize the chance that the query won’t be able to complete in a reasonable period of time, therefore fail, and just keep trying over and over. By requesting data one day at a time that will resolve the issue for most uses.
Single Value Snapshots versus Complex Table Snapshots
There are two main types of tables we routinely see when configuring the snapshots, one is a table that has a column which has a full unique reference to a single data item (for instance the differential pressure at one gas meter), then a timestamp and a data value. For example.
Item | Time | Value |
017090.Battery | 9/14/2022 2:43 PM | 12.76 |
017090.Temperature | 9/14/2022 2:44 PM | 87.5 |
017091.Battery | 9/14/2022 2:45 PM | 13.21 |
Alternately you might have a table where each row specifies a location, then there is a column with the timestamp, and multiple columns of data. For example.
Meter | Time | Temperature | Static Pressure | Differential Pressure | Rate |
017090 | 9/14/2022 2:00 PM | 86.6 | 156 | 45.2 | 1096.6 |
017091 | 9/14/2022 2:00 PM | 82.8 | 95 | 32.6 | 485.2 |
017092 | 9?14/2022 2:00 PM | 84.7 | 121 | 37.5 | 715.8 |
Both types of queries are supported in the Snapshot service, and you select which you need for a given table by setting the parameters tagthread and pivot to “false” for the first type and “true” for the second type.
If set to true then you will also need to add a set of DataColumn definitions to instruct the system which columns to send (and how to name them.)
Samples:
There are a couple of images below from some sample configurations to show you what a typical configuration might look like for each of these table types.
Type 1 Single Value
Type 2 Complex Table
Running the software.
When the software was installed entries were entered into the Windows Services database, these entries specify that both the WebHost Snapshot and WebHost Transport services should be started automatically any time the computer is rebooted.
Windows does allow you to manually start and stop the tool with the Services manager. In the services manager you’ll see the two entries listed next to each other as eLynx WebHost Snapshot Service and eLynx WebHost Transport Service. The Services manager allows you to start/stop/restart the services, and also to set whether or not they automatically restart when the computer restarts.
Debugging
WebHost Snapshot issues.
The WebHost Snapshot creates at least two log files when it runs. These files are located in the same location as the application in a folder named Logs which will be created automatically the first time the Service is started.
The overview log is named WebHostSnapshot.txt and will contain entries in the log for each time the software is started or stopped, as well as an error message any time a query fails.
The other files are all named based on the value in the “shortdescription” of the query configuration, each file will have an entry when the query is run showing exactly what query was sent to the database and a count of the number of items returned from the database.
WebHost Transport issues.
The WebHost Transport creates a single log file when it runs. These files are located in the same location as the application in a folder named Logs which will be created automatically the first time the Service is started.
The file is named WebHostTransport.txt and will have information logged every time performs any action (checking for new files to send, converting to .zip to reduce the file sizes, files sent or failed to send, and files archived for backup purposes, or deleted because they are out of date.
Automatic Cleanup
All log files created by the system are converted to .zip files any time a file gets larger than 1 MB in size. These .zip files are stored in the Archives folder underneath the Logs folder for each server. These .zip files are then deleted automatically after 7 days.
Upgrade Instructions
The installation program will not allow you to install a new version over the top of an existing version, therefore you must first uninstall the current version.
BEFORE UNINSTALLING THE CURRENT VERSION
The process of removing the software will also remove the configuration files, therefore, we strongly recommend you copy the WebHostTransportService.exe.config file and the WebHostSnapshotService.exe.config to a safe location before upgrading.
The easiest way to remove the current version of the software is to use Add/Remove Software in the Windows Settings application, highlight eLynx WebHost and click the “Remove” button.
You may now follow the instructions above to install the new version.
Once the installation is complete you should NOT just copy the configuration files back to the original locations as other information (required .NET versions etc.) may have changed. It is much better to open both the old and new files in text editors and COPY the relevant settings from the old file. In the case of the WebHostTransportService.exe.config you’ll want to replace the lines in the new file from <add key=”RunEveryXMinutes” through the line with add key=”FilesToTransfer”.
In the WebHostSnapshotServer.exe.config you’ll want to replace the entire section that starts with <DataQueries> and ends with </DataQueries> from the old file into the new one.
Comments
0 comments
Please sign in to leave a comment.