A robust Windows service that bridges legacy HL7 systems with modern HTTPS endpoints. This service listens for HL7 messages on a TCP port and securely forwards them to any HTTPS endpoint, enabling seamless integration between healthcare systems.
- Download the latest release or clone this repository
- Configure your endpoints in
App.config - Install as a Windows service
- Start forwarding HL7 messages!
This lightweight C# Windows service acts as a reliable bridge between legacy HL7 systems and modern web APIs. Perfect for healthcare organizations needing to integrate older systems with cloud-based or web-based healthcare platforms.
- 🔄 Real-time Message Forwarding: Instantly forwards HL7 messages from TCP to HTTPS
- 🛡️ Secure Authentication: Built-in support for HTTP Basic Authentication
- 📊 Comprehensive Logging: Detailed event logging to Windows Event Viewer
- ⚙️ Easy Configuration: Simple XML configuration file
- 🔧 Production Ready: Runs as a Windows service with automatic startup
| Feature | Description |
|---|---|
| TCP Listener | Configurable IP and port for incoming HL7 messages |
| HTTPS Forwarding | Secure message forwarding to any HTTPS endpoint |
| Authentication | Username/password authentication for target endpoints |
| Error Handling | Robust error handling with detailed logging |
| Multi-threading | Concurrent connection handling for high throughput |
| Windows Service | Runs continuously in background with system startup |
- Operating System: Windows 7/Server 2008 R2 or later
- Framework: .NET Framework 4.7.2 or higher
- Privileges: Administrator rights for service installation
- Development (optional): Visual Studio 2017 or later for building from source
copy HL7forwardTCPtoHTTPS\App.config.template HL7forwardTCPtoHTTPS\App.configOpen App.config and configure your endpoints:
<appSettings>
<!-- TCP Listener Settings -->
<add key="ReceiveToIP" value="127.0.0.1" />
<add key="ReceiveToPort" value="7777" />
<!-- HTTPS Endpoint Settings -->
<add key="ForwardToHost" value="https://your-api.example.com/hl7" />
<add key="ForwardToUser" value="your-username" />
<add key="ForwardToPassword" value="your-password" />
</appSettings>| Parameter | Description | Example |
|---|---|---|
ReceiveToIP |
IP address to listen on | 127.0.0.1 (localhost) or 0.0.0.0 (all interfaces) |
ReceiveToPort |
TCP port for incoming HL7 messages | 7777, 2575, 6661 |
ForwardToHost |
Target HTTPS endpoint URL | https://api.example.com/hl7/messages |
ForwardToUser |
Username for HTTP Basic Auth | hl7user |
ForwardToPassword |
Password for HTTP Basic Auth | secure-password |
Security Note: Store credentials securely and consider using Windows credential storage for production deployments.
- Download
SetupHL7endpointTCPlistener.msifrom theSetupHL7forwardTCPtoHTTPSfolder - Run the installer as Administrator
- Follow the installation wizard
- Configure the service using the steps above
# Clone the repository
git clone https://github.com/vsaturnino/tcphl7lisenter.git
cd tcphl7lisenter
# Open in Visual Studio
start HL7forwardTCPtoHTTPS/HL7forwardTCPtoHTTPS.sln
# Build the solution (Ctrl+Shift+B)# Open Command Prompt as Administrator
# Navigate to .NET Framework directory
cd C:\Windows\Microsoft.NET\Framework64\v4.0.30319
# Install the service
installutil "C:\path\to\your\build\HL7endpointTCPlistener.exe"
# Start the service
net start "HL7endpointTCPlistener"# Stop the service
net stop "HL7endpointTCPlistener"
# Uninstall the service
installutil /u "C:\path\to\your\build\HL7endpointTCPlistener.exe"- Configure your endpoints in
App.config - Install the service using one of the methods above
- Start the service:
net start "HL7endpointTCPlistener"
- Send HL7 messages to the configured TCP port
- Monitor logs in Windows Event Viewer
# Test TCP connection (using telnet or similar)
telnet localhost 7777
# Send a sample HL7 message
# The service will forward it to your configured HTTPS endpoint- Windows Services: Check service status in
services.msc - Event Viewer: View logs under
Windows Logs > Application - Log Source: Look for events from "HL7endpointTCPlistener"
``` HL7endpointTCPlistener/ ├── HL7forwardTCPtoHTTPS/ │ ├── Program.cs # Service entry point │ ├── TCPtoHTTPS.cs # Main service logic │ ├── Subscriber.cs # TCP listener implementation │ ├── ProjectInstaller.cs # Service installer │ ├── App.config.template # Configuration template (copy to App.config) │ └── HL7forwardTCPtoHTTPS.csproj └── SetupHL7forwardTCPtoHTTPS/ # Setup project ```
| Issue | Cause | Solution |
|---|---|---|
| Service won't start | Configuration error | Check Event Viewer for details |
| Connection refused | Port already in use | Use netstat -an to check port usage |
| HTTPS errors | Invalid endpoint/credentials | Verify URL and authentication |
| Permission denied | Insufficient privileges | Run as Administrator |
| Messages not forwarding | Network/firewall issues | Check connectivity to target endpoint |
-
Check Event Viewer:
Windows Logs > Application > Filter by Source: "HL7endpointTCPlistener" -
Verify Port Availability:
netstat -an | findstr :7777
-
Test HTTPS Endpoint:
curl -X POST -u username:password https://your-endpoint.com/api/hl7
-
Check Service Status:
sc query "HL7endpointTCPlistener"
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow existing code style and conventions
- Add appropriate error handling and logging
- Test with various HL7 message formats
- Update documentation for new features
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: Report bugs or request features via GitHub Issues
- Discussions: Ask questions in GitHub Discussions
- Documentation: Check this README and inline code comments
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2024 | Initial release with TCP to HTTPS forwarding |
This service is perfect for:
- Healthcare Integration: Connect legacy HL7 systems to modern cloud APIs
- System Modernization: Bridge old hospital systems with new web applications
- Data Pipeline: Forward HL7 messages to analytics or storage systems
- Protocol Translation: Convert TCP-based HL7 to HTTPS REST APIs
Made with ❤️ for the healthcare community