roy-harmon / universalis

UniversaLIS is a laboratory information system (LIS) for ASTM/CLSI-compliant clinical laboratory analyzers using serial and TCP connections.

UniversaLIS

An LIS system for ASTM/CLSI-compliant clinical laboratory instruments, written in C#. Originally created for Siemens IMMULITE systems, but expanded to work with any system that complies with ASTM-1381/1394 or CLSI-LIS1-A/LIS2-A2 specifications.

Installation

The project will eventually be updated to include an executable setup file. It was originally registered as a Windows service using InstallUtil, but migration from .NET Framework 4.8 to .NET 5.0 removed service installers. Restoring this functionality is top priority, but until I figure out the new cross-platform way to do this, the program can be executed using the Visual Studio debugger.

Please note: The software also requires a database server in order to function properly. See the next section for details.

Database

This Windows service is designed to connect to a database of your choice. Currently, only Microsoft SQL Server is supported, but MySQL and ODBC connection driver support is planned. Due to the deprecation of the native Oracle client in recent versions of the .NET framework, Oracle databases are not currently supportable without a third-party ODBC driver. Whichever data source you use, just be sure to specify a valid connection string in the UniversaLIS.exe.config file as discussed below.

While some parts of the database are fairly flexible, the UniversaLIS service expects certain tables and fields to be present. To that end, several SQL "CREATE TABLE" scripts will be provided in an upcoming release.

Configuration

The "config.yml" file contains several configuration items that should be changed according to your specific requirements. The details of each setting are described in the comments of that file. Note: For settings marked with an asterisk (*), ensure that the setting matches the analyzer's LIS Parameters configuration screen.

---

Usage

The program runs as a Windows service under a Local System account. After installation, the service should automatically start on boot. Or rather, "Automatic (Delayed Start)" since some RS-232 port drivers take a moment to initialize.

This program will eventually support all modes of operation available on the IMMULITE. The active communication mode is determined by the "LIS Host Query Mode" setting in the analyzer's LIS Parameters configuration screen.

• For "Unidirectional" mode:
  • Results are transmitted from the analyzer to the LIS and inserted into a database for storage and retrieval.
• For "Bidirectional" mode:
  • Pending test requests are pulled from a database (specified in the config file) and sent to the analyzer.
  • These test orders are stored in the analyzer's Worklist pending assignment to a sample cup.
  • When the operator enters data into the "Accession #" field on the analyzer's Worklist Entry screen, the relevant patient and test order information is populated automatically if the entered value matches a sample number in the list sent by the LIS.
    • This data entry can be performed manually or by scanning a barcoded label. For efficiency and accuracy, the latter is encouraged.
  • Results are transmitted from the analyzer to the LIS and inserted into a database for storage and retrieval.
• For "Bidirectional Query" mode:
  • Like "Bidirectional" mode, but if the "Accession #" input does not match an existing record in the Worklist, the analyzer queries the LIS for any pending test orders for the sample.

Please note that "Control" and "Verify" samples may be supported in the future, but initially, the focus is entirely on patient samples.

User Interface

A graphical user interface is not included at this time because most use cases will involve another application for management of patient information and test requests. Those applications (the good ones, anyway) are typically capable of interfacing with a SQL Server or MySQL database directly. Currently, the UniversaLIS software only forms a bridge between the instrument and a database server; this database server can be accessed by third-party programs to automatically transmit test requests to the instrument and pull results into the reporting software.

A simple GUI might be added in the future, but mostly for demonstration purposes. The real benefit of this software is in its ability to integrate with other systems, so while a GUI could be used, it would be less efficient in a production environment.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Acknowledgements

This software was written using information from the IMMULITE® Systems Interface Specification manual, downloaded from the Siemens Healthineers Document Library. Support for MySQL uses the Oracle MySQL team's MySQL Connector/.NET 8.0, used under the GPLv2 license as outlined here. IMMULITE is a trademark of Siemens Healthcare Diagnostics.

License

UniversaLIS is published under the MIT license.

MIT License

Copyright (c) 2021 Roy Harmon

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

universalis's Issues

Send to API and Test code mapping

Thanks for being generous 😊

please can you add the following functionalities;

1. to get orders orders from API,
2. send acknowledgement (true) after receiving the orders.
3. Able to request for orders after getting a order ID (read by machine barcode).
4. Able to post results to API (using order ID).
5. Finally functionality to map host test code to machine test code if they are different.
6. Thanks you so much

Test it on SCCSimulator(LISVendors)

Restore service functionality

With the move from .NET Framework 4.8 to .NET 5.0, installing as a Windows service isn't as easy as it used to be (since .NET 5.0 is cross-platform). There are new ways of doing this, apparently, but I'm not sure yet how it all works.
Topics to explore include:

• "sc create"
• Background Service
• IHostedService

If we can take advantage of the cross-platform nature of .NET 5.0 to implement similar functionality on other platforms, so much the better.

error on run

i just clone and run

Severity Code Description Project File Line Suppression State
Error MSB3323 Unable to find manifest signing certificate in the certificate store. UniversaLIS C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\amd64\Microsoft.Common.CurrentVersion.targets 3493

Store received message data when hierarchy level decrements

If results for an order are received and then an order or patient frame is received, the results for the previous order (and all other data received before the current frame) should be permanently stored. See CLSI-LIS2-A2 page 30 (Figure 2) for more details.
At the moment, results are only stored once the message's terminator frame is received.

Sharing a weird message/Frame

Hi
I want to share you a message not often used.
I had this kind of frame with an instrument.
I mix some of those vocable. that what i come back in the official document.
A few of vocable from the document ASTM E1381-02 or LIS1-A and LIS2-A2
A session starts with ENQ and ends with EOT. the protocol explain the send and response : ACK generally
A session include 1message if the session doesn't terminate abnormally. the message contains informations like IDs, test, age etc...
A frame is a subdivision of a message. it starts with STX, ends with ETX, checksum and CR LF
A record is described in LIS2-A2 as a group a field. the different records are H,P,O,C,R,M,S,L
then generally a frame (ETX-STX) contains one record.

Here is a message not often used. I don't know if you already saw one.
I thought it was a wrong implementation but after reading the LIS1 and LIS2 It's correct.
I can't not simulated this kind of message because I don't have anymore this instrument. and my simulator doesn't handle like this. Then I can not say if UniversaLIS can handle those frames.
I saw that your way to test the checksum seems to be able to handle this but it seems to me that it's not the case with the records, I should test to know.
Usually a CR means the end of a line (frame) but a CR can be in the middle of a frame. CR LF close the frame.
Here is the session formated.
->
<-
-> 1H|^&|0||EasyCell6|||||||P|E 1394-97|20191210155707
P|1||A8010700109||name1^Name2^name3||19351124|F|||||TORMA||||||||||||GUIG
O|1|0112101193||^^^CBCD^200|||20191210070000||||||||||||||||||F
C|1|I|^Les neutrophiles bande sont combi7C
<-
-> 2n s avec les neutrophiles segment s dans ce diff rentiel de leucocytes.|G
C|2|I|^223 cells in the differential.|I
R|1|^^^SEG%|48|%||L||F||MP||20191210155707
R|2|^^^BAND%|0|%||N||F||MP||20191210155707
R|3|^^^LYMPH%|41|%||N||F||MP||20191210150A
<-
-> 35707R|4|^^^MONO%|7|%||N||F||MP||20191210155707
R|5|^^^EO%|2|%||N||F||MP||20191210155707
R|6|^^^BASO%|2|%||N||F||MP||20191210155707
R|7|^^^SMUDGES|15|/100 WBCs||A||F||MP||20191210155707
R|8|^^^RBC NORMAL||||N||F||MP||20191210155707
R|9|^^^P3F
<-
-> 4LT|NORMAL|||N||F||MP||20191210155707
M|1|PHOTO|//192.168.1.175/report/0112101193_121019_01.jpg
M|2|REPORT|//192.168.1.175/report/0112101193_121019_01_1.pdf
L|1|N71
<-
->

here is the raw session
[2019/12/10][15:57:13.392][instrument.exe(Instrument)P:3276][T=3752]->
[2019/12/10][15:57:13.560][instrument.exe(Instrument)P:3276][T=3296]<-
[2019/12/10][15:57:13.691][instrument.exe(Instrument)P:3276][T=3752]-> 1H|^&|0||Instrument6|||||||P|E 1394-97|20191210155707P|1||A8010700109||name1^Name2^name||19351124|F|||||TORMA||||||||||||GUIGO|1|0112101193||^^^CBCD^200|||20191210070000||||||||||||||||||FC|1|I|^Les neutrophiles bande sont combi7C
[2019/12/10][15:57:13.822][instrument.exe(Instrument)P:3276][T=3296]<-
[2019/12/10][15:57:14.036][instrument.exe(Instrument)P:3276][T=3752]-> 2n s avec les neutrophiles segment s dans ce diff rentiel de leucocytes.|GC|2|I|^223 cells in the differential.|IR|1|^^^SEG%|48|%||L||F||MP||20191210155707R|2|^^^BAND%|0|%||N||F||MP||20191210155707R|3|^^^LYMPH%|41|%||N||F||MP||20191210150A
[2019/12/10][15:57:14.198][instrument.exe(Instrument)P:3276][T=3296]<-
[2019/12/10][15:57:14.412][instrument.exe(Instrument)P:3276][T=3752]-> 35707R|4|^^^MONO%|7|%||N||F||MP||20191210155707R|5|^^^EO%|2|%||N||F||MP||20191210155707R|6|^^^BASO%|2|%||N||F||MP||20191210155707R|7|^^^SMUDGES|15|/100 WBCs||A||F||MP||20191210155707R|8|^^^RBC NORMAL||||N||F||MP||20191210155707R|9|^^^P3F
[2019/12/10][15:57:14.579][instrument.exe(Instrument)P:3276][T=3296]<-
[2019/12/10][15:57:14.793][instrument.exe(Instrument)P:3276][T=3752]-> 4LT|NORMAL|||N||F||MP||20191210155707M|1|PHOTO|//192.168.1.175/report/0112101193_121019_01.jpgM|2|REPORT|//192.168.1.175/report/0112101193_121019_01_1.pdfL|1|N71
[2019/12/10][15:57:14.990][instrument.exe(Instrument)P:3276][T=3296]<-
[2019/12/10][15:57:15.306][instrument.exe(Instrument)P:3276][T=3752]->

Maistouse

little enhancement

Hi
I tried to use your project.
I did some modifications hereunder

[Update.md]

I'm working on project to connect several instrumenst in ASTM and HL7 then to make:

• a report (pdf) of all results from the same patient
• send result on a LIS in ASMT or HL7
  Thus i will come with others.
  Maistouse

Expand support to multiple ASTM E1381/1394 analyzers

Given the compliance with ASTM standards, this software should be applicable to other analyzers besides the Siemens IMMULITE series. ASTM E1394 specifies all field definitions for each type of record (header, patient, order, result, query, etc.). However, some product lines may not require the same record fields, so all fields defined by the ASTM E1394 standard should be supported and ignored if not required for the instrument. This should make it possible to support multiple instrument manufacturers' products, as long as they comply with the same standards.

The application could consult a configuration file to determine which fields to implement; this configuration could simply be a setting that points to one of multiple pre-defined configurations included with the application, and each supported instrument could correspond to a configuration file. Each (read-only?) configuration file could consist of a binary array representing the fields of each record type, and the values (0 or 1) in each position of the array would indicate whether a field is supported for that instrument.

If more record field customization is desired, the bit array could be copied from one of these instrument configuration templates upon initial setup, stored independently of its source template, and optionally customized/reconfigured via a GUI or other method.

Alternatively, it may be helpful to encapsulate the methods that generate the content of a message's individual frames.

Also note that the [Universal Test ID] field is in fact a four-part field delimited by carats (^); the Siemens IMMULITE specification simply does not implement the first 3 parts, resulting in what resembles a "^^^" prefix before each test code.

Unhandled contention state in bidirectional mode

Bidirectional mode may cause the application to stop responding when both the LIS and the analyzer attempt to send an ENQ at the same time. This results in a state of contention that needs to be safely handled according to the ASTM E1381/CLSI LIS1-A standard.
Implementing this feature in compliance with these standards will likely require significant code refactoring to allow for the various phases defined for LIS communications.