Driver Monitoring Service Integration Guide
- Robert Hines
- Ryan Miller (Deactivated)
- Mary Beth Walls (Deactivated)
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
| 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 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 Type | Cost Per Request | Description | Example |
|---|---|---|---|
| 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 month | Scheduled monitoring for each future month individually. | Let me know if there are any changes to this record over the next three months. |
Connection Strings
| Environment | URL | Purpose |
|---|---|---|
| UAT | https://dev.alabamainteractive.org/alea-dhr-ws/MonitoringWSService?WSDL | This is the WSDL, which defines the SOAP service and its available methods |
| UAT | https://dev.alabamainteractive.org/alea-dhr-ws/MonitoringWSService | This is the web service end-point and is where you will direct your requests |
| Production | https://api.alabamainteractive.org/alea-dhr-ws/MonitoringWSService?WSDL | This is the WSDL, which defines the SOAP service and its available methods |
| Production | https://api.alabamainteractive.org/alea-dhr-ws/MonitoringWSService | This 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
| 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 |
| The driver license number to be monitored |
| monitorStartDate | Yes | Number | yyyymm |
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. |
| monitorEndDate | Yes | Number | yyyymm |
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. |
| customerReferenceId | No | String | Max Length: 100 | This 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. |
| 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 an 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 |
|---|---|---|---|
| successfulResponse | Boolean | true/false | Indicates if the monitoring request was successfully added to your account |
| monitorId | Number | ||
| message | String | If "successfulResponse = false", then an error message will be present. Otherwise, this value will be blank. |
Possible Error Messages
| Reason | Error Message |
|---|---|
| Invalid monitoring start date format | Invalid format: monitorStartDate. |
| Invalid monitoring end date format | Invalid format: monitorEndDate. |
| Invalid monitoring start date | Invalid date range: monitorStartDate. monitorStartDate must be less than or equal to <current month yyyymm> |
| Invalid monitoring end date | Invalid date range: monitorEndDate. MonitorEndDate must be greater than or equal to <current month yyyymm> |
| Invalid monitoring end date | Invalid date range: Invalid date range: monitorEndDate. MonitorEndDate is less than MonitorStartDate. |
| Duplicate request found | Duplicate 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
| 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 | |
| monitorMonth | Yes | Number | yyyymm | 4-digit Year & 2-digit Month |
Response
| Field | Data Type | Format | Notes |
|---|---|---|---|
| successfulResponse | Boolean | true/false | Indicates if the request returned a successful response |
| message | String | If "successfulResponse = false", then an error message will be present. Otherwise, this value will be blank | |
| monitorMonth | Number | yyyymm | This will be the monitor month provided in the request |
| monitoringRequests | Object List | monitoringRequest object | This will contain a list of monitoring request object |
| monitoringRequests.monitoringRequest | Object | monitoringRequest | This is a specific monitoring request and includes all of the fields provided when the request was added |
| monitoringRequests.monitoringRequest.monitorId | Number | This is the unique Monitoring ID for this monitored record | |
| monitoringRequests.monitoringRequest.customerReferenceId | String | This is the value provided in the original Driver Monitoring Service Integration Guide#submitDriverMonitoringRequest | |
| monitoringRequests.monitoringRequest.dlNumber | String | The driver's license number being monitored | |
| monitoringRequests.monitoringRequest.citationAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new citation is added to a record |
| monitoringRequests.monitoringRequest.citationRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation is removed from a record |
| monitoringRequests.monitoringRequest.accidentAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new accident is added to a record |
| monitoringRequests.monitoringRequest.accidentRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when an accident is removed from a record |
| monitoringRequests.monitoringRequest.withdrawalAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record |
| monitoringRequests.monitoringRequest.withdrawalRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record |
| monitoringRequests.monitoringRequest.reinstated | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a license is reinstated |
Possible Error Messages
| Reason | Error Message |
|---|---|
| Invalid monitor month format | Invalid format: monitorMonth (yyyyMM) |
removeDriverMonitoringRequest
Use this method to remove a monitoring request. Note that only pending non-completed monitoring requests can be removed.
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 | |
| monitorId | Yes | Number | 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. | |
| dlNumber | Yes | String |
| The driver's license number you would like to remove from monitoring |
| customerReferenceId | No | String | If provided will be used in combination with the monitorId and dlNumber to uniquely identify and remove the requested record from monitoring. |
Response
| Field | Data Type | Format | Notes |
|---|---|---|---|
| successfulResponse | Boolean | true/false | Indicates if the request to remove the record from monitoring was successful |
| message | String | If "successfulResponse = false", then an error message will be present. Otherwise, this value will be blank |
Possible Error Messages
| Reason | Error Message |
|---|---|
| Invalid request criteria | No records match the parameters provided |
| Invalid driver license format | Drivers 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
| 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 | |
| monitorMonth | Yes | Number | yyyymm | 4-digit Year & 2-digit Month |
Test Request
| Field | Test Value | Notes |
|---|---|---|
| username | Your actual username | |
| password | Your actual password | |
| monitorMonth | 202401 | You 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
| Field | Data Type | Format | Notes |
|---|---|---|---|
| successfulResponse | Boolean | true/false | Indicates if the request returned a successful response |
| message | String | If successfulResponse = false, then an error message will be present. Otherwise, this value will be blank | |
| monitorMonth | Number | yyyymm | This will be the monitor month provided in the request |
| monitoringResults | Object List | monitoringResult object | This will contain a list of monitoring result object |
| monitoringResults.monitoringResult | Object | monitoringResult | This 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.monitorId | Number | This is the unique Monitoring ID for this monitored record | |
| monitoringResults.monitoringResult.customerReferenceId | String | This is the value provided in the original Driver Monitoring Service Integration Guide#submitDriverMonitoringRequest | |
| monitoringResults.monitoringResult.dlNumber | String | The driver's license number being monitored | |
| monitoringResults.monitoringResult.monitorStart | Number | yyyymm | The start date this monitoring request applies to |
| monitoringResults.monitoringResult.monitorEnd | Number | yyyymm | The end date this monitoring request applies to |
| monitoringResults.monitoringResult.recordHasHit | Boolean | true/false | Indicates if any of the requested triggers caused a HIT event |
| monitoringResults.monitoringResult.status | Number | 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.citationAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new citation is added to a record |
| monitoringResults.monitoringResult.citationRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a citation is removed from a record |
| monitoringResults.monitoringResult.accidentAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new accident is added to a record |
| monitoringResults.monitoringResult.accidentRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when an accident is removed from a record |
| monitoringResults.monitoringResult.withdrawalAdded | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a new withdrawal is added to a record |
| monitoringResults.monitoringResult.withdrawalRemoved | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a withdrawal is removed from a record |
| monitoringResults.monitoringResult.reinstated | Boolean | true/false | A value indicating if you wish to trigger monitoring hits when a license is reinstated |
| monitoringResults.monitoringResult.citationAddedResult | Boolean | true/false | A 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.citationRemovedResult | Boolean | true/false | A 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.accidentAddedResult | Boolean | true/false | A 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.accidentRemovedResult | Boolean | true/false | A 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.withdrawalAddedResult | Boolean | true/false | A 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.withdrawalRemovedResult | Boolean | true/false | A 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.reinstatedResult | Boolean | true/false | A 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
| Reason | Error Message |
|---|---|
| Invalid monitor month format | Invalid 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
| 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 | |
| monitorId | Yes | Number | 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 | |
| dlNumber | Yes | String | 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
| Field | Test Value | Notes | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| username | Your actual username | ||||||||||||||||||||||||||||
| password | Your actual password | ||||||||||||||||||||||||||||
| monitorId | Any value included in the viewDriverMonitoringResults method from the test system | Test Cases
| |||||||||||||||||||||||||||
| dlNumber | Any value included in the viewDriverMonitoringResults method from the test system |
Response
| Field | Data Type | Format | Notes |
|---|---|---|---|
| successfulResponse | Boolean | true/false | Indicates if the response includes the record requested |
| message | String | Will contain an error message if the request for the driving record is not successful | |
| searchRespone | Object | 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
| Reason | Error Message |
|---|---|
| Invalid request criteria | No records match the parameters provided |
| Invalid driver license format | Drivers License Number is invalid format |
Standard Authentication Error Responses
| 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. |
Monitoring Result Status Codes
| Value | Definition |
|---|---|
| 1 | Requested - Record has been requested, but processing has not yet been completed. |
| 2 | No Changes Found - Record has been processed successfully and no changes to the record were found. |
| 3 | Changes Found - Record has been processed successfully and changes were found. You can retrieve the full record using the requestDriverMonitoringRecord method. |
| 4 | No Matching Record Found - No matching driver license record could be found. |
| 5 | Invalid License Number - The driver license number provided is not valid and no record could be found. |
| 6 | Unknown Error Occurred - An unexpected error occurred. |
© Tyler Technologies Alabama. All rights reserved.