Quick User Guide to NAHLN HL7 Messaging 

Listed below are key steps and important information to begin electronic messaging test results for NAHLN.

Very Important: To initiate the process, email NAHLN.IT@aphis.usda.gov to inform us you are ready to 

start the process so we can assist you appropriately. A member of our NAHLN Laboratory Messaging 

Services (LMS) Team will reply. 

The following steps will need to be completed prior to initiating messaging. 

1. Initial logistics:

a) Obtain system Accounts for messaging into NAHLN LMS

• A system account is used to transmit messages directly from the NAHLN lab LIMS to the VS LMS. 

You will receive accounts in both the LMS test and the LMS production environments. 

o If you already have an account, please provide that information to the LMS Team member.

• Send LMS system account requests to Help@aphis.usda.gov with VS IT LMS account request in the 

subject line. In the body of the email provide the following information for the system accounts:

o Account point of contact name, email and phone number

o Laboratory full name and address

• Account information will be provided to you by email.

b) If messaging CSF results, Obtain a VS Program IT system (VSLS) user account 

• This account may be needed to test data exchange interfaces built for reporting VS Program results

such as CSF, BSE and Scrapie or enter data. Contact the NAHLN.IT group at 

NAHLN.IT@aphis.usda.gov with “VS IT System: VSLS user account request, attn. NAHLN Staff” in 

the subject line. 

o Provide the following information and the NAHLN program office will complete and submit a 

Form 513 to request your account

 Indicate the VSLS system for which access is needed: BSE, CSF or Scrapie

 Your full name, email address and phone

 Laboratory name and address

 Lab Director name and phone number

 Indicate the role/s needed: Results Data Entry and/or Submission Data Entry

o If you need to test CSF result messaging contact NAHLN.IT@aphis.usda.gov, with subject “CSF 

Test Request.” LMS staff will then assist in coordinating testing.

c) Obtain access to NAHLN HL7 messaging references-- Join the NAHLN discussion forum

• This forum is hosted at the VTSL NAHLN Terminology Services web site. Resources available to 

forum members, including User, Implementation and Messaging Guides along with multiple Job Aids.

Additionally, registering for discussion forum updates will provide a method for staying informed of 

message schema updates.

• Go to http://vtsl.vetmed.vt.edu/nahln/main.cfm Click on Forum tab to request an account. 

• This is a venue that is also used by NAHLN laboratories to discuss progress and post questions. Your 

forum account can be customized so that you can receive or disable automated notices when new 

postings are submitted to the forum. System documentation and message schemas are available for 

download by forum members. 

d) Obtain a lab facility premise ID

• The laboratory facility premise identifier is currently known as a National Premises ID Number, 

usually referred to as a PIN

• Contact your State’s assigning authority (e.g. state department of agriculture) to obtain a premises ID.
Quick User Guide to NAHLN HL7 Messaging 

e) Obtain a lab system OID

• The lab system OID is used to uniquely identify an individual lab or a set of laboratory facilities,

managed as a system and usually located within a single state. Each State or Federal diagnostic 

laboratory facility must have an OID to participate in NAHLN HL7 messaging. 

o Go to http://vdpambi.vdl.iastate.edu/aavld_oid/Home/OIDTree and expand the ‘Partner_IDs’ tree 

branch to find out if your lab already has an OID assigned. If not, register for an account 

(http://vdpambi.vdl.iastate.edu/aavld_oid/Account/Register) to add or modify OIDs.

o Assistance with finding or obtaining a new Lab system OID can be obtained by contacting

NAHLN.IT@aphis.usda.gov enter Laboratory OID in the subject line.

f) Obtain a digital certificate for transmitting messages 

• A locally installed digital certificate is required for sending HL7 messages to LMS. If using cURL 

bundle, a specific certificate is not needed.

• Instructions for Other Users: 

o Access the certificates on the Messaging forum at: http://vtsl.vetmed.vt.edu/nahln/main.cfm by 

clicking the Forum navigation tab and then clicking the ‘NAHLN Documents’ discussion thread

2. Developing capability, mapping and connectivity within your LIMS: – This step is the most resource and 

time intensive. The NAHLN program collaborates with subject matter experts who work directly with 

NAHLN laboratories to provide assistance with this step. Additionally, other NAHLN labs that have 

established their messaging capabilities are excellent resources for this step, especially those who have 

the same LIMS. A member of the LMS team will help facilitate the appropriate contacts.

a) Access lab information stored in your LIMS 

• All information defined for transmission in the HL7 message needs to be identified in the LIMS (e.g. 

test result) or generated during the messaging event (e.g. Message ID, field constants). The data stored 

in the LIMS needs to be analyzed and compared to the data information required for messaging. The 

data access approach used to extract the data from the LIMS and identify data reporting trigger events 

needs to be developed. 

• Examine the LIMS system and any necessary ancillary systems to identify sources for each required 

data element. Note that some elements that are optional in the general message are required by specific 

testing programs. 

• Examine the laboratory workflow as represented in the LIMS system to determine the event that 

signals readiness of a test to be sent via message. (This is defined by NAHLN as the point at which the 

individual test result is final and verified.) This may be an existing part of the LIMS workflow or an 

explicit release to NAHLN action by the user.

• Develop methods to extract these data from the LIMS and to detect the trigger event.

• This step requires close collaboration between laboratory management and information technologists. 

Management provides deep understanding of the information and workflow. The information

technologists to provide technical access to system details.

• Evidence of completion consists of a listing of LIMS fields in both User Interface and database-specific 

terms. It may include SQL queries or other technical directions for data extraction.

b) Standardize required coded data elements

• Translate concepts represented with local terminology into concepts represented with a standardized 

terminology (e.g. name of lab test performed, test interpretation, specimen type, etc.)

• Information as recorded in the LIMS system database must be translated into the standard 

terminologies and data formats specified by the NAHLN standards.
Quick User Guide to NAHLN HL7 Messaging 

• Laboratory scientists must be able to provide unambiguous meanings for all required concepts as 

recorded in LIMS. They must work with information technologists to select appropriate codes from 

standard terminologies.

• Information technologists must determine the preferred mechanism for performing the translation 

function at run time. This may be internal to the LIMS or provided externally as part of the messaging 

process.

• Evidence of completion consists of complete mapping tables this may exist in both human-readable and 

machine-processable formats.

• Resources that may be helpful for completing this step can be found at the NAHLN terminology 

services web site at: http://vtsl.vetmed.vt.edu/nahln/main.cfm

o Vocabulary lists can be accessed directly by clicking on the Search tab

o HL7 Message Profile information including value sets and search and download options can be 

accessed at by clicking on the Message tab

c) Create the message and map the lab information

• A system needs to be configured to populate each message with information extracted directly or 

derived from the LIMS data along with generating and populating the remaining messaging data 

elements (e.g. message ID, date message sent, data field constants). 

• The translated data must be formatted into the appropriate XML data "file" as specified by HL7 and the 

NAHLN implementation guide.

• This requires technical resources to build an HL7 message using the selected technology (Rhapsody or 

other interface engine, reporting system, internal LIMS features, etc.) Refer to section 3.11 of the Lab 

Reporting User Guide for instructions for obtaining Rhapsody software

• Evidence of completion is a complete and correct message saved as a file. 

o Before sending, it is strongly recommended schema validation is completed to check for 

correctness by using XML tools; Rhapsody can be used for or there are a number of programming 

editors and other free tools (such and Notepad ++ and XML Tools. see the NAHLN Hitchhikers 

Guide for more details.

o If necessary, a manual examination by a member of the LMS Team can be requested. 

• Resources that may be useful to complete this step are the NAHLN message mapping tool, NAHLN 

HL7 Implementation Guide, and the Hitchhiker’s Guide to NAHLN Messaging

3. Transmitting messages to the NAHLN LMS systems - Before you transmit messages:

• Inform the LMS Team at NAHLN.IT@aphis.usda.gov that you are ready to start test messaging for 

each specific disease

• Ensure you have accessed and met requirements listed for that disease in the appropriate LMS 

Messaging Guide provided by the LMS Team member and/or the NAHLN terminology site.

a. Transmit and Validate HL7 message against automated business rules

• Transmit messages to the TEST environment at: 

https://vsapps.aphis.usda.gov/HL7ResultTest

The testing environment can be used for the purpose of sending a training message type (MSH.11 = 

T) or for the purpose of sending a debugging messaging type (MSH.11=D). 

 

• Select a method for transmission. This may be built into the LIMS or interface engine or any other 

mechanism capable of conducting a standard HTTPS web service call and receiving and storing the 

response XML "file." 

• Develop a system to regularly review the responses for any errors, etc. and correct and resend as 

necessary.

• Evidence of completion is a message sent to the NAHLN LMS system and receipt of a response with 

an acknowledgment code of "AA".
Quick User Guide to NAHLN HL7 Messaging 

b. Receive approval to transmit HL7 message into Production environment

• A member of the LMS Team will validate the structure and content of message (for each disease). 

• The LMS Team or NAHLN program office will approve your laboratory to begin transmitting HL7 

messaging into the PRODUCTION environment at: https://vsapps.aphis.usda.gov/HL7Result

• The production environment can be used for sending a production message type (MSH.11 = P).

c. Implement system to stay informed of terminology updates

• Terminology update notices are distributed via e-mail. These notices may occur as frequently as daily. 

An automated system will be used to distribute e-mail notices if at least one update has occurred in the 

past 24 hours. No notice will be sent that day if no updates occurred. If you would like to be added or 

removed from the list of e-mail addresses currently notified of updates to NAHLN messaging 

terminology please:

o Click on the Forum tab at http://vtsl.vetmed.vt.edu/nahln/main.cfm

o Post a note to the discussion thread: Veterinary Terminology Services Forums > NAHLN 

Messaging Forums > NAHLN Terminology Discussion > Terminology Updates 

References available by clicking on the Resources tab at http://vtsl.vetmed.vt.edu/nahln/main.cfm

1. NAHLN Implementation Guide 

2. The Hitchhiker’s Guide to NAHLN Messaging

3. Idiot’s Guides (Simple ‘how do I do it’ guides)

4. NAHLN IS Lab Registry User Guide

5. NAHLN IS Lab Registry Job Aid

6. NAHLN IS lab Reporting User Guide

7. NAHLN IS User Account Management Guide

8. NAHLN IS OID User Guide

9. NAHLN Message Map (excel spreadsheet)

10. Program Messaging Guides 

11. Example cURL script NAHLN messaging

12. Terminology Services Presentation (May 2007 training session)

13. Integrated Taxonomic Information System

14. Animal Diversity Web

15. The Complete Lexicon of Parrots

16. World Bird Guide 

17. OID registry