Section 03: Message Structure

From Nlets Wiki
Jump to: navigation, search

Message Structure

The purpose of this section is to establish basic ground rules upon which the Nlets system functions. It contains information that is either standard or applies to most Nlets messages. Message formats and computer interfaces are presented in the following sections.

Start of Message and Message Headers

Output Message Header

The Nlets system attaches control and special interest information as a message is passed through the system. As an example, Nlets "clocks" a message as it enters and leaves the system. The system also maintains control counts of all messages sent by Nlets (to a line in Legacy Transactions or an element in XML Transactions).

Nlets makes almost all of the special interest information available in each output message header. Users may ignore that which is not of interest for a particular message. Users that interface on an automated basis may reformat and use only that information determined to be pertinent.

Note: Nlets supports 8 character dates (ccyymmdd).

Message Identification

The message type for Nlets messages is a two to three character variable length field.

XML message types are identified by message key and included in the Nlets header. An example follows:

    <nh2:MessageKeyCodeText>

All Legacy Nlets messages must begin with the message type code followed by a period.

The tables below list the Message Codes and corresponding Message Types that have been identified.

MKE Description
AA Amber Alert
ACQ CVIS Inquiry on Commercial Carrier
ACR CVIS Response on Commercial Carrier
ALQ Alarm Exchange Query
ALR Alarm Exchange Response
AM Administrative Message
AML Administrative Message (Law Enforcement Only)
AQ CHRI Inquiry
AR CHRI Response
AVQ CVIS Inquiry on Commercial Vehicle
AVR CVIS Response on Commercial Vehicle
BQ Boat Registration Inquiry
BR Boat Registration Response
CCQ Charge Code Inquiry
CCR Charge Code Response
CPQ Parole, Probation, Corrections Inquiry
CPR Parole, Probation, Corrections Response
CR Triple I Response from NCIC
CWQ Concealed Weapons Inquiry
CWR Concealed Weapons Response
DNQ Driver Inquiry by Name Only
DNR Driver Response From Name Only Inquiry
DQ Driver Inquiry
DQG Driver Inquiry by Region
DR Driver Response
ER Error Message
FQ CHRI Inquiry
FQC IFTA File Query
FR CHRI Response
FRC IFTA File Response
GPQ General Persons Query
GPR General Persons Response
GQ FAA Aircraft Registration Inquiry
GR FAA Aircraft Registration Response
GVQ VIN Check Inquiry
GVR VIN Check Response
HQ Road/Weather Inquiry
HR Road/Weather Response
HS Homeland Security Message
HSL Homeland Security Message Law Enforcement Only
IAQ Immigration Alien Inquiry
IAR Immigration Alien Response
IQ CHRI Inquiry
IR CHRI Response
KQ Driver History Inquiry
KR Driver History Response
LE LoJack Transaction
LPQ License Plate Reader Inquiry
LPR License Plate Reader Response
LQ Generic Message Inquiry
LR Generic Message Response
MQ Hazardous Material Inquiry
MR Hazardous Material Response
NFQ RAND Full Text Message Inquiry
NFR RAND Full Text Message Response
NLQ RAND Message Log Inquiry]
NLR RAND Message Log Response
PAQ Parole, Probation & Corrections Inquiry
PAR Parole, Probation & Corrections Response
PBQ Probation Inquiry
PBR Probation Response
PCQ Corrections Inquiry
PCR Corrections Response
PDR Parsed Driver License Response
PPQ Parole Inquiry
PPR Parole Response
PRR Parsed Vehicle Registration
PCQ Railroad Crossing Inquiry
PCR Railroad Crossing Response
RNQ Vehicle Registration by Name Only
RNR Vehicle Registration Response from Name Only Inquiry
RQ Registration Inquiry
RQG Registration Inquiry by Region
RR Registration Response
SM Service Message
SON Sex Offender Notification
SOQ Sex Offender Registration Inquiry
SOR Sex Offender Registration Response
SQ Snowmobile Registration Inquiry
SR Snowmobile Registration Response
SWQ State Warrant Query
SWR State Warrant Response
TA ORION Add Transaction
TD ORION Delete Transaction
TQ ORION Inquiry
TR ORION Response
TSQ Taser Inquiry
TSR Taser Response
TU ORION Update Transaction
WLQ Wildlife File Inquiry
WLR Wildlife file Response
YQ Hit Confirmation Inquiry
YR Hit Confirmation Response

National Drug Pointer Index System (NDPIX) Message Keys

MKE Description
DEA Response from NDPIX Resulting from Entry to
DEX Enter NDPIX Record
DRR Response from NDPIX Resulting from Renewal of
DRX Renew Record in NDPIX
DTR Response from NDPIX Resulting from Request for On-line Report]
(*This MKE has been Decommissioned)
DTX Request to NDPIX for On-line Report
(*This MKE has been Decommissioned)
DUA Response from NDPIX Resulting from Update to
DUX Update to Existing NDPIX Record

National Insurance Crime Bureau (NICB) Message Keys

MKE Description
NAQ Inquiry of All NICB Files
NAR Response to Inquiry of NCIB Files
NCA Acknowledgment for Impound Record Cancel
NCI Cancel Impound Record
NEA Acknowledgment for Impound Record Entry
NEI Enter Impound Record
NIQ Inquiry of Impound/Export File Only
NIR Response to Inquiry of Impound/Export File Only
NUA Acknowledgment for Impound Record Update
NUI Update Impound Record

Canadian Message Keys

MKE Description
AM Administrative Message
CAQ Canadian Stolen Article Inquiry
CAR Canadian Stolen Article Response
CBQ Canadian Stolen Boat/Motor Inquiry
CBR Canadian Stolen Boat/Motor Response
CGQ Canadian Stolen Gun Inquiry
CGR Canadian Stolen Gun Response
CSQ Canadian Stolen Securities Inquiry
CSR Canadian Stolen Securities Response
FQ Canadian Criminal History Full Record Inquiry
FR Canadian Criminal History Full Record Response
IQ Canadian Criminal History Name Index Inquiry
IR Canadian Criminal History Name Index Response
UQ Canadian Driver License Inquiry
UR Canadian Driver License Response
VQ Canadian Stolen Vehicle Inquiry
VR Canadian Stolen Vehicle Response
WQ Canadian Wanted Person Inquiry
WR Canadian Wanted Person Response
XQ Canadian Vehicle Registration Inquiry
XR Canadian Vehicle Registration Response

Interpol Message Keys

MKE Description
FGQ Interpol Gun Query Full Report
FGR Interpol Gun Response Full Report
FPQ Interpol Wanted Person Query Full Report
FPR Interpol Wanted Person Response Full Report
FTQ Interpol Stolen Travel Document Query Full Report
FTR Interpol Stolen Travel Document Response Full Report
FVQ Interpol Stolen Vehicle Query Full Report
FVR Interpol Stolen Vehicle Response Full Report
IGQ Interpol Gun Query
IGR Interpol Gun Response
IPQ Interpol Wanted Person Query
IPR Interpol Wanted Person Response
ITQ Interpol Stolen Travel Document Query
ITR Interpol Stolen Travel Document Response
IVQ Interpol Stolen Vehicle Query
IVR Interpol Stolen Vehicle Response

Inquiry Data Elements

In most cases, rules for data elements and codes used for Nlets transactions conform to NCIC standards. In some cases members may not initially conform to all NCIC data codes in responses to queries (i.e., vehicle make/model). Non-conforming codes are acceptable within responses as long as they are clearly understandable.

The Nlets user should reference Part II of the NCIC Operating Manual for codes and detailed instructions.

ORI Usage

All messages are transmitted over Nlets using an Originating Agency Identifier (ORI). There are two general types of ORIs authorized for use on Nlets:

  • Nlets ORIs
  • NCIC ORIs

Nlets ORIs

There are four types of Nlets ORIs: Generic, Line, File and Nlets Approved 'S'. Each type is described below.

Generic ORIs

Generic ORIs are standard ORIs used to send a message to a selected department or agency. They vary in the first two characters that name the state designation and sometimes the 6th, 7th, and 8th positions.

Reference Codes:
ORI Code Abbreviation: Code Description:
xx State code
aaa County code
bb Type of agency
d Open
dd Assigned by Nlets
Generic ORIs Supported by Nlets:
ORI Code: ORI Description:
xxLIC0000 Vehicle Registration Agency
xxVIN0000 Vehicle Registration Agency
xxSIR0000 State Identification Bureau
xxOLN0000 State Driver License Bureau
xxBAS0000 State Agency Handling Boats and Snowmobiles
xxBOAT000 State Agency Handling Only Boats
xxSNOW000 State Agency Handling Only Snowmobiles
xxNLETREP Nlets Representative
xxaaabbcH ORI assigned to agency authorized to access hazardous material file only
xxaaabbdS ORI assigned by Nlets
Line ORIs

Line ORIs are used to designate a Principal (State), Federal, Associate or International member.

State two-character codes have been assigned for many years (i.e., NY = New York, IN = Indiana, etc.). Federal 2-character codes are a creation of Nlets to allow the system to uniquely identify each member. Examples of this include FB (FBI/NCIC), TC (Treasury Enforcement Communications System or TECS), DN (Naval Investigative Service), etc.

A complete list of line ORIs follows later in this section. Future line ORIs will be assigned by Nlets Staff as new members are approved by the Board of Directors.

File ORIs

ORIs created by Nlets are used to access or perform some action on the Nlets 'HELP' files, the ORION Directory, or other files supported on Nlets.

Nlets Approved "S" ORIs

The "S" ORIs have been approved by Nlets and are authorized for Administrative and DMV messages only, assigned to specific agencies that are not assigned an NCIC ORI. They have an Nlets assigned character designating the type of agency or organization in the 8th position and an "S" in the 9th position designating that the ORI has been assigned by Nlets. The characters allowed in the 8th position are:

Agency 8th Character in ORI
Child Support Enforcement Agency C
Vehicle Enforcement Agency V
Agencies in neither of the two categories named above M
Note: Do not confuse this with the "S" in the 8th character which is a convention
used to identify federal terminals off state systems.
NCIC ORIs

NCIC ORIs must be assigned by NCIC and must meet NCIC standards as detailed in the NCIC Operating Manual.

Rules for Using ORIs

The following rules apply when using ORIs:

  • Sending ORI must be a nine-character code.
  • Destination ORI may be a 2 or 9 character code.
  • Some formatted inquiries may be sent to a maximum of five ORIs. Consult the section on the specific inquiry for restrictions.
  • Most formatted inquiries may not be sent APB.
  • If a two-character ORI is used, Nlets always directs the message to a control terminal.
  • Nlets uses the entire nine characters for routing purposes.
  • The 3rd, 4th, and 5th characters identify the county or, for Federal ORIs, the agency. Nlets uses these three characters for special routing to Federal systems on Nlets. Nlets uses the 8th character of the ORI to route messages to Federal agencies that have acquired terminals on State or other Federal networks and are accessing Nlets through these networks.

The two character line codes are listed below with the member they identify.

Description Code
Air Force OSI AI
Alabama AL
Alaska AK
Alberta, Canada (AB) AB
American Samoa AM
Arizona AZ
Arkansas AR
ATF National Tracing Center AT
British Columbia, Canada BC
California CA
Canada CN
Coast Guard CG
Colorado CO
Connecticut CT
Delaware DE
Department of Interior DI
Department of State DS
Department of State (diplomatic plates only) US
Department of Justice DJ
District of Columbia (MPD only) DC
El Paso Intelligence Center EP
FBI/NCIC FB
FBI/Identification FI
Florida FL
FMCSA FM
Georgia GA
Government Services Administration GS
Guam GM
Hawaii HI
Idaho ID
IFTA FT
Illinois IL
INS's Law Enforcement Support Center AX
International Fuel Tax System FT
Interpol IP
Iowa IA
Kansas KS
Kentucky KY
License Plate Reader (Customs & NVS) LP
Louisiana LA
LoJack LJ
Maine ME
Manitoba, Canada MB
Maryland MD
Massachusetts MA
Mexico MX
Michigan MI
Minnesota MN
Mississippi MS
Missouri MO
Montana MT
National Insurance Crime Bureau NA
National Drug Pointer Index System DX
Naval Investigative Service DN
Nebraska NB
Nevada NV
New York NY
New Brunswick, Canada NK
New Mexico NM
New Jersey NJ
New Hampshire NH
Newfoundland, Canada NF
Nlets Headquarters NX
Nlets Control Center NL
North Dakota ND
North Carolina NC
Northwest Territory, Canada NT
Nova Scotia, Canada NS
Nunavut, Canada NU
NVS VS
Ohio OH
Oklahoma OK
Ontario, Canada ON
Oregon OR
ORION Data Base OD
ORION Foreign File FN
Pennsylvania PA
Postal Inspection Service PS
Prince Edward Island, Canada PE
Puerto Rico PR
Quebec, Canada PQ
Rhode Island RI
Saskatchewan, Canada SN
Secret Service SS
South Dakota SD
South Carolina SC
TECS/FAA File FA
TECS, U.S. Customs TC
Tennessee TN
Texas TX
TML-CDLIS CL
U.S. Marshals' Service MR
Utah UT
Vermont VT
Virgin Islands VI
Virginia VA
Washington WA
West Virginia WV
Wisconsin WI
Wyoming WY
Yukon Territory YT

To send a broadcast message to all stations under any of the Federal agencies listed above, address the message to the accompanying two character line code (i.e., for a message to the FBI/NCIC use 'FB').

Assignment of Nlets Approved ORIs

  • Any agency wishing to access Nlets must first apply through their state's NCIC CTO for an ORI from NCIC unless NCIC has specifically prohibited such agencies from obtaining an ORI.
  • Assignment of an ORI by NCIC, coupled with approval by the Nlets Board of Directors, will allow an agency access to Nlets.
  • If the agency is rejected by or otherwise is unacceptable to NCIC, the Nlets representative may submit a request for authorization to access Nlets. The agency may NOT access criminal history information.
  • The Nlets Board of Directors will determine whether the agency meets access criteria.
  • If they are approved, the Nlets member agency providing access to the new ORI must assure that the new ORI is added to ORION and must include, in the remarks field, a description of the function and responsibility.
  • The structure of the ORI must conform to current NCIC structure. In addition the ORI must have either an "S" or an "H" in the 9th position and the 8th position will be assigned by Nlets.

ORI Validation and Certification

The objective of this enhancement to validate ORIs (addresses) through Nlets is to assure that:

  • Only authorized users are using the network.
  • Authorized users are using the network for authorized purposes.

Four subsections follow:

  • Scope of Edit: This section describes those message types that will be validated. Those that are not validated are generated by computers and there is little to be gained by validation.
  • Update Procedures: This section defines the criteria for entry, modification and canceling of records onto ORION and onto the validation table.
  • Validation Processing: The third section describes the method of comparison used to accept or reject ORIs accessing the network.
  • Certification Procedures: The fourth describes the requirement that must be followed by the user to assure that the ORION (and thus the authorization table) is kept up to date.

Scope of Edit

Not every ORI that passes through Nlets will be validated. For example, responses resulting from vehicle registration inquiries will not be validated since the destination (originally the inquirer) was validated in the inquiry and the sender (the DMV) is a computer.

ORION Update Procedures

The following procedures dictate how the ORION file will be maintained to assure its accuracy.

Entry

Only Nlets and NCIC approved ORIs may be entered on ORION. Editing for sending messages will also apply for file entry onto ORION. For example, Arizona may not enter an Illinois ORI.

Only terminals authorized by the member CTO may add entries to ORION. The "add/cancel" authorization flag will be manipulated only by the Nlets System Agency (NSA) ORI.

After an ORI is created, they will be checked against the NCIC's ZO file to determine whether they are on NCIC. If not, they must have been approved by the Board of Directors.

Modification

It is the responsibility of the CTO to control who may modify records that are owned by that member.

The exceptions are the "criminal history access" flag, the "add/cancel" flag and the "active/inactive" flag. Only the NSA may modify these flags.

Validation Processing

Every ORI that passes through the Nlets system must meet one of the following criteria:

  • If it is a law enforcement ORI the first seven characters must match the first seven characters of an entry on ORION.
  • If it is an Nlets authorized ORI, it must meet Nlets ORI criteria.
  • If it is a criminal justice ORI it must match a nine-character entry on ORION.
  • Generic ORIs will be edited according to current Nlets definition.
  • There will also be editing based on the message type. Only ORIs flagged as authorized to access criminal record information will be allowed to send/receive IQ/IR, FQ/FR, AQ/AR and other message types reserved for law enforcement use only.

Certification Procedures

It is the responsibility of the Nlets representative to assure that all ORION entries owned by that user (state, federal, and/or associate) have been certified as up to date and accurate at least every two years. These dates will coincide with NCIC's validation of their ZO file.

Every two years a printed listing or other form of storage media containing all ORIs will be mailed to the Nlets representative. The CTO will certify that all records are valid, accurate, and up to date. The CTO will sign a certification document attesting to the validity of each record owned by the member.

Nlets Staff will cause the certification date in each record to be updated to reflect the successful completion of the certification procedure. Users will have 90 days to certify their ORIs.

Following the 90-day certification period, Nlets will notify the members, return receipt requested, that their ORIs have not been certified and their ORIs will be deactivated in 30 days unless certified. If, after thirty days from the time the member has received the second notice, the ORIs have still not been certified, they will be deactivated.

Message Length

Nlets will accept any length Nlets-formatted text messages.

Data Types

Nlets dictates the type of data that may be included in many message fields. Some fields are required to have particular code-based values or specifically formatted data (such as names and dates). Occasionally a field may be specified to have numeric only content, and otherwise it will be indicated as alphanumeric. Alphanumeric fields may contain letters, numbers and some special characters, although the use of special characters in alphanumeric fields are not recommended unless necessary as part of a unique identifier, or in free-form comments or remarks fields. If a special character, such as an ampersand (&) is to be sent in an XML message, the data must be properly enclosed in a CDATA tag such as to keep the XML well-formed.

IMQ/Image Requests

Nlets will support the exchange of images. Several inquiry formats include an optional image request (IMQ/ or its XML equivalent). When this field is included in the inquiry with a "Y" or true as a value, the receiver should return an image if one is available.

Nlets accepts this optional image request field in any inquiry where it is valid from any member.

Each member may opt to receive the image request field in any inquiry where it is valid, or to have Nlets delete the field before forwarding the inquiry. This authorization flag is turned on by request to the Nlets Control Center.

States that cannot receive images, for whatever reason, should not send the image request field to Nlets.

Initially all members will be flagged to NOT receive the field and Nlets will eliminate the field from inquiries sent to that member unless Nlets is notified otherwise.

Top

GJXDM (DEPRECATED)

GJXDM has been deprecated. Please contact Nlets for additional assistance with GJXDM.

Top

NIEM

NIEM Message Structure

This section defines message formats and includes examples for NIEM Nlets transactions.

Note: This section should be read and thoroughly understood before using the system.

NIEM Message Structure

All Nlets NIEM messages contain the root element <n2:NLETS>. The root element must contain a version attribute indicating that the XML being sent is based on this 4.00 version (n2:version="4.00"). Nlets messages must contain the Nlets namespace (http://www.nlets.org/niem/1.0) and the prefix "n2" is preferred. The Nlets NIEM specifications are compliant with the National Information Exchange Model (NIEM) and as such, import the NIEM namespaces and are written in accordance with the NIEM naming conventions (where are, themselves ISO-11179 compliant). Any namespaces used in an XML message transaction, including the NIEM namespace(s) must also be included and consistent with the accompanying documentation.

As noted above, the Nlets XML Message specifications utilize the NIEM. Further detail on the NIEM is available at (http://www.niem.gov). Unless otherwise noted in more specificity, when NIEM elements are used within the Nlets XML specifications, their definitions are to be taken from the NIEM. Any elements needing more specific definitions will be detailed in the written documentation that is a part of this appendix.

The Nlets root element contains two basic parts:

  • the Nlets header section (contained in a Message Header element) and
  • the body section.

Inside the <n2:NLETS> element node there must be exactly one occurrence of a n2:NLETSMessageHeader element node, as well as exactly one primary content node.

The primary content node must be one of the following:
    <n2:NLETSMailData>
    <n2:NLETSInquiryData>
    <n2:NLETSUpdateData>
    <n2:NLETSResponseData>

When a response message is being sent, in addition to the primary content node of n2:NLETSResponseData, the original inquiry data may be sent for reference within the n2:NLETSInquiryData.

These four nodes represent the four possible types of information currently transmitted in an Nlets transaction. New nodes may be introduced as appropriate in the future.

The data nodes must contain at least one child node. If the text of the message can be parsed then the children nodes will represent data contained in the text of the transaction. However, if the text cannot be parsed, then at least a Text node (i.e., <n2:ResponseText>) will occur that shall contain the unparsed text.

The documentation herein describes the format for each Nlets message transaction. Each section includes specific business data about the transaction set, along with a detailed Element Dictionary. The Element Dictionary in each section describes those elements within the Nlets Data section. That is, all messages will be based on a standard XML message structure and those elements specific to a transaction (falling underneath NLETSInquiryData, NLETSResponseData, NLETSMailData or NLETSUpdateData elements) are detailed.

NIEM Start of Message

To begin a message, create an <n2:NLETS> element.

After the Nlets message header and Nlets body sections are inserted, close the message with the closing of the </n2:NLETS> element.

The table below explains the opening and closing of the NIEM message.

Elements Explanation
<n2:NLETS> Opening the <n2:NLETS> element indicates the beginning of the Nlets message.
</n2:NLETS> Closing the <n2:NLETS> element indicates the end of the Nlets message.
NIEM Message Header Formats and Examples

The message type (broadcast, request, etc.) and body of message follow after the end of the header section Header.

The table below lists and explains the XML elements comprising the XML Message Header for input and output messages:

Entry Size Explanation
<n2:NLETSMessageHeader> N/A Opening the Header element indicates the
beginning of the Nlets message header.
<nh2: UserID> 20 Optional User ID number.
<nh2:UserPasswordText> 20 Optional Password.
<nh2:MessageKeyCodeText /> 4 Mandatory element containing the message key.
<nh2:DocumentControlFieldText /> 10 Optional element containing 10 characters.
<nh2:OriginatingORIID /> 9
 The <nh2:OriginatingORIID> element
 containing the 9 character sender ORI. 
 The element can only appear one time.
<nh2:DestinationORIID /> 9
 The <nh2:DestinationORIID> element
 contains the 9-character destination
 agency ORI or the 2-character destination
 code (state or region code). 
 This element may appear up to five times
 depending on message type.
<nh2:ExtendedControlFieldText />  
 Optional element containing additional
 special routing or identification data that
 may be returned when supported by the
 responding agency.
</n2:NLETSMessageHeader> N/A Closing the Header element indicates the end for the Nlets message header.

Example 1: NIEM Header for Input Messages

Input Message Header:
  <n2:NLETSMessageHeader>
    <nh2:MessageKeyCodeText>AVQ</nh2:MessageKeyCodeText>
    <nh2:OriginatingORIID>GA1234567</nh2:OriginatingORIID>
    <nh2:DestinationORIID>VA</nh2:DestinationORIID>
    <nh2:DocumentControlFieldText>String</nh2:DocumentControlFieldText>
    <nh2:ExtendedControlFieldText>String</nh2:ExtendedControlFieldText>
    <nh2:UserID>USER55</nh2:UserID>
    <nh2:UserPasswordText>password</nh2:UserPasswordText>
  </n2:NLETSMessageHeader>

The XML format for output message headers:

Entry Size Explanation
<n2:NLETSMessageHeader> N/A Opening the Header element indicates the beginning of the Nlets message header.
<nh2: UserID> 20 Optional User ID number.
<nh2:UserPasswordText> 20 Optional Password.
<nh2:MessageKeyCodeText /> 4 Mandatory element containing the message key.
<nh2:DocumentControlFieldText /> 10 Optional element containing 10 characters.
<nh2:OriginatingORIID /> 9
 The <nh2:OriginatingORIID> element containing the 9 character sender ORI.
 The element can only appear one time.
<nh2:DestinationORIID /> 9
 The <nh2:DestinationORIID> element
 contains the 9-character destination agency
 ORI or the 2-character destination code
 (state or region code). 
 This element may appear up to five times
 depending on message type.
<nh2:ExtendedControlFieldText />  
 Optional element containing additional special
 routing or identification data that may be
 returned when supported by the responding
 agency.
<nh2:MessageReceiveDate />   Contains date the message was received by Nlets in the format YYYY-MM-DD.
<nh2:MessageReceiveTime />   Contains the time the message was received by Nlets on 24-hour clock in the form hh:mm.
<nh2:MessageSendDate />   Date the message was delivered by Nlets in the format YYYY-MM-DD.
<nh2:MessageSendTime />   Time the message was delivered by Nlets on a 24 hour clock in the form hh:mm.
<nh2:ReceiveMessageNumeric />   Contains the number of messages received today.
<nh2:SendMessageNumeric />   The number of messages delivered to this line today.
</n2:NLETSMessageHeader> N/A Closing the Header element indicates the end for the Nlets message header.

Example 2: NIEM Header for Output Messages with optional control field element.

Output Message Header:
  <n2:NLETSMessageHeader>
    <nh2:MessageKeyCodeText>AVQ</nh2:MessageKeyCodeText>
    <nh2:OriginatingORIID>GA1234567</nh2:OriginatingORIID>
    <nh2:DestinationORIID>VA</nh2:DestinationORIID>
    <nh2:DocumentControlFieldText>String</nh2:DocumentControlFieldText>
    <nh2:ExtendedControlFieldText>String</nh2:ExtendedControlFieldText>
    <nh2:MessageReceiveDate>2011-08-13</nh2:MessageReceiveDate>
    <nh2:MessageReceiveTime>14:20:00</nh2:MessageReceiveTime>
    <nh2:MessageSendDate>2011-08-13</nh2:MessageSendDate>
    <nh2:MessageSendTime>14:20:00</nh2:MessageSendTime>
    <nh2:ReceiveMessageNumeric>00001</nh2:ReceiveMessageNumeric>
    <nh2:SendMessageNumeric>00001</nh2:SendMessageNumeric>
    <nh2:UserID>USER55</nh2:UserID>
    <nh2:UserPasswordText>password</nh2:UserPasswordText>
  </n2:NLETSMessageHeader>
NIEM Message Identification

All NIEM messages will include an Nlets message code as an element in the Header. The message type is a two to four character variable length field.

For example, a person inquiry may be one of several message types.

The following example illustrates one message type for a person search, "AQ".

    <n2:MessageKeyCodeText>AQ</n2:MessageKeyCodeText>

NIEM Multiple Destination Message Specifications

To send a message to more than one agency, enter multiple ORIs or region codes.

A message may be sent to a maximum of five locations.

Each terminal designated as a destination in the input message receives a message with a single ORI. In Administrative Messages the other destinations that received the message will be included in the text of the message directly after the text and in parentheses.

NIEM Field Delimiters

All predefined fields in the message header or in the text of inquiry messages are encapsulated in tags. See the example below.

    <nh2:OriginatingORIID>GA1234567</nh2:OriginatingORIID>

NIEM Control Field

The Control Field is a special field provided to convey special routing or identification data that the sending agency must have returned in order to match a response to an earlier message.

The control field is always 10 characters in length. The control field can have leading and trailing spaces. Additionally, a control field can have spaces in the middle of it. Since the same control field must always be returned on a response, it can be difficult for terminal operators of manual messages to count the spaces within a control field to return it exactly. Nlets recommends not using spaces within the control field; however, spaces are legal and are used by several agencies.

Computerized states must make provisions for automatically saving and returning the control field on all inquiries that are handled on an automatic basis. Whenever a user terminal (Nlets or within a state) sees the "control field" on an incoming message, that terminal must insure that the same "control field" is sent with all messages prepared in response.

When used, the control field must follow these rules:

  • 10 characters fixed length
  • Imbedded blanks are acceptable
  • Nlets recommends the usage of only alphabetic and numeric characters; however, the dash (-), ampersand (&), left parenthesis [(], right parenthesis [)], quotation marks ("), dollar sign ($), slash (/), colon (:), semi-colon (;), plus sign (+), underscore (_), space ( ) and comma (,) are allowed.
  • Nlets requires that if an illegal XML character such as "&" is used in the control field that it be enclosed in a <![CDATA[]]> tag.
  • Users are advised that, if they do not follow the above restrictions, they run the risk of not having the control field returned, or returned improperly, since the destination may not be able to send and/or receive characters other than those listed above.
Note: On inquiries to Canada the control field follows the above rules but may not contain a slash (/) or a colon (:).

Example of control field entry:

<n2:DocumentControlFieldText><![CDATA[123(567&90]]></n2:DocumentControlFieldText>
NIEM Message Caveats

An Nlets message may contain one or many caveats. These may be inserted by the switch or by the originating agency. These caveats are part of the message text and will appear as the first line inside of a <!CDATA[]]> element in non-standardized message formats. In the case of standardized message types, any caveat will be contained within an element <j:CaveatText> underneath the data element (n2:NLETSMailData, n2:NLETSUpdateData, n2:NLETSInquiryData, n2:NLETSResponseData).

NIEM Examples Explained

The XML will take on four different possible formats. The first is the originating query from the sender, without a timestamp. After the sender's original query passes through the Nlets switch, it is given a timestamp. A response is sent by the recipient, without a timestamp. Again, as the message passes through the Nlets switch, it is given a timestamp.


XML.jpg

The format for data elements and inquiries closely follows NCIC and/or other nationally adopted standards.

Top

Legacy (DEPRECATED)

Message Structure > Legacy Formats and Examples

This section defines message formats and includes examples for Legacy transactions.

Legacy Message Formats and Examples

Legacy Start of Message

All Legacy Nlets messages must be prefixed by a message type code. Legacy standard message header formats and examples are described in the sections below.

Legacy Message Header Formats and Examples

Control characters (i.e. carriage return, line feed, delete, etc.) may be used in the header. They will be ignored during the processing of the header.

The format for input messages:

Entry #Char. Explanation
Msg. Type 2-3 2-3 character identifier for the type of message followed by a period.
Sender ORI 9 9 character sender ORI followed by a period.
Destination ORI 2-9

From one to five destination ORIs; each ORI will be either 2
or 9 characters. When more than one ORI is included, they
will be separated by a comma. The final destination will end
with a period.

* 1 Asterisk to identify the start of the Control Field (omit if no
Control Field is used).
Control Field 10 Optional 10 character control field ending with a period.
Text Varies Message Text. Must begin with a TXT.

The format for output messages:

Entry #Char. Explanation
Msg. Type 2-3 2-3 character identifier for the type of message followed by a period.
Sender ORI 9 9 character sender ORI.
CR/LF/DEL 3 Carriage return, line feed and delete control characters.
In Time 5 Time message was received by Nlets on 24-hour clock in
the form hh:mm.
  1 Space to separate fields
In Date 8 or 10 Date message received by Nlets in form mm/dd/yy or
mm/dd/ccyy.
  1 Space to separate fields
In Seq # 5 Identifies the number of messages from the sending line
today.
CR/LF/DEL 3 Carriage return, line feed, delete control characters.
Out Time 5 Time message was delivered by Nlets on a 24 hour clock in
the form hh:mm.
  1 Space to separate fields
Out Date 8 or 10 Date message is delivered in the form mm/dd/yy or
mm/dd/ccyy.
  1 Space to separate fields
Out Seq # 5 Identifies the number of messages delivered to this line
today.
  1 Space to separate fields
Destination ORI 2 or 9 Either a 2 or 9 character ORI, only one per message.
CR/LF/DEL 3 Carriage return, line feed, delete control characters.
* 1 Asterisk identifies the start of the control field (not present if
control field not in original message).
Control Field 10 Optional Control Field (not present if not in original message).
CR/LF/DEL 3 Carriage return, line feed, delete control characters (not
present in control field not in original message).
Text Varies Message Text Must begin with a TXT

Example 1: Output Message Header

Output Message Header

AM.AZ0071100
09:00 6/10/1996 00325
09:01 6/10/1996 00001 TXDPS0000

Explanation:

Line Entry Explanation
Line 1 AM.AZ0071100 Message type terminated by a period and
the ORI of agency sending the message.
Line 2 09:00 6/10/1996 00325

Time received by Nlets computer
followed by the date received.
The final number is the number of
messages received today from the input
line (AZ in this case).

Line 3 09:01 6/10/1996 00001 TXDPS0000

Time sent by Nlets computer followed by
the date sent.
The final number is the number of
messages sent today to the addressed line
(TX) followed by the agency addressed in
the message (receiving ORI).

Legacy Field Delimiters

All predefined fields in the message header or in the text of inquiry messages end with a period.

Exception: The last field in an inquiry or response is not followed by a period (according to NCIC message standards).

Legacy Control Field

The control field in legacy transaction messages is always prefixed by an asterisk (*) and is always 10 characters in length. The control field can have leading and trailing spaces. Additionally, a control field can have spaces in the middle of it. Since the same control field must always be returned on a response, it can be difficult for terminal operators of manual messages to count the spaces within a control field to return it exactly. Nlets recommends not using spaces within the control field; however, spaces are legal and are used by several agencies.

Computerized states must make provisions for automatically saving and returning the control field on all inquiries that are handled on an automatic basis. Whenever a user terminal (Nlets or within a state) sees the "* control field" on an incoming message, that terminal must insure that the same "* control field" is sent with all messages prepared in response.

When used, the control field must follow these rules:

  • Prefixed by an asterisk (*)
  • 10 characters fixed length
  • Followed by a period (.)

Nlets recommends the usage of only alphabetic and numeric characters; however, the dash (-), ampersand (&), left parenthesis [(], right parenthesis [)], quotation marks ("), dollar sign ($), slash (/), colon (:), semi-colon (;), plus sign (+), underscore (_), space ( ) and comma (,) are allowed.

Users are advised that, if they do not follow the above restrictions, they run the risk of not having the control field returned, or returned improperly, since the destination may not be able to send and/or receive characters other than those listed above.

Note: On inquiries to Canada the control field follows the above rules but may not contain a
slash (/) or a colon (:) or a semicolon (;) and the first four characters cannot be 'CQCU'.

Legacy Text Identifier

A special set of three characters (TXT) is used to denote the beginning of the text field or the beginning of the inquiry data elements for all Nlets messages.

  • The Nlets computer processes the standard header (including the control field) and then scans the message looking for the TXT.
  • No data is processed after the header until the TXT characters are encountered.
  • If TXT is not encountered within the first 3 characters following the header, the message is rejected.

Legacy General Format

The prescribed text of administrative messages follows the conventions documented in the APCO Standard Operating Procedures Manual. The following illustrates the general APCO format:

Example 2: Administrative Message

Administrative Message

AM.FL0130000.AZ
TXT
15 DPS DADE COUNTY FL 6/10/1988
DPS STATE OF AZ
REF 482 ELDON MOORE
SUBJECT MOORE CHECKED OUT OF MOTEL
ON 10/29/90 WHEREABOUTS UNKNOWN
DPS DADE COUNTY FL ARCH 0945 EST

Explanation of Administrative Message:

Line Entry Explanation
Line 1 AM.FL0130000.AZ Nlets header
Line 2 TXT Text identifier
Line 3 15 DPS DADE COUNTY FL 6/10/88 Message number, originator, and
date transmitted
Line 4 DPS STATE OF AZ Destination
Line 5 REF 482 11/01/1990 ELDON MOORE Reference number, reference date,
and subject of reference
Line 6 SUBJECT MOORE CHECKED OUT OF MOTEL Body of message
Line 7 ON 10/29/1990 WHEREABOUTS UNKNOWN Body of message
Line 8 DPS DADE COUNTY FL ARCH 0945 EST Sending authority,
operator/dispatcher, time

The format for data elements and inquiries closely follows NCIC and/or other nationally adopted standards.


Top