Alabama Law Enforcement Agency
Driver Monitoring Service
Table of Contents
| Table of Contents | ||||
|---|---|---|---|---|
|
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 convictionscitations(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 | 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 SOAP web 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 monitoredhave 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 month 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...........
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
© 2016 Alabama Interactive, LLC. All rights reserved.