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:

1. GitHub release download (~5s) — requires gh CLI
2. Docker image extraction (~6s) — requires Docker with itechuw/openelis-global-2 image
3. 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

1. Copy the built JAR to the plugins directory:

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

2. Restart OpenELIS:

   docker compose restart oe.openelis.org

3. Verify plugin loaded:

   • Navigate to: Results > Analyzer
   • Plugin should appear in the dropdown menu

---

Using Analyzer Plugins

File-Based Analyzers

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

ASTM Analyzers

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

HL7 Analyzers

1. Configure network settings on analyzer
2. Point analyzer to OpenELIS IP/port
3. Configure analyzer in OpenELIS Dashboard
4. 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

1. Copy template/ as starting point:

   cp -r analyzers/template/ analyzers/MyAnalyzer/

2. Update plugin descriptor XML

3. Implement analyzer identification logic

4. Add test mappings

5. 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

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

Adding New Plugins

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

---

Related Documentation

• INVENTORY.md - Complete analyzer inventory with technical details
• Feature 011 Madagascar Analyzers - Madagascar deployment specifics

---

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