Driver Monitoring Service Integration Guide



Alabama Law Enforcement Agency

Driver Monitoring Service



Table of Contents


Introduction

The Alabama Law Enforcement Agency (ALEA) in partnership with Tyler Technologies Alabama 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).  This document provides a high-level overview of implementing and interfacing with the new standard DMS interface for the State of Alabama.

Acronyms

DMSDriver Monitoring Service
DHRDriver History Record
HITHas Initiated Trigger
HTTPSSecure Hypertext Transfer Protocol
XMLeXtended Markup Language
XSDXML Schema Definition
ALEAAlabama 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 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.

Monitoring Request TypeCost Per RequestDescriptionExample
Look back monitoring$0.40 / per month Any portion of the monitored date range which is prior to the end of the current month in which monitoring is requested.Have 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.
Scheduled monitoring$0.40 / per monthScheduled monitoring for each future month individually.

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.

Connection Strings

EnvironmentURLPurpose
UAThttps://dev.alabamainteractive.org/alea-dhr-ws/MonitoringWSService?WSDLThis is the WSDL, which defines the SOAP service and its available methods
UAThttps://dev.alabamainteractive.org/alea-dhr-ws/MonitoringWSServiceThis is the web service end-point and is where you will direct your requests
Productionhttps://api.alabamainteractive.org/alea-dhr-ws/MonitoringWSService?WSDL

This is the WSDL, which defines the SOAP service and its available methods

Productionhttps://api.alabamainteractive.org/alea-dhr-ws/MonitoringWSServiceThis is the web service end-point and is where you will direct your requests

Web Service Method Definitions

submitDriverMonitoringRequest

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

Request

FieldRequiredData TypeFormatNotes
usernameYesString
The username in your customer account approved to request driver monitoring
passwordYesString
The password associated with the provided username
dlNumberYesString
  • 7 or 8 digits
  • "I" + 6 or 7 digits
  • "ID" + 5 or 6 digits
The driver license number to be monitored
monitorStartDateYesNumberyyyymm
  • 4-digit Year & 2-digit Month
  • Can be no more than 12 months in the past
  • Cannot be a future month

1Note: To correctly add monitoring for a single month, both the monitorStartDate and monitorEndDate values will be the same.

2Note: The monitoring start date includes the month provided.

monitorEndDateYesNumberyyyymm
  • 4-digit Year & 2-digit Month
  • Can be no more than 12 months in the future
  • Cannot be before the current month

1Note: To correctly add monitoring for a single month, both the monitorStartDate and monitorEndDate values will be the same.

2Note: The monitoring end date includes the month provided.

customerReferenceIdNoStringMax Length: 100This is an optional, but recommended field and should contain a unique identifier to tie this request back to the customer's system.
This value will be used to make this record unique from other requests and as part of any duplicate checking if provided.
citationAddedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new citation is added to a record
citationRemovedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a citation is removed from a record
accidentAddedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new accident is added to a record
accidentRemovedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when an accident is removed from a record
withdrawalAddedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record
withdrawalRemovedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record
reinstatedYesBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a license is reinstated

Response

FieldData TypeFormatNotes
successfulResponseBooleantrue/falseIndicates if the monitoring request was successfully added to your account
monitorIdNumber

messageString
If "successfulResponse = false", then an error message will be present.  Otherwise, this value will be blank.

Possible Error Messages

ReasonError Message
Invalid monitoring start date formatInvalid format: monitorStartDate.
Invalid monitoring end date formatInvalid format: monitorEndDate.
Invalid monitoring start dateInvalid date range: monitorStartDate. monitorStartDate must be less than or equal to <current month yyyymm>
Invalid monitoring end dateInvalid date range: monitorEndDate. MonitorEndDate must be greater than or equal to <current month yyyymm>
Invalid monitoring end dateInvalid date range: Invalid date range: monitorEndDate. MonitorEndDate is less than MonitorStartDate.
Duplicate request foundDuplicate found

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 Driver Monitoring Service Integration Guide#viewDriverMonitoringResults method.

Request

FieldRequiredData TypeFormatNotes
usernameYesString
The username in your customer account approved to request driver monitoring
passwordYesString
The password associated with the provided username
monitorMonthYesNumberyyyymm

4-digit Year & 2-digit Month

Response

FieldData TypeFormatNotes
successfulResponseBooleantrue/falseIndicates if the request returned a successful response
messageString
If "successfulResponse = false", then an error message will be present.  Otherwise, this value will be blank
monitorMonthNumberyyyymmThis will be the monitor month provided in the request
monitoringRequestsObject ListmonitoringRequest objectThis will contain a list of monitoring request object
monitoringRequests.monitoringRequestObjectmonitoringRequestThis is a specific monitoring request and includes all of the fields provided when the request was added
monitoringRequests.monitoringRequest.monitorIdNumber
This is the unique Monitoring ID for this monitored record
monitoringRequests.monitoringRequest.customerReferenceIdString
This is the value provided in the original Driver Monitoring Service Integration Guide#submitDriverMonitoringRequest
monitoringRequests.monitoringRequest.dlNumberString
The driver's license number being monitored
monitoringRequests.monitoringRequest.citationAddedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new citation is added to a record
monitoringRequests.monitoringRequest.citationRemovedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a citation is removed from a record
monitoringRequests.monitoringRequest.accidentAddedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new accident is added to a record
monitoringRequests.monitoringRequest.accidentRemovedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when an accident is removed from a record
monitoringRequests.monitoringRequest.withdrawalAddedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record
monitoringRequests.monitoringRequest.withdrawalRemovedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record
monitoringRequests.monitoringRequest.reinstatedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a license is reinstated

Possible Error Messages

ReasonError Message
Invalid monitor month formatInvalid format: monitorMonth (yyyyMM)

removeDriverMonitoringRequest

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

Request

FieldRequiredData TypeFormatNotes
usernameYesString
The username in your customer account approved to request driver monitoring
passwordYesString
The password associated with the provided username
monitorIdYesNumber
This is the unique identifier provided in the Driver Monitoring Service Integration Guide#submitDriverMonitoringRequest or Driver Monitoring Service Integration Guide#viewDriverMonitoringRequests response and must be provided to confirm you are removing the intended record from monitoring.  Note that only pending monitoring requests may be removed.  Those which have already been completed and the results provided will not be able to be removed.
dlNumberYesString
  • 7 or 8 digits
  • "I" + 6 or 7 digits
  • "ID" + 5 or 6 digits
The driver's license number you would like to remove from monitoring
customerReferenceIdNoString
If provided will be used in combination with the monitorId and dlNumber to uniquely identify and remove the requested record from monitoring.

Response

FieldData TypeFormatNotes
successfulResponseBooleantrue/falseIndicates if the request to remove the record from monitoring was successful
messageString
If "successfulResponse = false", then an error message will be present.  Otherwise, this value will be blank

Possible Error Messages

ReasonError Message
Invalid request criteriaNo records match the parameters provided
Invalid driver license formatDrivers License Number is invalid format

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

FieldRequiredData TypeFormatNotes
usernameYesString
The username in your customer account approved to request driver monitoring
passwordYesString
The password associated with the provided username
monitorMonthYesNumberyyyymm

4-digit Year & 2-digit Month

Test Request

FieldTest ValueNotes
usernameYour actual username
passwordYour actual password
monitorMonth202401You can use other value to see a response that does not have results, but 202401 is the only one that will return a list of records.  Keep in mind this is a canned list of records and will not correspond to the list you created using the submitDriverMonitoringRequest method in the test system.

Response

FieldData TypeFormatNotes
successfulResponseBooleantrue/falseIndicates if the request returned a successful response
messageString
If successfulResponse = false, then an error message will be present.  Otherwise, this value will be blank
monitorMonthNumberyyyymmThis will be the monitor month provided in the request
monitoringResultsObject ListmonitoringResult objectThis will contain a list of monitoring result object
monitoringResults.monitoringResultObjectmonitoringResultThis is a specific monitoring result and includes all of the fields provided when the request was added, as well as an indicator of whether this record triggered a HIT and individual indicators as to which event triggered the HIT
monitoringResults.monitoringResult.monitorIdNumber
This is the unique Monitoring ID for this monitored record
monitoringResults.monitoringResult.customerReferenceIdString
This is the value provided in the original Driver Monitoring Service Integration Guide#submitDriverMonitoringRequest
monitoringResults.monitoringResult.dlNumberString
The driver's license number being monitored
monitoringResults.monitoringResult.monitorStartNumberyyyymmThe start date this monitoring request applies to
monitoringResults.monitoringResult.monitorEndNumberyyyymmThe end date this monitoring request applies to
monitoringResults.monitoringResult.recordHasHitBooleantrue/falseIndicates if any of the requested triggers caused a HIT event
monitoringResults.monitoringResult.statusNumber
Indicates if a record has been processed and if so what the result is. See the list of Monitoring Results Status Codes below.
monitoringResults.monitoringResult.citationAddedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new citation is added to a record
monitoringResults.monitoringResult.citationRemovedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a citation is removed from a record
monitoringResults.monitoringResult.accidentAddedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new accident is added to a record
monitoringResults.monitoringResult.accidentRemovedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when an accident is removed from a record
monitoringResults.monitoringResult.withdrawalAddedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record
monitoringResults.monitoringResult.withdrawalRemovedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record
monitoringResults.monitoringResult.reinstatedBooleantrue/falseA value indicating if you wish to trigger monitoring hits when a license is reinstated
monitoringResults.monitoringResult.citationAddedResultBooleantrue/falseA value indicating if  a new citation is added to a record.  If you chose not to monitor based on this trigger, it will always be false
monitoringResults.monitoringResult.citationRemovedResultBooleantrue/falseA value indicating if a citation is removed from a record.  If you chose not to monitor based on this trigger, it will always be false
monitoringResults.monitoringResult.accidentAddedResultBooleantrue/falseA value indicating if a new accident is added to a record.  If you chose not to monitor based on this trigger, it will always be false
monitoringResults.monitoringResult.accidentRemovedResultBooleantrue/falseA value indicating if a accident is removed from a record.  If you chose not to monitor based on this trigger, it will always be false
monitoringResults.monitoringResult.withdrawalAddedResultBooleantrue/falseA value indicating if a new withdrawal is added to a record.  If you chose not to monitor based on this trigger, it will always be false
monitoringResults.monitoringResult.withdrawalRemovedResultBooleantrue/falseA value indicating if a withdrawal is removed from a record.  If you chose not to monitor based on this trigger, it will always be false
monitoringResults.monitoringResult.reinstatedResultBooleantrue/falseA value indicating if the license is reinstated.  If you chose not to monitor based on this trigger, it will always be false

Possible Error Messages

ReasonError Message
Invalid monitor month formatInvalid format: monitorMonth (yyyyMM)

viewDriverMonitoringRecord

This method will be used to request the full DHR for each record indicated as having a HIT in the Driver Monitoring Service Integration Guide#viewDriverMonitoringResults 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

FieldRequiredData TypeFormatNotes
usernameYesString
The username in your customer account approved to request driver monitoring
passwordYesString
The password associated with the provided username
monitorIdYesNumber

This is the unique identifier provided in the Driver Monitoring Service Integration Guide#viewDriverMonitoringResults response and must be provided to confirm you are requesting the desired DHR

dlNumberYesString
This is the driver's license number of the monitoring request that had a HIT and is being requested to obtain the DHR

Test Request

FieldTest ValueNotes
usernameYour actual username
passwordYour actual password
monitorIdAny value included in the viewDriverMonitoringResults method from the test system

Test Cases

Monitor IDDL NumberRecord Has Hit
50012000005No
50022000006No
50032000007Yes
50042000008No
50052000009Yes
50062000010No
50072000012Yes
50082000013Yes
dlNumberAny value included in the viewDriverMonitoringResults method from the test system

Response

FieldData TypeFormatNotes
successfulResponseBooleantrue/falseIndicates if the response includes the record requested
messageString
Will contain an error message if the request for the driving record is not successful
searchResponeObject
This is the same format response returned by the existing Driver History web service.  The details on formatting can be found here: Driver History web service integration guide

Possible Error Messages

ReasonError Message
Invalid request criteriaNo records match the parameters provided
Invalid driver license formatDrivers License Number is invalid format

Standard Authentication Error Responses

ReasonError Message
Invalid LoginInvalid login for <username>
Invalid or no DPPA for userValid login for <username>, but DPPA Number is not valid.
User does not have any access permissionsValid login for <username>, but login access group list is empty.
User does not have permission to access this serviceValid login for <username>, but DPS_MVR_PTP_WS access group may not be present.
Access not grated to UAT environmentAccess to the test web service is only available for testing purposes.

Monitoring Result Status Codes

ValueDefinition
1Requested - Record has been requested, but processing has not yet been completed.
2No Changes Found - Record has been processed successfully and no changes to the record were found.
3Changes Found - Record has been processed successfully and changes were found.  You can retrieve the full record using the requestDriverMonitoringRecord method.
4No Matching Record Found - No matching driver license record could be found.
5Invalid License Number - The driver license number provided is not valid and no record could be found.
6Unknown Error Occurred - An unexpected error occurred.



© Tyler Technologies Alabama.  All rights reserved.