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 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 |
| HIT | Has Initiated Trigger |
| 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" 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. |
| 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. |
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
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.
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
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.
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.
Web Service Method Definitions
submitDriverMonitoringRequest
This is the method used to add new driver monitoring requests to your account.
Request
| Field | Required | Data Type | Format | Notes |
|---|---|---|---|---|
| username | Yes | String | The username in your customer account approved to request driver monitoring | |
| password | Yes | String | The password associated with the provided username | |
| dlNumber | Yes | String | 7 or 8 digits "I" + 6 or 7 digits "ID" + 5 or 6 digits | The driver license number to be monitored |
| monitorStartDate | Yes | String | yyyymm |
|
| monitorEndDate | Yes | String | yyyymm |
|
| customerReferenceId | No | String | This is an optional, but recommended field and should contain a unique identifier to tie this request back to the customers system | |
| citationAdded | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new citation is added to a record |
| citationRemoved | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation is removed from a record |
| accidentAdded | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new accident is added to a record |
| accidentRemoved | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a accident is removed from a record |
| withdrawalAdded | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record |
| withdrawalRemoved | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record |
| reinstated | Yes | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a license is reinstated |
Response
| Field | Data Type | Format | Notes |
|---|---|---|---|
Possible Error Messages
| Reason | Error Message |
|---|---|
| Invalid Login | Invalid login for <username> |
| Invalid or no DPPA for user | Valid login for <username>, but DPPA Number is not valid. |
| User does not have any access permissions | Valid login for <username>, but login access group list is empty. |
| User does not have permission to access this service | Valid login for <username>, but DPS_MVR_PTP_WS access group may not be present. |
| Access not grated to UAT environment | Access to the test web service is only available for testing purposes. |
viewDriverMonitoringRequests
This method allows you to view the list of all pending driver monitoring requests within a given month. Note that only pending non-completed monitoring requests can be viewed from this method. To view completed monitoring results, see the viewDriverMonitoringResults method.
removeDriverMonitoringRequest
Use this method to remove a monitoring request. Note that only pending non-completed monitoring requests can be removed.
viewDriverMonitoringResults
| Anchor | ||||
|---|---|---|---|---|
|
This method allows you to view the list of all completed driver monitoring requests for a given month. This method will list all of the details of the original monitoring request including the triggers requested as well a true/false value indicating which trigger(s) caused a record HIT, if any. A single "recordHasHit" boolean value will also be sent for simplicity.
viewDriverMonitoringRecord
This method will be used to request the full DHR for each record indicated as having a HIT in the viewDriverMonitoringResults method.
© 2016 Alabama Interactive, LLC. All rights reserved.