Connect an Instrument to InteLIS¶

Send an analyzer's results into InteLIS through the Interfacing Tool, so nobody types them in.

InteLIS must already be installed on the lab's Ubuntu machine. The analyzer must be connected to the lab network.

Choose the situation that fits, then follow its steps from top to bottom.

Tool on this machineTool on another computer

Use this when the Interfacing Tool runs on the InteLIS machine itself.

Install the Interfacing Tool¶

Open a terminal on the InteLIS machine and download the installer:

cd ~ && wget -O install-interfacing.sh "https://raw.githubusercontent.com/deforay/intelis-interfacing/master/scripts/install.sh?v=$(date +%s)"

Run it, and type the password when sudo asks for it:
```
bash install-interfacing.sh
```
To install a particular version

Add the version at the end:
```
bash install-interfacing.sh --tag v4.2.1
```

Add the analyzer in the tool¶

Open the Interfacing Tool from the applications menu.
Sign in with Login ID admin and password admin. The first sign-in opens Settings.
Under System, set Auto-connect on startup to Yes. With No, the tool stops listening after every restart until somebody signs in.

Under Instruments, select + Add Instrument and fill in these fields:

Field	Value
Connection Mode	TCP Server if the analyzer connects to this machine. TCP Client if this machine connects to the analyzer. The analyzer's manual says which.
Communication Protocol	ASTM, ASTM (with checksum) or HL7, as set on the analyzer.
IP Address	TCP Server: this machine's address on the lab network. TCP Client: the analyzer's address.
Port Number	The port set on the analyzer.
Analyzer Type	The analyzer model.
Instrument Name/Code	A name for this analyzer. Step 15 gives InteLIS the same name.

If the lab has more than one analyzer

Add each one here with its own port. One Interfacing Tool serves them all.

Select Save Settings.
Run one sample on the analyzer. Check that it appears under the received results on the tool's console.

If the result does not appear in the tool

Read the log on the instrument's tab. Server bound and listening on means the tool is waiting and the analyzer has not connected. Follow the tool's own troubleshooting guide.

Do not carry on until the tool shows the result. InteLIS can only import what the tool holds.

Connect InteLIS to the tool¶

In the terminal, run:

sudo intelis interface setup

If it shows What is configured now

Interfacing is set up already. To replace it, answer Yes to Set interfacing up again, replacing this?. To leave it as it is, press Enter.

If it stops with The InteLIS database is not reachable

Run sudo intelis fix-database. Then repeat step 9.

If intelis is not recognised

The install is older. Either update InteLIS and repeat step 9, or set it up by hand:

Open MySQL:
```
sudo mysql
```

Create the database and the account. Choose a long password in place of A-LONG-PASSWORD:

CREATE DATABASE IF NOT EXISTS interfacing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'interfacing'@'localhost' IDENTIFIED BY 'A-LONG-PASSWORD';
CREATE USER 'interfacing'@'127.0.0.1' IDENTIFIED BY 'A-LONG-PASSWORD';
ALTER USER 'interfacing'@'localhost' IDENTIFIED WITH mysql_native_password BY 'A-LONG-PASSWORD';
ALTER USER 'interfacing'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'A-LONG-PASSWORD';
GRANT ALL PRIVILEGES ON interfacing.* TO 'interfacing'@'localhost';
GRANT ALL PRIVILEGES ON interfacing.* TO 'interfacing'@'127.0.0.1';
EXIT;

MySQL 8.4 and later reject the ALTER USER lines with Plugin 'mysql_native_password' is not loaded. On those servers, leave them out.

Open the InteLIS settings file. On older installs, the folder is /var/www/vlsm:
```
sudo nano /var/www/intelis/configs/config.production.php
```

Set these lines, with the same password:

$systemConfig['interfacing']['enabled'] = true;
$systemConfig['interfacing']['database']['host'] = '127.0.0.1';
$systemConfig['interfacing']['database']['username'] = 'interfacing';
$systemConfig['interfacing']['database']['password'] = 'A-LONG-PASSWORD';
$systemConfig['interfacing']['database']['db'] = 'interfacing';
$systemConfig['interfacing']['database']['port'] = 3306;

Save with Ctrl+O, then close with Ctrl+X.

Go on to step 12, and enter host 127.0.0.1, port 3306, database interfacing, username interfacing and that password. Open the tool once so it creates its tables, then run intelis interface-migrate.

Answer the questions:

Question	Answer
How does the Interfacing Tool store the results InteLIS should read?	Press Enter. MySQL on this machine is already selected.
MySQL port	Press Enter (`3306`).
Database name	Press Enter (`interfacing`).
Where is the Interfacing Tool installed?	Press Enter. On this machine is already selected.
Enter a MySQL administrator account to use?	Asked only when setup finds no account of its own. Press Enter (Yes), then type the MySQL `root` username and password.
Name for the account the tool and InteLIS will use	Press Enter (`interfacing`).
Reuse it, and set its password to the one chosen next?	Asked only when the account exists already. Answer Yes if an earlier interfacing setup made it. Otherwise press Enter (No) and choose another name.
Password for that account	Press Enter. Use a generated password is already selected.

To have InteLIS read the tool's SQLite file instead

This is the simplest route, but it carries results only. Instrument activity and daily usage reporting need MySQL.

At the first question, choose The tool's own SQLite file on this machine.
At Which file?, press Enter. The tool's file is already selected. If no file is found, open the tool once, then repeat step 9.
If asked Grant www-data just enough access to read it?, press Enter (Yes).

Setup creates no database and no account on this route. Do step 11, then skip steps 12 to 14 and go on to step 15.

If the interfacing database is on another server

Setup creates nothing on another server. The database and its account must exist there already.

At the first question, choose MySQL on another server.
Enter the server's address, the MySQL port and the database name.
Enter the username and password of the account InteLIS connects as.

Setup checks the connection and looks for the tool's orders table. In step 12, enter that server's details, not the values below.

Wait for interfacing is now switched on. Setup then prints a table under Enter these in the Interfacing Tool. Keep the terminal open.

If it prints Still to do

Run each command it lists, in order. If it says This MySQL no longer offers mysql_native_password, the tool may fail to connect in step 13. Contact support with the tool's version.

Enter the database in the tool¶

In the tool, open Settings, then MySQL. Enter the values setup printed:

Printed setting Tool field

Host MySQL Host

Port MySQL Port

Database Database Name

Username Database User

Password Database Password
Select Test Connection.

If the tool cannot connect

Compare each value with the printed table. The password is also saved in /var/www/intelis/configs/config.production.php, on the line with ['interfacing']['database']['password'].
Select Save Settings.

Register the analyzer in InteLIS¶

Add the analyzer in InteLIS by following How to set up instruments and interfacing. Enter the tool's Instrument Name/Code as the Machine Name.

Check a result arrives¶

Run one sample on the analyzer, or re-send a finished result from the analyzer's screen.
In the terminal, import it now rather than waiting a minute:
```
sudo intelis interface
```
Expect the result counted:
```
Connected to MySQL
# of records from MySQL : 1
Processing 1 filtered results from Interface Tool
```
On the SQLite route, the first two lines read Connected to sqlite and # of records from SQLITE3 : 1.
If it counts 0 records

The result has not reached the database InteLIS reads.
- Check the tool's Sync Status column. If every result is Pending, repeat step 13.
- Only final results and failed runs are read. A result the analyzer has not finalised is left in the tool.
If it prints Error while syncing interface results

Open the newest file in /var/www/intelis/var/logs and search for the error. Send it to support if it does not name a fix.
Open the sample in InteLIS. Check that the result is there.

If the result is counted but not in InteLIS

The sample ID on the analyzer must match the sample code of a registered request in InteLIS, character for character. Register the request, or correct the ID on the analyzer, then repeat steps 16 to 18.
Leave the tool running. InteLIS now imports results every minute.
If results arrive by hand but not on their own

The scheduler is not running. Check it is installed:
```
sudo crontab -l | grep cron.sh
```
Expect this line:
```
* * * * * cd /var/www/intelis && ./cron.sh
```
If the line is missing, or calls crunz directly, see Maintenance scripts. If the line is there, check that this file's time is within the last minute:
```
ls -l /var/www/intelis/var/.cron_heartbeat
```

Use this when the Interfacing Tool runs on a different computer from InteLIS, such as a Windows computer beside the analyzer.

Install the Interfacing Tool¶

On the tool's computer, open a terminal and download the installer:
```
cd ~ && wget -O install-interfacing.sh "https://raw.githubusercontent.com/deforay/intelis-interfacing/master/scripts/install.sh?v=$(date +%s)"
```
If the tool's computer runs Windows

Download the file ending in -setup.exe from the releases page and run it. Then go on to step 3.
Run it, and type the password when sudo asks for it:
```
bash install-interfacing.sh
```
To install a particular version

Add the version at the end:
```
bash install-interfacing.sh --tag v4.2.1
```

Add the analyzer in the tool¶

Open the Interfacing Tool from the applications menu.
Sign in with Login ID admin and password admin. The first sign-in opens Settings.
Under System, set Auto-connect on startup to Yes. With No, the tool stops listening after every restart until somebody signs in.

Under Instruments, select + Add Instrument and fill in these fields:

Field	Value
Connection Mode	TCP Server if the analyzer connects to this computer. TCP Client if this computer connects to the analyzer. The analyzer's manual says which.
Communication Protocol	ASTM, ASTM (with checksum) or HL7, as set on the analyzer.
IP Address	TCP Server: this computer's address on the lab network. TCP Client: the analyzer's address.
Port Number	The port set on the analyzer.
Analyzer Type	The analyzer model.
Instrument Name/Code	A name for this analyzer. Step 22 gives InteLIS the same name.

If the lab has more than one analyzer

Add each one here with its own port. One Interfacing Tool serves them all.

Select Save Settings.
Run one sample on the analyzer. Check that it appears under the received results on the tool's console.

If the result does not appear in the tool

Read the log on the instrument's tab. Server bound and listening on means the tool is waiting and the analyzer has not connected. Follow the tool's own troubleshooting guide.

Do not carry on until the tool shows the result. InteLIS can only import what the tool holds.
Find this computer's address on the lab network, and write it down. On Ubuntu, run hostname -I and take the first address. On Windows, run ipconfig and take the IPv4 Address.

If this computer's address changes after a restart

Ask the network administrator to give it a fixed address first. InteLIS admits the tool from this one address only. A new address means repeating steps 10 to 21.

Connect InteLIS to the tool¶

On the InteLIS machine, open a terminal and run:

sudo intelis interface setup

If it shows What is configured now

Interfacing is set up already. To replace it, answer Yes to Set interfacing up again, replacing this?. To leave it as it is, press Enter.

If it stops with The InteLIS database is not reachable

Run sudo intelis fix-database. Then repeat step 10.

If intelis is not recognised

The install is older. Either update InteLIS and repeat step 10, or set it up by hand:

Open MySQL:
```
sudo mysql
```

Create the database and the account. Put the address from step 9 in place of TOOL_IP, and a long password in place of A-LONG-PASSWORD:

CREATE DATABASE IF NOT EXISTS interfacing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'interfacing'@'localhost' IDENTIFIED BY 'A-LONG-PASSWORD';
CREATE USER 'interfacing'@'127.0.0.1' IDENTIFIED BY 'A-LONG-PASSWORD';
CREATE USER 'interfacing'@'TOOL_IP' IDENTIFIED BY 'A-LONG-PASSWORD';
ALTER USER 'interfacing'@'localhost' IDENTIFIED WITH mysql_native_password BY 'A-LONG-PASSWORD';
ALTER USER 'interfacing'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'A-LONG-PASSWORD';
ALTER USER 'interfacing'@'TOOL_IP' IDENTIFIED WITH mysql_native_password BY 'A-LONG-PASSWORD';
GRANT ALL PRIVILEGES ON interfacing.* TO 'interfacing'@'localhost';
GRANT ALL PRIVILEGES ON interfacing.* TO 'interfacing'@'127.0.0.1';
GRANT ALL PRIVILEGES ON interfacing.* TO 'interfacing'@'TOOL_IP';
EXIT;

MySQL 8.4 and later reject the ALTER USER lines with Plugin 'mysql_native_password' is not loaded. On those servers, leave them out.

Open the InteLIS settings file. On older installs, the folder is /var/www/vlsm:
```
sudo nano /var/www/intelis/configs/config.production.php
```

Set these lines, with the same password:

$systemConfig['interfacing']['enabled'] = true;
$systemConfig['interfacing']['database']['host'] = '127.0.0.1';
$systemConfig['interfacing']['database']['username'] = 'interfacing';
$systemConfig['interfacing']['database']['password'] = 'A-LONG-PASSWORD';
$systemConfig['interfacing']['database']['db'] = 'interfacing';
$systemConfig['interfacing']['database']['port'] = 3306;

Save with Ctrl+O, then close with Ctrl+X.

Open the firewall to the tool's computer only:

sudo ufw allow from TOOL_IP to any port 3306 proto tcp

Then do steps 14 to 17. For the bind-address, use this machine's first address from hostname -I. In step 19, enter that address as the host, port 3306, database interfacing, username interfacing and that password. Open the tool once so it creates its tables, then run intelis interface-migrate.

Answer the questions:

Question	Answer
How does the Interfacing Tool store the results InteLIS should read?	Press Enter. MySQL on this machine is already selected.
MySQL port	Press Enter (`3306`).
Database name	Press Enter (`interfacing`).
Where is the Interfacing Tool installed?	On another computer on the lab network.
Address of the computer running the tool	The address from step 9. Do not enter `%`, which admits every computer.
Enter a MySQL administrator account to use?	Asked only when setup finds no account of its own. Press Enter (Yes), then type the MySQL `root` username and password.
Name for the account the tool and InteLIS will use	Press Enter (`interfacing`).
Reuse it, and set its password to the one chosen next?	Asked only when the account exists already. Answer Yes if an earlier interfacing setup made it. Otherwise press Enter (No) and choose another name.
Password for that account	Press Enter. Use a generated password is already selected.
Open port 3306 to the tool's address?	Asked only when the firewall is on and the port is closed. Press Enter (Yes).

If the interfacing database is on another server

Setup creates nothing on another server. The database and its account must exist there already, and must admit the tool's computer.

At the first question, choose MySQL on another server.
Enter the server's address, the MySQL port and the database name.
Enter the username and password of the account InteLIS connects as.

Setup checks the connection and looks for the tool's orders table. Skip steps 13 to 18. In step 19, enter that server's details, not the values below.

Wait for interfacing is now switched on. Setup then prints a table under Enter these in the Interfacing Tool. Write the five values down. The host is this machine's address on the lab network.

Let the tool's computer reach MySQL¶

Read the Still to do list under the table. If it has no line starting Set bind-address, go on to step 18.

Open the MySQL settings file:

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Change the bind-address line to the address the note gives, then save with Ctrl+O and close with Ctrl+X. For example:
```
bind-address = 192.168.1.10
```
Do not use 0.0.0.0. It offers the database to every network the machine is attached to.
Check the file, then restart MySQL:
```
sudo mysqld --validate-config && sudo systemctl restart mysql
```
If --validate-config prints an error

MySQL was not restarted. Open the file again, correct the line the error names, and repeat step 16.

If MySQL will not start

Follow MySQL will not start, then come back to step 17.
Check that MySQL listens on the lab address:
```
sudo ss -lntp | grep 3306
```
Expect the address from step 15, not 127.0.0.1.
If Still to do says port 3306 is closed, run the sudo ufw allow command it prints.

Enter the database in the tool¶

On the tool's computer, open Settings, then MySQL. Enter the values setup printed:

Printed setting Tool field

Host MySQL Host

Port MySQL Port

Database Database Name

Username Database User

Password Database Password
Select Test Connection.
If the tool cannot connect
- Compare each value with the printed table. The password is also saved on the InteLIS machine in /var/www/intelis/configs/config.production.php, on the line with ['interfacing']['database']['password'].
- On the InteLIS machine, repeat the check in step 17.
- On the InteLIS machine, run sudo ufw status. Port 3306 must be allowed from the address in step 9.
- Run step 9 again on the tool's computer. If the address has changed, repeat steps 10 to 20 with the new one.
- If Still to do said This MySQL no longer offers mysql_native_password, contact support with the tool's version.
Select Save Settings.

Register the analyzer in InteLIS¶

Add the analyzer in InteLIS by following How to set up instruments and interfacing. Enter the tool's Instrument Name/Code as the Machine Name.

Check a result arrives¶

Run one sample on the analyzer, or re-send a finished result from the analyzer's screen.
On the InteLIS machine, import it now rather than waiting a minute:
```
sudo intelis interface
```
Expect the result counted:
```
Connected to MySQL
# of records from MySQL : 1
Processing 1 filtered results from Interface Tool
```
If it counts 0 records

The result has not reached the database InteLIS reads.
- Check the tool's Sync Status column. If every result is Pending, repeat step 20.
- Only final results and failed runs are read. A result the analyzer has not finalised is left in the tool.
If it prints Error while syncing interface results

Open the newest file in /var/www/intelis/var/logs and search for the error. Send it to support if it does not name a fix.
Open the sample in InteLIS. Check that the result is there.

If the result is counted but not in InteLIS

The sample ID on the analyzer must match the sample code of a registered request in InteLIS, character for character. Register the request, or correct the ID on the analyzer, then repeat steps 23 to 25.
Leave the tool running. InteLIS now imports results every minute.
If results arrive by hand but not on their own

The scheduler is not running. Check it is installed:
```
sudo crontab -l | grep cron.sh
```
Expect this line:
```
* * * * * cd /var/www/intelis && ./cron.sh
```
If the line is missing, or calls crunz directly, see Maintenance scripts. If the line is there, check that this file's time is within the last minute:
```
ls -l /var/www/intelis/var/.cron_heartbeat
```
To add a second tool computer
1. On the first tool computer, open Settings, then Backup & Restore, and select Export Settings. Choose Settings and Credentials.
2. Install the tool on the second computer, as in steps 1 to 4.
3. On the second computer, select Import Settings and open the exported file.
4. Change the instrument names and ports to match the analyzers beside the second computer.
5. On the InteLIS machine, repeat steps 10 to 12 with the second computer's address. Answer Yes to replace the current setup, and Yes to reuse the account. The first computer keeps its own password and goes on working.
6. Open the firewall to the second computer. Setup does not offer this once port 3306 is open to the first one:
```
sudo ufw allow from SECOND_TOOL_IP to any port 3306 proto tcp
```
7. On the second computer, enter the newly printed values as in steps 19 to 21.

Printed setting	Tool field
Host	MySQL Host
Port	MySQL Port
Database	Database Name
Username	Database User
Password	Database Password