Skip to main content

Need Help Using Spok Knowledge?

Certain site features may not be supported by older versions of Internet Explorer.
Chrome, Edge, Firefox, or Safari will provide the most optimal experience.
Spok

HL7 Interface

Smart Suite HL7 Interface

The Smart Suite HL7 interface is specially designed to be compatible with many other vendors' HL7 products. Configuration files specify the message and segment formats which make up the HL7 protocol, so the product can be made to conform to different HL7 release levels (within the design and limits of the product), and deal with idiosyncrasies of specific implementations. Any part of this document is subject to change without notice.

Smart Suite Patient Database Table

The table below shows the fields included in the standard Smart Suite configuration.

If you attempt to send any values that go over the maximum set for a given column, the insert will fail with an Oracle error of 12899 -- value too large for column. You should make every effort to inspect your data and compare it to the rules defined below to correct the issue.

Patient Directory Field Name

Character Size in Patient Directory

Character Size from HL7 Standard

HL7 Data Fields

Description

Patient ID

20

20

PID 3;1

Internal patient ID.

Name

48

48

PID 5; 1

PID 5; 2

PID 5; 3

PID 5; 4

PID 5; 5

PID 5; 6

Patient's name in the form of <family>, <given>, <middle>, <suffix>, <prefix>, <degree>

Facility

20

20

MSH 4

Sending facility.

Room

12

See Extracting Locations

PV1 3;2

Assigned patient's room.

Bed

12

See Extracting Locations

PV1 3;3

Assigned patient's bed.

Nursing Station

12

See Extracting Locations

PV1 3;1

Assigned patient's nursing station.

Patient Type

3

1

PV1 18

Patient type.

Patient Class

1

1

PV1 2

A common field used to categorize patients by site.

Patient sub-type

2

User Defined(Z)

User Defined (Z)

Additional patient type.

Sex

1

1

PID 8

A character that represents patient gender.

Hospital Service

3

3

PV1 10

The treatment of type of surgery the patient is scheduled to receive.

Admission Date/Time

Date Type

26

PV1 44

The date/time the patient was admitted into the Hospital.

Discharge Date/Time

Date Type

26

PV1 45

The date/time the patient was discharged from the Hospital.

Admitting Doctor

60

60

PV1 17; 2

PV1 17; 3

PV1 17; 4

PV1 17; 5

PV1 17; 6

PV1 17; 7

Admitting doctor in the format of <id>, <family>, <given>, <middle>, <suffix>, <prefix>, <degree>, <source table id>

Attending Doctor

60

60

PV1 7; 2

PV1 7; 3

PV1 7; 4

PV1 7; 5

PV1 7; 6

PV1 7; 7

Same format as admitting doctor.

Referring Doctor

60

60

PV1 8; 2

PV1 8; 3

PV1 8; 4

PV1 8; 5

PV1 8; 6

PV1 8; 7

Same format as admitting doctor.

Consulting Doctor

60

60

PV1 9; 2

PV1 9; 3

PV1 9; 4

PV1 9; 5

PV1 9; 6

PV1 9; 7

Same format as admitting doctor..

NINP Code

1

60

PV2 2;1

Not In, Not  Published.  Indicates the specific patient accommodations for this visit.

Confidentiality

8

User Defined (Z)

User Defined (Z)

User defined patient confidentiality.  This an optional field that is not included with the stand patient interface installation.

Death Indicator

1

1

PID 30

A flag that indicates whether the patient is alive or not.

Birth Date

Date Type

26

PID 7

Patient's date of birth.

CPI Number

20

16

PID 2; 1

External patient ID.

Religious Preference

3

3

PID 17

Patient's religion

Restrictions

3

2

PV1 16

VIP indicator.

VPI

50

1

PV2 22

Visit Protection Indicator.

First Street

80

See Extracting Address

PID 11; 1

First street address.

Second Street

80

See Extracting Address

PID 11; 2

Second street address.

City

80

See Extracting Address

PID 11; 3

The name of the city.

State or Province

80

See Extracting Address

PID 11; 4

The name (code) of the state or province.

Zip or Postal Code

16

See Extracting Address

PID 11; 5

The zip or postal code.

Country

60

See Extracting Address

PID 11; 6

The name of the country.

Address Type

32

See Extracting Address

PID 11; 7

A code or text that describes the address type.

Address Remark

2000

See Extracting Address

PID 11; 8

Remark about the address.

Visit Suffix

Number

15

PID 18;1

PID 18; 2

Unique number assigned to each patient visit.

Remark

2000

N/A

None

A note taken by the operator.

Last Updated

Date Type

N/A

None

This field is updated by a trigger in the Smart Suite database. When a record is changed it stores the transaction time.

Field Formatting

 

When you send multiple components in a field to populate a column in the Smart Suite patient table, keep in mind that the purpose of the interface is to display the patient record to an end-user in a readable format. Due to this, there are at times extra characters added such as spaces and commas. The name field, for example, is 48 characters.  A comma is added after the last name and spaces are added in between each component sent. Therefore, if you are sending all 6 components in this field, a comma and space will be added between the first two (last name and first name) and an additional space between each, adding 6 characters to the total.  In that scenario, your maximum value sent could be no more than 42 or the insert will fail.  If you only send the last name and first name, a comma and a space will be added, so your maximum value sent could be no more than 46 or the insert will fail.  The same is true of the Admitting / Referring / Consulting Doctor fields.

Extracting Locations (Room, Bed, Nursing Station)

The location fields are derived from the HL7 patient location field, which has a total length of 12 characters.  The Smart Suite HL7 separates the HL7 patient location fields in the Smart Suite patient directory.

Extracting Address Fields

Address fields are derived from the HL7 address field, which has a total length of 106 characters. The length of the patient address is 106 by HL7 standard and can be changed to accommodate patient addresses that are greater than 106. We separate the HL7 address field into 8 fields in the Smart Suite patient directory.

Required Database Fields

The standard Smart Suite Patient Directory requires both patient id and visit suffix. The composite key of both fields is a primary key. This key allows maintaining multiple records per patient.

 

Currently, the patient directory is capable of keeping multiple records per patient. Keeping these records is achieved by making patient_id and visit_suffix a composite primary key. In this case, every record of the same patient_id is maintained independently if the visit_suffix is different.

Required HL7 Fields

Smart Suite's standard HL7 configuration files (hl7MsgRules, hl7SegRules, etc) require the following fields.

   MSH field 1 - Field separator
   MSH field 2 - Encoding characters
   MSH field 10 - Message control ID
   MSH field 11 - Processing ID
   MSH field 12 - Version ID
   PID field 3 - Patient ID (Internal ID)
   PID field 5 - Patient Name
   PV1 field 2 - Patient Class
   EVN field 1 - Event Type Code

Even if the above fields are set to be required, the requirement can be changed to optional upon request or during testing phase. In the case of of an A18 (merge), for example, the MRG field is required. The various segments can be set to required or optional on a per-transaction-type basis.

HL7 Messages

The standard configuration of the Smart Suite system will processes the following ADT message events. Events that are not listed below can be processed, but will require a custom configuration, which may include new message rules, segment rules and SQL statements. Conversely, if you send other events that are not configured, they will be ignored.

ADT Message Events

Description

Action

Note

A01

Admit

Add a patient record into patient table.

If record exists, then it will be updated.

A02

Transfer

Update room, bed and nursing station of a patient.

If record does not exist, then it will be added into the patient table.

A03

Discharge

Update the discharge date/time field of a patient with the new discharge date/time received.

If a record does not exist, then it will be added into the patient table.

A04

Register Patient

Same as A01.

Same as A01.

A05

Pre admit

Same as A01.

Same as A01.

A06

Transfer an Outpatient to Inpatient

Same as A01.

Same as A01.

A07

Transfer an Inpatient to Outpatient

Same as A01.

Same as A01.

A08

Update

Update a patient record.

If record does not exist, then it will be added into the patient table.

A09

Patient Departing

Same as A01.

Same as A01.

A10

Patient Arriving

Same as A01.

Same as A01 with discharge date

Set to blank.

A11

Cancel Admit

Delete a patient record.

The record will be deleted from the patient table permanently.

A13

Cancel Discharge

Clear the discharge date/time field of a patient record.

If the record does not exist, then it will be added into the patient table.

A14

Pending Admit

Same as A01.

Same as A01.

A17

Swap Patients

Swap room, bed and nursing station of two patients.

If the records don't exist, then they will be added into the patient table.

A18

Merge

Merge pre-existing two patient records into one.

If the records don't exist, then new record will be added into the patient table.

A23

Delete Patient Record

Same as A11.

Same as A11.

A28

Add Person Information

Same as A01.

Same as A01.

A29

Delete Person Information

Same as A11.

Same as A11.

A32

Cancel Patient Arriving

Same as A01.

Same as A01.

A33

Cancel Patient Departing

Same as A01.

Same as A01.

A34

 

 

Merge Patient Information

Merge Patient ID only.

 

A35

Merge Patient Information

Merge Account Number or Visit Suffix only.

 

A36

Merge Patient Information

Merge Both Patient ID and Visit Suffix.

 

For the above events, the expected segments are MSH, EVN, PID, and PV1, with PV2 being optional. User-defined segments follow the HL7 standard and need to begin with character Z. Merge message requires MRG segment.
 

HL7 Acknowledgements

The Smart Suite HL7 interface responds to each message following the HL7 acknowledgment rules. The acknowledgement message includes the segments MSH, MSA, and optionally ERR.

Acknowledgment codes are:

AA

Application Accept. The message received follows HL7 specification.

AE

Application Error. The message received does not follow HL7 specifications.

AR

Application Reject.  The message received cannot be processed due to unmatched sequence number or AE has occurred.

CA

Commit Accept. For messages that are applied to the database.

CE

Commit Error. For messages that violate database rule(s).

CR

Commit Reject. For messages that are not applied to the database.

Purging Patient Records

In order to minimize the number of records in the patient table, the Smart Suite archival program purges patient records every night. The purge uses standard or configured rules to select the records that are no longer needed. Once matching records are found, the process removes the records from the patient table.

The Smart Suite Standard Rules to purge patient records include:

- Patients discharged three days ago.
- Patients that have patient_class of E (typically Emergency visits) and were admitted three days ago.
- Patients that have patient_class of O (typically Outpatient visits) and were admitted three days ago.

 

While the above rules are simply the standard rules in Smart Suite to purge patient records, the following options remain available:

Adding new rules.
Modifying the existing rules.
Replacing the rules by other rules.

For example, some sites choose to remove the patient data based on the patient_type field rather than the patient_class field. Some have special criteria for pre-admits; some may want the records removed that night if they were discharged; some may want to remove the records from the Smart Suite patient table entirely by facility nightly (as their operators have no need to see those specific patients); some may use a patient_class of O for observation rather than outpatient, and so those would not be desired to be removed three days after admission.

 


KB41739