hl7-pam-parser

What this skill does

# HL7 IHE PAM Message Parser and Explainer

## Overview

This skill parses and explains HL7 v2.5 IHE PAM (Patient Administration Management) messages - the standard healthcare interoperability format for patient administration events. The parser identifies message types, extracts segments and fields, validates structure according to IHE PAM 2.10 specifications, and provides human-readable explanations.

**When to use this skill:**
- Parse and explain any HL7 ADT message (raw HL7 text)
- Identify HL7 message type and event code (ADT^A01, ADT^A02, etc.)
- Extract and label all segments and fields (MSH, EVN, PID, PV1, PV2)
- Validate HL7 message structure and required fields
- Understand IHE PAM business rules and field mappings
- Debug HL7 message issues or data quality problems
- Document HL7 message examples with explanations

## HL7 v2.5 Message Format

HL7 messages use specific delimiters:

```
Field delimiter:        |  (pipe)
Component delimiter:    ^  (caret)
Repetition delimiter:   ~  (tilde)
Escape character:       \  (backslash)
Subcomponent delimiter: &  (ampersand)
```

**Basic Structure**:
```
MSH|^~\&|SendingApp|SendingFacility|ReceivingApp|ReceivingFacility|Timestamp||MessageType|MessageControlId|ProcessingId|VersionId
EVN|EventTypeCode|RecordedDateTime|...
PID|SetId||PatientId||PatientName||BirthDate|Sex|...
PV1|SetId|PatientClass|AssignedPatientLocation|...
```

**Segment Terminators**: Each segment ends with carriage return (`\r`) or newline (`\n`)

## IHE PAM Message Types

### ADT Messages (Admit, Discharge, Transfer)

#### ADT^A01 - Admit/Visit Notification
**Purpose**: Patient admission to inpatient care or registration

**Required Segments**:
- MSH (Message Header)
- EVN (Event Type)
- PID (Patient Identification)
- PV1 (Patient Visit)

**Example**:
```
MSH|^~\&|HEXAFLUX|CHU_PARIS|TARGET|DEST|20260122140000||ADT^A01^ADT_A01|MSG001|P|2.5
EVN|A01|20260122140000|||USER001
PID|1||PAT12345^^^CHU_PARIS^PI||DUPONT^JEAN^^M.||19750315|M|||15 RUE DE LA PAIX^^PARIS^^75001^FRA||(33)612345678
PV1|1|I|CHU_PARIS^CARDIO^LIT_001^CHU_PARIS||||PR_MARTIN^MARTIN^SOPHIE|||CARDIO||||||||||VIS20260122001|||||||||||||||||||||||||20260122140000
```

**Explanation**:
- **Event**: A01 (Patient Admission)
- **Patient**: DUPONT JEAN (M.), born 15/03/1975
- **Patient ID**: PAT12345
- **Visit**: VIS20260122001
- **Location**: CHU_PARIS, Cardiology, Bed LIT_001
- **Admission**: 22/01/2026 14:00:00
- **Patient Class**: I (Inpatient)
- **Attending**: Dr. MARTIN SOPHIE

#### ADT^A02 - Transfer a Patient
**Purpose**: Patient transfer between units, rooms, or services

**Required Segments**:
- MSH, EVN, PID, PV1
- PV2 (optional but recommended for prior location)

**Example**:
```
MSH|^~\&|HEXAFLUX|CHU_PARIS|TARGET|DEST|20260123090000||ADT^A02^ADT_A02|MSG002|P|2.5
EVN|A02|20260123090000|||USER002
PID|1||PAT12345^^^CHU_PARIS^PI||DUPONT^JEAN^^M.||19750315|M
PV1|1|I|CHU_PARIS^NEURO^LIT_102^CHU_PARIS||||PR_DURAND^DURAND^PAUL|||NEURO||||||||||VIS20260122001
PV2||||||||||||||||||||||CHU_PARIS^CARDIO^LIT_001^CHU_PARIS
```

**Explanation**:
- **Event**: A02 (Patient Transfer)
- **Patient**: PAT12345 (DUPONT JEAN)
- **From**: Cardiology, Bed LIT_001 (PV2-1: prior location)
- **To**: Neurology, Bed LIT_102 (PV1-3: assigned location)
- **Transfer Time**: 23/01/2026 09:00:00

#### ADT^A03 - Discharge a Patient
**Purpose**: Patient discharge from hospital

**Required Segments**:
- MSH, EVN, PID, PV1

**Example**:
```
MSH|^~\&|HEXAFLUX|CHU_PARIS|TARGET|DEST|20260125180000||ADT^A03^ADT_A03|MSG003|P|2.5
EVN|A03|20260125180000|||USER003
PID|1||PAT12345^^^CHU_PARIS^PI||DUPONT^JEAN^^M.||19750315|M
PV1|1|I|CHU_PARIS^CARDIO^LIT_001^CHU_PARIS||||PR_MARTIN^MARTIN^SOPHIE|||CARDIO||||||||||VIS20260122001|||||||||||||||||||||||||||20260125180000|||||HOME
```

**Explanation**:
- **Event**: A03 (Patient Discharge)
- **Patient**: PAT12345 (DUPONT JEAN)
- **Discharge Time**: 25/01/2026 18:00:00 (PV1-45)
- **Discharge Disposition**: HOME (PV1-36)
- **Visit**: VIS20260122001

#### ADT^A04 - Register a Patient
**Purpose**: Pre-admission or outpatient registration

**Required Segments**:
- MSH, EVN, PID, PV1

#### ADT^A05 - Pre-admit a Patient
**Purpose**: Pre-admission notification

#### ADT^A06 - Change Outpatient to Inpatient
**Purpose**: Convert outpatient visit to inpatient admission

#### ADT^A07 - Change Inpatient to Outpatient
**Purpose**: Convert inpatient admission to outpatient visit

#### ADT^A08 - Update Patient Information
**Purpose**: Update patient demographics

**Example**:
```
MSH|^~\&|HEXAFLUX|CHU_PARIS|TARGET|DEST|20260122150000||ADT^A08^ADT_A08|MSG004|P|2.5
EVN|A08|20260122150000|||USER001
PID|1||PAT12345^^^CHU_PARIS^PI||DUPONT^JEAN^^M.||19750315|M|||15 RUE DE LA PAIX^^PARIS^^75001^FRA||(33)612345678|||||||1234567890123||FRA
PV1|1|O||||||||||||||||||||VIS20260122001
```

**Explanation**:
- **Event**: A08 (Update Patient Information)
- **Patient**: PAT12345 demographics updated
- **Updated Fields**: Address, phone, national identifier (NIR)

#### ADT^A11 - Cancel Admit
**Purpose**: Cancel a previous admission

#### ADT^A12 - Cancel Transfer
**Purpose**: Cancel a previous transfer

#### ADT^A13 - Cancel Discharge
**Purpose**: Cancel a previous discharge

## Segment Definitions

### MSH - Message Header (Required)
**Purpose**: Message metadata and routing information

**Field Structure**:
```
MSH|^~\&|SendingApp|SendingFacility|ReceivingApp|ReceivingFacility|Timestamp||MessageType^EventCode^MessageStructure|MessageControlId|ProcessingId|VersionId
```

**Key Fields**:
- MSH-3: Sending Application
- MSH-4: Sending Facility
- MSH-5: Receiving Application
- MSH-6: Receiving Facility
- MSH-7: Date/Time of Message (YYYYMMDDHHmmss)
- MSH-9: Message Type (ADT^A01^ADT_A01)
- MSH-10: Message Control ID (unique identifier)
- MSH-11: Processing ID (P=Production, T=Training, D=Debugging)
- MSH-12: Version ID (2.5)

### EVN - Event Type (Required)
**Purpose**: Event-specific information

**Field Structure**:
```
EVN|EventTypeCode|RecordedDateTime|EventDateTime|EventReasonCode|OperatorId
```

**Key Fields**:
- EVN-1: Event Type Code (A01, A02, A03, etc.)
- EVN-2: Recorded Date/Time (when event was recorded)
- EVN-3: Event Occurred Date/Time (when event actually occurred)
- EVN-5: Operator ID (user who triggered the event)

### PID - Patient Identification (Required)
**Purpose**: Patient demographic information

**Field Structure** (30+ fields):
```
PID|SetId||PatientId^^^AssigningAuthority^IdType~AltId||LastName^FirstName^MiddleName^Suffix^Prefix||BirthDate|Sex|PatientAlias|Race|PatientAddress||PhoneHome|PhoneBusiness|PrimaryLanguage|MaritalStatus|Religion|PatientAccountNumber|SSN|DriverLicense|MotherIdentifier|EthnicGroup|BirthPlace|MultipleBirth|BirthOrder|Citizenship|VeteranStatus|Nationality|DeathDateTime|DeathIndicator
```

**Key Fields**:
- PID-1: Set ID
- PID-3: Patient Identifier List (PatientId^^^Facility^PI)
- PID-5: Patient Name (LastName^FirstName^MiddleName^Suffix^Prefix)
- PID-7: Date of Birth (YYYYMMDD)
- PID-8: Sex (M/F/O/U)
- PID-11: Patient Address (Street^^City^^PostalCode^Country)
- PID-13: Phone Number - Home
- PID-14: Phone Number - Business
- PID-22: Ethnic Group
- PID-29: Death Date and Time
- PID-30: Death Indicator (Y/N)

### PV1 - Patient Visit (Required)
**Purpose**: Visit/encounter information

**Field Structure** (52 fields):
```
PV1|SetId|PatientClass|AssignedLocation^Room^Bed^Facility|AdmissionType|PreadmitNumber|PriorLocation|AttendingDoctor^LastName^FirstName|ReferringDoctor|ConsultingDoctor|HospitalService|TemporaryLocation|PreadmitTestIndicator|ReadmissionIndicator|AdmitSource|AmbulatoryStatus|VIPIndicator|AdmittingDoctor|PatientType|VisitNumber|FinancialClass
```

**Key Fields**:
- PV1-1: Set ID
- PV1-2: Patient Class (I=Inpatient, O=Outpatient, E=Emergency, R=Recurring)
- PV1-3: Assigned Patient Location (Facility^Service^Room^Bed)
- PV1-4: Admission Type (E=Emergency, R=Routine, etc.)
- PV1-6: Prior Patient Location (for transfers)
- PV1-7: Attending Docto