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 citations(s), accident record(s), administrative action(s) and status change(s). The system, called Driver Monitoring Service (DMS), will replace the existing monthly bulk data file, previously known as the pointer 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
XML	eXtended Markup Language
XSD	XML Schema Definition
ALEA	Alabama Law Enforcement Agency

Usage Requirements

The DMS is developed as a SOAP web service. Customers will have the option to make requests to: add records to be monitored, list records being monitored, remove a record from monitoring, list monitoring results and request monitoring details for a specific record.

New Requests

New monitoring requests can be submitted with a start date up to 12 months in the past, which will trigger a "hit" if any of the requested triggers are true from the provided start date to the end of the current monitoring month. A look back type request would typically be used as a one time history check for a new customer. To get monthly status information on a monitored record going forward you would submit your monitoring request with an end date up to 12 months in the future. This will provide you with a monthly update for each of the months included in your start to end date range.

Costs

Your customer account will be billed per monitoring request per the following fee schedule.

Monitoring Request Type	Cost Per Request	Description	Example
Look back monitoring	$0.12	Any portion of the start to end monitoring date period which is prior to the end of the month in which monitoring is originally requested.	Has there been any changes to this record in the past six months? A record is requested to be added to monitoring in September with a monitoring start date of April and an end date of September. This request will look for any of the requested triggers in all six of those months as a single collective check. The monitoring result for this record will be provided to the customer at the beginning of October.
Look forward monitoring	$0.12 / per month	Any portion of the start to end monitoring date period which is after the end of the month in which monitoring is originally requested will be charged the per request rate for each month.	Let me know if there are any changes to this record over the next three months. A record is requested to be added to monitoring in September with a monitoring start date of October and an end date of December. Each future month being monitored will be split into a unique monitoring request. This request will look for any of the requested triggers in each of the three months individually as they pass. The monitoring result for this record will be provided to the customer in November, December and January for October, November and December respectively. Your account will be billed at the per request rate in each of the three months being monitored.
Dual span monitoring	$0.12 for look back + $0.12 / per future month	Any portion of the start to end monitoring date period which is prior to the end of the month in which monitoring is originally requested will be charged once at the per request rate. Any portion of the start to end monitoring date period which is after the end of the month in which monitoring is originally requested will be charged the per request rate for each month.	Has there been any changes to this record in the past twelve months and let me know if there are any changes to this record over the next twelve months. A record is requested to be added to monitoring in September with a monitoring start date of October of the previous year and an end date of September of the following year. A request which spans both past and future months will be split into two groups of requests; a look back request spanning from the monitoring start date to the end of the month the request was received in and a future request, which will be split into a unique monitoring request per future month being monitored. The monitoring result for this record will be provided to the customer at the beginning of October, to cover from the previous October until the end of September of the current year, as well as in each of the next twelve months for the future months being monitored. Your account will be billed once in September for the entirety of the look back request and then once in each of the twelve look forward months.

Connection Strings

Environment	URL	Purpose
UAT	https://test.alabamainteractive.org/mvr_search/MonitoringWS.jws?wsdl	This is the WSDL, which defines the SOAP service and its available methods
UAT	https://test.alabamainteractive.org/mvr_search/MonitoringWS.jws	This is the web service end-point and is where you will direct your requests
Production	https://www.alabamainteractive.org/mvr_search/MonitoringWS.jws?wsdl	This is the WSDL, which defines the SOAP service and its available methods
Production	https://www.alabamainteractive.org/mvr_search/MonitoringWS.jws	This is the web service end-point and is where you will direct your requests

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