Alabama Law Enforcement Agency

Driver Monitoring Service

Introduction

The Alabama Law Enforcement Agency (ALEA) in partnership with Alabama Interactive has developed a new secure method of monitoring driver record information. This service will allow authorized customers to monitor Alabama Driver History Records (DHRs) for changes such as traffic convictions(s), administrative action(s) and status change(s). The system, called Driver Monitoring Service (DMS), will replace the existing monthly bulk data file provided by ALEA commonly referred to as the "Pointer File". This document provides a high level overview on implementing and interfacing with the new standard DMS interface for the state of Alabama.

Acronyms

DMS	Driver Monitoring Service
DHR	Driver History Record
HTTPS	Secure Hypertext Transfer Protocol
SFTP	Secure File Transfer Protocol
XML	eXtended Markup Language
XSD	XML Schema Definition
GPG	GNU Privacy Guard
ALEA	Alabama Law Enforcement Agency

Usage Requirements

The DMS is developed as a batch service. Customers will supply an encrypted request file via SFTP by the 25th of each month. The file will specify the driver's license, number of months for the monitor to look back for changes and specify a unique reference number for each driver being monitored.

This file will be processed by the service and will respond with a notification email of any issues found in the file and a payment receipt for all valid requests. By the 5th of each month, the service will generate a response file of the records requested to monitor for the given month according to look-back periods. Should any change events be identified within the monitored period, the DHR for the given individual will be purchased on behalf of the customer. All "hits" will be combined into a single response file. The response file will be encrypted and uploaded to the customers SFTP folder. A notification email will be sent once the file has been uploaded.

Access to the SFTP is restricted to customers of Alabama Interactive who have been issued a system user account. Authentication to the SFTP server will require a username and password as well as IP address validation. The username and password information is provided by Alabama Interactive. Customers are responsible for providing Alabama Interactive with up to 3 unique IP addresses to be given access to the SFTP server. IP addresses must be provided at least two weeks in advance of when connectivity is required and customers are responsible for notifying Alabama Interactive of any changes to IP addresses required to connect to the SFTP server.

Encryption and decryption using GPG will be used to exchange files securely via the STFP server. This provides an added layer of security to the file exchange. Customers can obtain the Alabama Interactive GPG Public Key using the link provided in the "Connection Strings" section later in this document. This key will be used to encrypt the response file that is sent back to you. Customers will be required to provide Alabama Interactive with their GPG Public Key, which will be used to decrypt the request file we receive from you.

Connection Strings

URL	Purpose
stfp://stfp-1.cdc.nicusa.com	Needed to connect to the DMS SFTP server. Note that there is no test environment available for this service.
https://test.alabamainteractive.org/mvr_search/dms/dmsRequest.xsd	Defines the XML format for the file used to monitor DHRs. This is the file you will provide to Alabama Interactive.
https://test.alabamainteractive.org/mvr_search/dms/dmsResponse.xsd	Defines the XML format for the result file that will be returned to you.
https://test.alabamainteractive.org/mvr_search/dms/dmsPublic.key	GPG Public Key used to encrypt the "ConvictionRequest.xml" file.

Process Steps

The following steps should be followed to request a new monitoring record.

Step #1: Generate Request File

Build the request file based on the dmsRequest.xsd specification. All monitoring requests for the given month should be included in a single request file.

Step #2: Encrypt and Upload File

Once the request is generated, the file must be encrypted using the GPG public key provided by Alabama Interactive. Once encrypted, the file should be named "ConvictionRequest.xml.pgp". The encrypted file will then be uploaded to the SFTP server in the customer's root folder.

Step #3: Receiving of Request Files

The service will review the received files to ensure they are in a valid format and that no duplicates exist. The system will define a duplicate as a record in which all three fields match. Duplicates will be ignored and the file will be processed. In the case of an invalid or missing file, the system will send an email to the technical contact. A new file will need to be supplied by the 1st of the month. Failure to provide a file by the 1st of the month will result in delayed processing.

Step #4: Processing of Pending Requests

By the 5th of the month, the service will review new requests according to their look-back period. New requests will be confirmed by matching the driver's license against an existing record. Should the record not exist, a response shall be added to the monthly return file with a status of "NOMATCHINGRECORDFOUND". The system will check each valid driver record for changes as defined in Appendix F: Hit Events. Should no Hit Event be identified, the response will be added to the monthly return file with a status of "NOCHANGESFOUND". Should a Hit Event be identified, the DHR will be pulled and normal DHR fees will be applied to your customer account. The request along with the DHR will be added to the monthly return file with a status of "CHANGESFOUND".

Once the response file is completed, it will be encrypted and named "ConvictionResponse_YYYYMM.xml.gpg", where "YYYYMM" is the year and month that the file is created. The file will be uploaded to the customers SFTP folder and an email will be sent to the technical contact.

Appendix A: Request XML Element Definitions

Element Name	Data Type	Required	Definition
dlNumber	Numeric	Yes	Driver License Number being monitored
lookBackPeriod	Numeric	Yes	A numeric value between 1 and 12, which determines the number of previous months to monitor for changes. Note: If you wish to monitor this driver license monthly, you should enter a value of "1". Typically this value will follow the frequency, in months, that you wish to monitor this driver license.
referenceId	String	No	This can be any value you wish to provide and can be used to links requests back to a unique key in your system. This value may not exceed 200 characters in length. The value provided in the request file will be returned with the corresponding record in the response file.
triggerOnCitationAdded	Boolean	Yes	If true, will cause a hit event when a citation has been added during the requested look back period.
triggerOnCitationRemoved	Boolean	Yes	If true, will cause a hit event when a citation has been removed during the requested look back period.
triggerOnAccidentAdded	Boolean	Yes	If true, will cause a hit event when an accident has been added during the requested look back period.
triggerOnAccidentRemoved	Boolean	Yes	If true, will cause a hit event when an accident has been removed during the requested look back period.
triggerOnWithdrawalAdded	Boolean	Yes	If true, will cause a hit event when a withdrawal has been added during the requested look back period.
triggerOnWithdrawalRemoved	Boolean	Yes	If true, will cause a hit event when a withdrawal has been removed during the requested look back period.
triggerOnReinstated	Boolean	Yes	If true, will cause a hit event when the license has been reinstated during the requested look back period.

Appendix B: Response File Element Definitions

For details regarding the response file element definitions, please see the Point-to-Point Web Service Integration Guide.

Appendix C: Sample Request/Response Files

Sample Request XML	https://test.alabamainteractive.org/mvr_search/dms/sampleRequest.xml
Sample Response XML	https://test.alabamainteractive.org/mvr_search/dms/sampleResponse.xml

Appendix D: Encryption Details

Encryption will be accomplished using GPG. Tools and instructions for GPG encryption and decryption are available for various operating systems and you may choose to use whatever tool works best in your environment. New customers or customers changing their GPG key must provide Alabama Interactive with their public key at least two weeks prior to needing service to ensure ample time for the necessary configuration. Customers will encrypt request files to Alabama Interactive using the public key provided by Alabama Interactive. Alabama Interactive will in turn encrypt response files sent to you using your public key, which you can then decrypt using your private key.

Appendix E: Status Code Definitions

The following table describes the Status values that will be returned in the response file.

Status Code	Definition
NOCHANGESFOUND	This record has reached its look back period and NO changes were found during the period.
CHANGESFOUND	This record has reached its look back period and changes were found during the period.
NOMATCHINGRECORDFOUND	The driver's license number is invalid or not found.
INVALIDLICENSENUMBER	The driver's license has been removed from the DMS reporting system during the look back period.
UNKNOWNERROROCCURED	An unknown error has prevented processing of this driver's license.

Appendix F: Hit Events

Each of the following events can be configured to trigger a "hit event" and result in the purchase of the corresponding DHR. The "ConvictionRequest.xml" file allows you to choose, per driver being monitored, which of the below events will trigger a record change and a DHR purchase.

Citation Added
Citation Removed
Accident Added
Accident Removed
Withdrawal Added
Withdrawal Removed
Reinstated

Driver Monitoring Service Integration Guide