OpenELIS Global Analyzer Plugins

Repository for external analyzer plugins for OpenELIS Global. Currently 35 analyzers are supported across 30+ countries.

Quick Links

INVENTORY.md - Complete structured inventory with protocol details
Template - Plugin template for new analyzers
CONTRIBUTING.md - Architecture standards and contribution guidelines

Supported Analyzers

By Category

Hematology (12 analyzers)

Complete blood count (CBC) and differential analysis.

Analyzer	Manufacturer	Protocol	Transport
HoribaMicros60	Horiba ABX	ASTM	RS232
HoribaPentra60	Horiba ABX	ASTM	RS232
Mindray	Mindray	HL7	TCP/IP
pocH-100i	Horiba ABX	ASTM	RS232/TCP
Sysmex2000i	Sysmex	FILE	Filesystem
Sysmex4000i	Sysmex	FILE	Filesystem
SysmexKX21	Sysmex	FILE	Filesystem
SysmeXT	Sysmex	FILE	Filesystem
SysmexXN-L	Sysmex	ASTM	RS232/TCP
SysmexXN1000	Sysmex	FILE	Filesystem
SysmexXP	Sysmex	ASTM	RS232/TCP
SysmexXT4000i	Sysmex	FILE	Filesystem

Molecular (9 analyzers)

PCR, viral load, and nucleic acid testing.

Analyzer	Manufacturer	Protocol	Transport
AB7500Fast	Applied Biosystems	FILE	Filesystem
Cobas4800	Roche	FILE	Filesystem
Cobas6800VL	Roche	HL7	TCP/IP
CobasTaqMan48DBS	Roche	FILE	Filesystem
CobasTaqMan48VL	Roche	FILE	Filesystem
CobasTaqman96VL	Roche	FILE	Filesystem
CobasTaqMan96DBS	Roche	FILE	Filesystem
FluoroCyclerXT	Hain Lifescience	FILE	Filesystem
GeneXpertFile	Cepheid	FILE	Filesystem
GeneXpertHL7	Cepheid	HL7	HTTP/TCP

Chemistry (5 analyzers)

Clinical chemistry panels (glucose, creatinine, liver enzymes, etc.)

Analyzer	Manufacturer	Protocol	Transport
CobasC111	Roche	FILE	Filesystem
CobasIntegra400	Roche	FILE	Filesystem
Fully	Unknown	FILE	Filesystem
Mindray	Mindray	HL7	TCP/IP

Flow Cytometry (4 analyzers)

CD4/CD3 counting for HIV monitoring.

Analyzer	Manufacturer	Protocol	Transport
FacsCalibur	BD Biosciences	FILE	Filesystem
FacsCantoII	BD Biosciences	FILE	Filesystem
FacsPresto	BD Biosciences	FILE	Filesystem
weberAnalyzer	Weber	FILE	Filesystem

Immunology (1 analyzer)

Immunoassay testing (HIV, HBsAg, VDRL).

Analyzer	Manufacturer	Protocol	Transport
AbbottArchitect	Abbott	HL7	TCP/IP

Coagulation (1 analyzer)

Coagulation testing (PT, INR, APTT, Fibrinogen).

Analyzer	Manufacturer	Protocol	Transport
StagoSTart4	Stago	ASTM/HL7	RS232/TCP

Generic/Template (2 items)

Item	Description
GenericASTM	Database-driven ASTM plugin for dashboard-configured analyzers
template	Plugin development template for creating new analyzer plugins

By Protocol

HL7 v2.x (5 analyzers)

HL7 messages over TCP/IP with MLLP framing (0x0B start, 0x1C+0x0D end).

Analyzer	MSH-3 Sending Application	Category
AbbottArchitect	ARCHITECT or ABBOTT	Immunology
Cobas6800VL	(Contains "Load Viral")	Molecular
GeneXpertHL7	(HTTP servlet)	Molecular
Mindray	MINDRAY	Hematology/Chemistry
StagoSTart4	STAGO	Coagulation

ASTM LIS2-A2 (8 analyzers)

Bidirectional laboratory instrument communication (ENQ/ACK/NAK framing).

Analyzer	Transport	H-Segment Identification
GeneXpert	RS232/TCP	Contains "GeneXpert"
GenericASTM	RS232/TCP	Database pattern matching
HoribaMicros60	RS232	Contains "ABX^MICROS60"
HoribaPentra60	RS232	Contains "ABX^PENTRA60"
pocH-100i	RS232/TCP	Contains "pocH-100i"
StagoSTart4	RS232	Contains "START4" or "STAGO"
SysmexXN-L	RS232/TCP	Contains "XN-L"
SysmexXP	RS232/TCP	Contains "XP-100"

FILE (23 analyzers)

CSV/TXT file exports monitored via filesystem watcher.

Molecular (7): AB7500Fast, Cobas4800, CobasTaqMan series (4), FluoroCyclerXT, GeneXpertFile

Hematology (7): Sysmex2000i, Sysmex4000i, SysmexKX21, SysmeXT, SysmexXN1000, SysmexXT4000i

Chemistry (3): CobasC111, CobasIntegra400, Fully

Flow Cytometry (4): FacsCalibur, FacsCantoII, FacsPresto, weberAnalyzer

Molecular (2): QuantStudio3

See INVENTORY.md for complete file format details.

Building

Prerequisites (required once per OpenELIS version)

Plugins depend on org.openelisglobal:openelisglobal:3.2.1.2 (classifier classes), which is not on Maven Central. Install it locally first.

Run the install script (tries lightweight sources first, falls back to Maven build):

# From OpenELIS-Global-2 root (submodule):
plugins/scripts/install-oe-jar.sh

# Or from this repo's root:
./scripts/install-oe-jar.sh

The script tries three sources in order:

GitHub release download (~5s) — requires gh CLI
Docker image extraction (~6s) — requires Docker with itechuw/openelis-global-2 image
Local Maven build (minutes) — only if running inside the OE2 submodule tree

Build All Plugins

mvn clean install

Build Single Plugin

From the repository root (recommended):

mvn clean package -pl :PluginArtifactId -am

-am (also-make) ensures local dependencies like test-utilities are built. Use :ArtifactId syntax (e.g., :CobasC111, :GeneXpert).

Deployment

Prerequisites

Java 21 LTS
Maven 3.8+
OpenELIS Global 2.x

Installation

Copy the built JAR to the plugins directory:

cp target/*.jar /var/lib/openelis-global/plugins/

Restart OpenELIS:
```
docker compose restart oe.openelis.org
```
Verify plugin loaded:
- Navigate to: Results > Analyzer
- Plugin should appear in the dropdown menu

Using Analyzer Plugins

File-Based Analyzers

Configure file import directory (if applicable)
Analyzer exports results to configured directory
OpenELIS monitors directory and imports automatically

ASTM Analyzers

Install and configure OpenELIS Analyzer Bridge
Connect analyzer via RS232 or TCP/IP
Configure analyzer in OpenELIS Dashboard
Results flow bidirectionally

HL7 Analyzers

Configure network settings on analyzer
Point analyzer to OpenELIS IP/port
Configure analyzer in OpenELIS Dashboard
Results received via HL7 ORU^R01 messages

Testing Plugins

Writing Tests for Analyzer Plugins

Plugin tests that extend AnalyzerLineInserter require special handling because the base class attempts to access Spring beans during construction. To handle this, extend PluginTestBase from the test-utilities module:

import org.junit.Test;
import org.openelisglobal.plugin.test.PluginTestBase;

public class MyAnalyzerLineInserterTest extends PluginTestBase {
  @Test
  public void testParseLine_WithValidData_ReturnsRecord() {
    MyAnalyzerLineInserter inserter = new MyAnalyzerLineInserter();
    // Test parsing logic - SpringContext is automatically mocked
  }
}

Adding Test Dependencies

In your plugin's pom.xml:

<dependencies>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.openelisglobal.plugins</groupId>
    <artifactId>test-utilities</artifactId>
    <version>1.0</version>
    <scope>test</scope>
  </dependency>
</dependencies>

Running Tests

# Run all tests
mvn test

# Run tests for a specific plugin
mvn test -pl ./analyzers/PluginName

# Run a specific test class
mvn test -pl ./analyzers/PluginName -Dtest=MyTestClass

Test Infrastructure

The test-utilities module provides PluginTestBase, which automatically:

Mocks SpringContext.getBean() to prevent NullPointerException
Sets up and tears down mocks before/after each test
Allows testing parsing logic without a full Spring application context

For custom service mocking, override setupMocks():

@Override
protected void setupMocks() {
  MyService mockService = mock(MyService.class);
  when(SpringContext.getBean(MyService.class)).thenReturn(mockService);
}

Creating New Analyzer Plugins

Quick Start

Copy template/ as starting point:

cp -r analyzers/template/ analyzers/MyAnalyzer/

Update plugin descriptor XML
Implement analyzer identification logic
Add test mappings
Build and test

Plugin Requirements

Analyzer interface implementation
File/message identification logic
Test code to OpenELIS test mappings
Build configuration (pom.xml)
README.md documentation

Contributing

See CONTRIBUTING.md for:

Plugin architecture standards (Java 21, Maven layout, code formatting)
Lazy initialization pattern (required for all Spring bean access)
How to write and test new plugins
Quality requirements and prohibited patterns
Contribution workflow

Key Architecture Requirement

All plugins MUST use lazy initialization for Spring beans. Static initializers that call SpringContext.getBean() are prohibited as they prevent unit testing. See CONTRIBUTING.md for the required pattern.

Dynamic Configuration (GenericASTM)

GenericASTM allows analyzers to be configured entirely through the OpenELIS dashboard without writing Java code. See Feature 004 (analyzer-management) for details.

Note: GenericASTM requires the 2-table analyzer model, available on develop since feat/011 merged.

Modifying Existing Plugins

Contact Original Author: Check plugin's contact.txt if present
Coordinate with Core Team: Ensure changes don't break existing deployments
Backward Compatibility: Maintain compatibility with existing configurations
Update Documentation: Update plugin's README.md

Adding New Plugins

Create plugin from template/
Follow plugin requirements above
Add comprehensive README.md
Submit pull request to openelisglobal-plugins

Support

Issues: Report bugs via GitHub Issues
Discussions: Join GitHub Discussions
Documentation: OpenELIS Global Wiki

Maintained By: OpenELIS Global Community
Plugin Repository: openelisglobal-plugins
Main Repository: OpenELIS-Global-2

Last Updated: 2026-02-02

Name		Name	Last commit message	Last commit date
Latest commit History 147 Commits
.cursor/ci-logs		.cursor/ci-logs
.github/workflows		.github/workflows
analyzers		analyzers
lib		lib
scripts		scripts
test-utilities		test-utilities
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PLUGIN-PR-INSTRUCTIONS.md		PLUGIN-PR-INSTRUCTIONS.md
PR23-TRIAGE.md		PR23-TRIAGE.md
README.md		README.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

OpenELIS Global Analyzer Plugins

Quick Links

Supported Analyzers

By Category

Hematology (12 analyzers)

Molecular (9 analyzers)

Chemistry (5 analyzers)

Flow Cytometry (4 analyzers)

Immunology (1 analyzer)

Coagulation (1 analyzer)

Generic/Template (2 items)

By Protocol

HL7 v2.x (5 analyzers)

ASTM LIS2-A2 (8 analyzers)

FILE (23 analyzers)

Building

Prerequisites (required once per OpenELIS version)

Build All Plugins

Build Single Plugin

Deployment

Prerequisites

Installation

Using Analyzer Plugins

File-Based Analyzers

ASTM Analyzers

HL7 Analyzers

Testing Plugins

Writing Tests for Analyzer Plugins

Adding Test Dependencies

Running Tests

Test Infrastructure

Creating New Analyzer Plugins

Quick Start

Plugin Requirements

Contributing

Key Architecture Requirement

Dynamic Configuration (GenericASTM)

Modifying Existing Plugins

Adding New Plugins

Related Documentation

Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages