HL7 v2 Integration Tutorial
This tutorial will guide you through setting up HL7 v2 integrations using the Healthcare Integration Platform.
Overview
HL7 (Health Level Seven) v2 is a widely used standard for exchanging healthcare information between systems. Our platform supports:
- Message Types: ADT, ORM, ORU, DFT, and more
- Transport: MLLP (Minimal Lower Layer Protocol)
- Versions: 2.3, 2.4, 2.5, 2.6, 2.7, 2.8
- Security: TLS encryption support
Prerequisites
- Healthcare Integration Platform access
- HL7 system with MLLP interface
- Network connectivity between systems
- Valid credentials (if required)
Step 1: Create HL7 Connection
Basic HL7 Connection
curl -X POST "https://your-platform.com/api/v1/connections" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Hospital ADT System",
"connection_type": "hl7",
"configuration": {
"host": "hl7.hospital.com",
"port": 2575,
"timeout": 30,
"use_tls": false
}
}'
Secure HL7 Connection with TLS
curl -X POST "https://your-platform.com/api/v1/connections" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Secure HL7 Interface",
"connection_type": "hl7",
"configuration": {
"host": "secure-hl7.hospital.com",
"port": 2576,
"timeout": 60,
"use_tls": true,
"message_types": ["ADT", "ORM", "ORU"]
}
}'
Test the Connection
curl -X POST "https://your-platform.com/api/v1/connections/{connection_id}/test" \
-H "Authorization: Bearer YOUR_TOKEN"
Expected Response:
{
"success": true,
"message": "HL7 connection successful",
"details": {
"host": "hl7.hospital.com",
"port": 2575,
"response_time": "150ms"
}
}
Step 2: Understanding HL7 Message Structure
Sample ADT^A01 Message (Admit Patient)
MSH|^~\&|EPIC|HOSPITAL|INTEGRATION|PLATFORM|20241218143000||ADT^A01|12345|P|2.5
EVN||20241218143000|||^SMITH^JOHN^J^DR^MD
PID|1||123456789^^^MRN||DOE^JOHN^MIDDLE^^MR||19800101|M|||123 MAIN ST^^ANYTOWN^ST^12345^USA||(555)123-4567||(555)987-6543||S||123456789|123-45-6789
NK1|1|DOE^JANE^||WIFE|123 MAIN ST^^ANYTOWN^ST^12345^USA|(555)123-4567
PV1|1|I|ICU^101^01^HOSPITAL||||^ATTENDING^PHYSICIAN^MD|||ICU|||A|||^ATTENDING^PHYSICIAN^MD|INP|||||||||||||||||||||20241218143000
Message Breakdown
- MSH: Message Header
- EVN: Event Type
- PID: Patient Identification
- NK1: Next of Kin
- PV1: Patient Visit
Step 3: Create HL7 to FHIR Integration
Integration Configuration
curl -X POST "https://your-platform.com/api/v1/integrations" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "HL7 ADT to FHIR Patient",
"description": "Convert HL7 ADT messages to FHIR Patient resources",
"source_connection_id": "hl7-connection-id",
"target_connection_id": "fhir-connection-id",
"schedule": "*/5 * * * *",
"transformation_rules": {
"type": "field_mapping",
"mappings": {
"resourceType": {"source": null, "default": "Patient"},
"identifier": {
"source": "segments.PID.field_3",
"transforms": [{
"function": "extract_mrn"
}]
},
"name": [{
"use": "official",
"family": {
"source": "segments.PID.field_5",
"transforms": [{
"function": "split_string",
"params": {"delimiter": "^", "index": 0}
}]
},
"given": [{
"source": "segments.PID.field_5",
"transforms": [{
"function": "split_string",
"params": {"delimiter": "^", "index": 1}
}]
}]
}],
"gender": {
"source": "segments.PID.field_8",
"transforms": [{
"function": "map_gender"
}]
},
"birthDate": {
"source": "segments.PID.field_7",
"transforms": [{
"function": "format_date",
"params": {
"input_format": "%Y%m%d",
"output_format": "%Y-%m-%d"
}
}]
}
}
}
}'
Step 4: HL7 Message Types and Use Cases
ADT Messages (Admit, Discharge, Transfer)
ADT^A01 - Admit Patient
Use case: Patient admission to hospital
Key segments: MSH, EVN, PID, NK1, PV1
Transformation focus: Patient demographics and admission details
ADT^A03 - Discharge Patient
Use case: Patient discharge from hospital
Key segments: MSH, EVN, PID, PV1
Transformation focus: Discharge information and final diagnosis
ORM Messages (Order Management)
ORM^O01 - Order Message
Use case: New order or order modification
Key segments: MSH, PID, PV1, ORC, OBR
Transformation focus: Order details and patient context
ORU Messages (Observation Results)
ORU^R01 - Observation Report
Use case: Lab results, vital signs, diagnostic reports
Key segments: MSH, PID, PV1, OBR, OBX
Transformation focus: Observation values and results
Step 5: Advanced HL7 Transformations
Complex Field Mapping with Conditions
{
"type": "field_mapping",
"mappings": {
"resourceType": {"source": null, "default": "Patient"},
"active": {
"source": "segments.PV1.field_2",
"transforms": [{
"function": "lookup",
"params": {
"lookup_table": {
"I": true,
"O": true,
"E": false,
"D": false
},
"default": true
}
}]
},
"maritalStatus": {
"source": "segments.PID.field_16",
"transforms": [{
"function": "lookup",
"params": {
"lookup_table": {
"S": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus", "code": "S", "display": "Never Married"}]},
"M": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus", "code": "M", "display": "Married"}]},
"D": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus", "code": "D", "display": "Divorced"}]},
"W": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus", "code": "W", "display": "Widowed"}]}
}
}
}]
}
}
}
Step 6: Error Handling and Validation
HL7 Message Validation
{
"validation_rules": {
"required_segments": ["MSH", "PID"],
"message_type_validation": true,
"field_validation": {
"PID.3": {"required": true, "pattern": "^[0-9]+$"},
"PID.5": {"required": true, "max_length": 100},
"PID.7": {"pattern": "^[0-9]{8}$"}
}
}
}
Error Handling Configuration
{
"error_handling": {
"on_validation_error": "skip_message",
"on_transformation_error": "log_and_continue",
"on_target_error": "retry_with_backoff",
"max_retries": 3,
"retry_delay_seconds": 30
}
}
Step 7: Monitoring HL7 Integrations
Integration Statistics
curl "https://your-platform.com/api/v1/integrations/{integration_id}/stats?days=7" \
-H "Authorization: Bearer YOUR_TOKEN"
Response:
{
"total_messages": 1500,
"successful_transformations": 1425,
"failed_transformations": 75,
"message_types": {
"ADT^A01": 800,
"ADT^A03": 600,
"ADT^A02": 100
},
"success_rate": 0.95,
"average_processing_time": "250ms"
}
Common HL7 Issues and Solutions
- Connection Timeout: Increase timeout value or check network connectivity
- Invalid Message Format: Validate message format at source system
- Transformation Failure: Add null checking in transformation rules
Step 8: Testing HL7 Integration
Send Test Message
# Python example for sending test HL7 message
import socket
def send_hl7_message(host, port, message):
# MLLP framing
start_block = b'\x0b'
end_block = b'\x1c'
carriage_return = b'\x0d'
# Frame the message
framed_message = start_block + message.encode() + end_block + carriage_return
# Send via socket
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect((host, port))
sock.send(framed_message)
response = sock.recv(1024)
sock.close()
return response
# Test message
test_message = """MSH|^~\&|TEST|HOSPITAL|INTEGRATION|PLATFORM|20241218143000||ADT^A01|TEST123|P|2.5
PID|1||123456789^^^MRN||DOE^JOHN^MIDDLE^^MR||19800101|M|||123 MAIN ST^^ANYTOWN^ST^12345^USA||(555)123-4567"""
response = send_hl7_message('localhost', 2575, test_message)
Integration Test
curl -X POST "https://your-platform.com/api/v1/integrations/{integration_id}/test" \
-H "Authorization: Bearer YOUR_TOKEN"
Best Practices
Security
- Always use TLS for production HL7 connections
- Implement IP whitelisting
- Use VPN connections when possible
- Regularly rotate credentials
Performance
- Optimize transformation rules for high-volume scenarios
- Use batch processing for large message volumes
- Monitor connection pool usage
- Implement proper error handling and retries
Compliance
- Maintain audit logs for all HL7 message processing
- Implement data retention policies
- Ensure PHI is properly handled and encrypted
- Regular compliance audits
Monitoring
- Set up alerts for connection failures
- Monitor message processing rates
- Track transformation success rates
- Regular performance reviews