Table of Contents

Introduction

The Alabama Law Enforcement Agency (ALEA) in partnership with Tyler Technologies 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 provided by ALEA commonly referred to as the "Pointer File".  This  This document provides a high-level overview on of implementing and interfacing with the new standard DMS interface for the state State of Alabama.

Acronyms

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 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

Defines the XML format for the result file that will be returned to you.

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

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.

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

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 of up to 12 months in the future.  This will provide you with a monthly update for each month included in your start-to-end date range.

Costs

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

Connection Strings

Web Service Method Definitions

submitDriverMonitoringRequest

Anchor
submitDriverMonitoringRequest submitDriverMonitoringRequest

This is the method used to add new driver monitoring requests to your account.

Request

Response

Possible Error Messages

viewDriverMonitoringRequests

Anchor
viewDriverMonitoringRequests 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 68780059 method.

Request

Response

Possible Error Messages

removeDriverMonitoringRequest

Use this method to remove a monitoring request.  Note that only pending non-completed monitoring requests can be removed.

Request

Response

Possible Error Messages

viewDriverMonitoringResults

Anchor
viewDriverMonitoringResults viewDriverMonitoringResults

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.

Driver Monitoring results are processed on the 2nd day of the month at 10:30 AM central. Records will be available shortly after this time, depending on processing time. An email will be sent to customers when processing is complete and records are officially available. These results are available without expiration for reporting and reconciliation purposes. However, once the "viewDriverMonitoringRecord" method for a given record has been requested and the MVR has been delivered, that MVR is only available for seven days from the time it is first delivered.

Request

Test Request

Response

Possible Error Messages

viewDriverMonitoringRecord

This method will be used to request the full DHR for each record indicated as having a HIT in the 68780059 method. Note that once the record has been requested and the MVR has been delivered, that MVR is only available for seven days from the time it is first delivered.

Request

Test Request

Response

Possible Error Messages

Standard Authentication Error Responses

Monitoring Result Status Codes

Anchor
MonitoringResultStatusCodes MonitoringResultStatusCodes

© Tyler Technologies Alabama.  All rights reserved.