Getting Started with fi-fhir

This guide walks you through parsing your first healthcare message, understanding the output, and running a basic workflow.

Installation

Option 1: Build from Source

# Clone the repository
git clone https://gitlab.flexinfer.ai/libs/fi-fhir.git
cd fi-fhir

# Build the CLI
make build

# Verify installation
./bin/fi-fhir --version

Option 2: Go Install

go install gitlab.flexinfer.ai/libs/fi-fhir/cmd/fi-fhir@latest

Option 3: Docker

docker pull registry.gitlab.flexinfer.ai/libs/fi-fhir:latest
docker run registry.gitlab.flexinfer.ai/libs/fi-fhir:latest --version

Option 4: TypeScript SDK

npm install @fi-fhir/sdk

Parse Your First Message

Let's parse a sample HL7v2 ADT (Admit/Discharge/Transfer) message.

1. Create a Sample Message

Save this as sample.hl7:

MSH|^~\&|EPIC|HOSPITAL|FHIRSERVER|DEST|20240115120000||ADT^A01|12345|P|2.5
EVN|A01|20240115120000
PID|1||MRN12345^^^EPIC^MR||Smith^John^A||19800115|M|||123 Main St^^Springfield^IL^62701||555-123-4567|||||SSN123456789
PV1|1|I|ICU^101^A^HOSPITAL||||1234567890^Jones^Sarah^M^^^MD|||MED||||||||VN98765|||||||||||||||||||||||||20240115100000

2. Parse the Message

fi-fhir parse --format hl7v2 --pretty sample.hl7

3. Understand the Output

You'll see a JSON event like this:

{
  "meta": {
    "id": "evt_abc123",
    "type": "patient_admit",
    "source": "default",
    "format": "HL7v2",
    "timestamp": "2024-01-15T12:00:00Z",
    "source_message_id": "12345"
  },
  "patient": {
    "mrn": "MRN12345",
    "name": {
      "family": "Smith",
      "given": ["John", "A"]
    },
    "birthDate": "1980-01-15",
    "gender": "M",
    "address": {
      "line": ["123 Main St"],
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701"
    }
  },
  "encounter": {
    "identifier": "VN98765",
    "class": "inpatient",
    "location": "ICU-101-A"
  }
}

Key observations:

• The message type ADT^A01 became the semantic event patient_admit
• HL7 field paths like PID.5 are now structured JSON (patient.name)
• Healthcare-specific encoding (like ^ delimiters) is handled automatically

The Three-Phase Pipeline

fi-fhir processes messages through three distinct phases:

Phase 1: Byte Normalization

• Character encoding detection (UTF-8, ISO-8859-1, etc.)
• Line ending normalization (CR, LF, CRLF)
• BOM marker handling

Phase 2: Syntactic Parsing

• Delimiter extraction from MSH segment
• Segment and field splitting
• Escape sequence handling

Phase 3: Semantic Extraction

• Event type classification (A01 → patient_admit)
• Identifier extraction and validation
• Field mapping to canonical model

This pipeline is visualized interactively in the Playground.

Run a Basic Workflow

Workflows route events to destinations based on filters.

1. Create a Workflow Configuration

Save this as workflow.yaml:

workflow:
  name: basic_routing
  version: '1.0'

  routes:
    - name: log_admits
      filter:
        event_type: patient_admit
      actions:
        - type: log
          level: info
          message: 'Patient admitted: {{.Patient.Name.Family}}, {{.Patient.Name.Given}}'

2. Run the Workflow

# Parse and pipe to workflow
fi-fhir parse --format hl7v2 sample.hl7 | fi-fhir workflow run --config workflow.yaml

# Or use dry-run to see what would happen without side effects
fi-fhir parse --format hl7v2 sample.hl7 | fi-fhir workflow run --dry-run --config workflow.yaml

3. Expected Output

INFO  Patient admitted: Smith, [John A]

Parse Different Formats

CSV Patient Data

# Create sample CSV
cat > patients.csv << 'EOF'
mrn,first_name,last_name,dob,gender
12345,John,Smith,1980-01-15,M
67890,Jane,Doe,1990-06-20,F
EOF

# Parse
fi-fhir parse --format csv --pretty patients.csv

EDI 837P Claim

# Parse an EDI claim file
fi-fhir parse --format edi --pretty claim.edi

CDA/CCDA Document

# Parse a clinical document
fi-fhir parse --format cda --pretty document.xml

Validate Configuration

Before running in production, validate your configurations:

# Validate workflow configuration
fi-fhir workflow validate workflow.yaml

# Validate source profile
fi-fhir validate profile epic_adt.yaml

# Show current configuration
fi-fhir config show

Next Steps

To learn about...	Read...
Source Profile configuration	Source Profiles
Workflow filters and actions	Workflows
FHIR resource generation	FHIR Output
Interactive learning	Playground Tutorial

Common Issues

"Unknown format"

Ensure you specify --format correctly: hl7v2, csv, edi, cda, or fhir.

"Failed to parse message"

Check that your message is well-formed. Use --verbose flag for detailed error messages:

fi-fhir parse --format hl7v2 --verbose sample.hl7

"Warning: Missing segment"

This is often expected behavior. Healthcare data is messy, and fi-fhir records warnings while continuing to parse. See Source Profiles for tolerance configuration.