Skip to main content

5. Licence checking

5.1 Introduction​

The licenceCheckController is responsible for handling the verification of a driver's licence and processing the results. It interacts with DVLA's ADD API to perform licence checks, update driver information, and record the outcome of the check. This controller is called after the JWT has been obtained successfully.

5.2 Functionality​

5.2.1 Perform licence check​

DVLA ADD(Access to driver data) API URL :​

https://driver-vehicle-licensing.api.gov.uk/full-driver-enquiry/v1/driving-licences/retrieve

  • The callLicenceCheckAPI is used to make a call to the DVLA API for licence checking.
  • The function constructs the HTTP request headers required for the API call. Accept and Content-Type headers are set to indicate that the client accepts and sends data in JSON format. The x-api-key header contains the API key required for authentication. The Authorization header includes the JWT (JSON Web Token) for further authorization.
  • The payload is an object containing drivingLicenceNumber, includeCPC, includeTacho, acceptPartialResponse to be sent in the API request. Ex:
    {
    "drivingLicenceNumber": "ABCDE123456AB1AB",
    "includeCPC": true,
    "includeTacho": true,
    "acceptPartialResponse": "false"
    }
  • Using the provided URL, headers, and payload, we use Axios to initiate an HTTP POST request to the specified URL, sending the data contained in the payload variable in the request body, while including the defined HTTP headers via the { headers } parameter configuration.
    • Logging the request:
      • The updateLog function is called to log the following:
        • level: Set to 'info' to indicate an informational log.
        • request: Logs the details of the API request, including the following sub-parameters:
          • payload: Contains the payload data being sent in the API request.
          • useStub: Indicates whether a stub or the actual DVLA API is being used.
          • url: Specifies the URL of the DVLA API.
          • apiKey: Partially hides the DVLA API key.
          • message: Describes the purpose of the log entry, by specifying "calling DVLA API with payload".
        • driverDetails: Contains information about the driver for context.
    • Handling a Successful Response:
      • If the API call is successful, i.e., the server responds with a valid HTTP response (e.g., 200 OK), Axios invokes the .then() callback.
      • Within the .then() block, the response object contains information about the HTTP response, including response data.
      • The updateLog function is called to log the following:
        • level: Set to 'info' to indicate an informational log.
        • path: Logs the path of the API request.
        • response: Logs the API response data, which include details about the driver's license.
        • message: Describes the log message, in this case, "DVLA API call successful".
        • driverDetails: Contains information about the driver for context.
      • Finally, resolve(response) is called to fulfill the Promise with the API response.
    • Handling Errors:
      • If there is an issue with the API call (e.g., network error, server error), Axios invokes the .catch() callback.
      • Within the .catch() block: The error object contains details about the error that occurred.
      • The updateLog function is called again to log the error:
        • level: Set to 'error' to indicate an error log.
        • error: Contains information about the error, including the error message.
        • message: Describes the log message, in this case, "DVLA API call failed".
        • driverDetails: Contains information about the driver for context.
      • reject(error) is called to reject the Promise with the error object, allowing error handling in the calling code.

5.2.2 Update driver details​

Upon successful response from the callLicenceCheckAPI, driver details are updated accordingly by calling updateDriverDetails function. This function performs the following operations:

  1. Updates driver date of birth.

  2. Updates driver disqualification details.

    A driver is considered to be disqualified if the licence status returned by the DVLA is either Disqualified or Revoked.

  3. Updates the driver stat array.

5.2.3 Update driver licence check date​

updateDriverLicenceCheckDate is called after updating the driver details, this function is responsible for updating the next licence check date for a driver based on various factors such as the risk category and disqualification status.

This function performs the following operations:

  1. Retrieve the sub-customer and risk category from driverDetails.
  2. Check if the driverLicenceInfo contains disqualification information, specifically, the driverDisqualifiedUntil property.
  3. Calculate the next licence check date based on the risk category and add it to the current date. This is determined using the getFrequencyFromRisk function.
  4. If the driver is currently disqualified and the disqualification end date is in the future, set the next licence check date to the disqualification end date. This ensures that the driver's licence is checked once they are eligible again.
  5. Update the driver's document with the new nextLicenceCheckDate.
  6. Add an entry in the driver licence check queue with the driver's ID, lease ID, and sub-customer ID at year, month, day level. This entry is used for scheduling periodic licence checks.

5.2.4 Update driving licence record​

updateDrivingLicenceRecord is called after updating driver licence check date and is responsible for updating the driving licence record.

This function performs the following operations:

  1. Extract relevant data from the driverLicenceInfo object, including licence data, token data, entitlements, and more.
  2. Perform transformations and enrichments on various data elements:
    • addDescriptionToEntitlements: Adds descriptions to entitlements based on information from DVLA.
    • addDescriptionToTachoCards: Adds descriptions to tacho cards.
    • getDriverLicenceCpcs: Extracts CPC information.
    • addDescriptionToLicenceRestrictions: Adds descriptions to licence restrictions.
  3. Construct an update object for the driving licence record and update in the database, including:
    • issueNumber: Masked and raw issue numbers.
    • startDate and endDate: Validity dates of the licence.
    • status: Type of licence.
    • entitlements: Updated entitlements.
    • licenceRestrictions: Updated licence restrictions.
    • tachoCards: Updated tacho cards.
    • cpcs: Updated CPCs.
    • resultMessages: Transformed error messages from the DVLA API.
    • firstIssuedDate: Derived from Car category's start date.

5.2.5 Update driving licence penalties​

updateDrivingLicencePenalties is called after updating necessary fields in driver licence record and is responsible for updating the penalties associated with the driver licence record.

This function performs the following operations:

  1. Gets the existing penalties for the driving licence record.

  2. Calls createPenaltiesDataUsingPenaltiesCodes function by passing the existing penalties, new penalties and look up data to create a curated list of penalties by merging the existing penalties and the new penalties returned by the DVLA.

    createPenaltiesDataUsingPenaltiesCodes function performs the following operations:

    1. For all penalties we first check if the penalty(endorsement) obtained by the DVLA is available in our lookup table.

      • If it is available then, we check if overrideCalculationType is set to USE_OFFENCE_DATE_IF_DISQUALIFIED, and the driver is disqualified , then offenceOrConvictionDate is set to the convictionDate if available, otherwise, it falls back to the offenceDate.

        Here offenceOrConvictionDate is used to determine the penalty end date and removal date.

      • If overrideCalculationType is set to use USE_CONVICTION_DATE, then offenceOrConvictionDate will be set to either the convictionDate or offenceDate, whichever is available.

      • If penalty is not available in our lookup table then we set the penalty end date and removal date as null.

    2. A penalty object is constructed for each penalty with the following properties and added to a list:

      • id: A unique identifier generated using uuidv4().
      • code: The offence code obtained from the endorsement.
      • description: The description of the offence obtained from the endorsement.
      • disqualification: Indicates if there is a disqualification associated with the penalty; it defaults to null if not present in the endorsement.
      • disqualifiedPendingSentence: Indicates if there is a disqualified pending sentence associated with the penalty; it defaults to null if not present in the endorsement.
      • endDate: The end date of the penalty, calculated based on the endPeriod and the offenceOrConvictionDate. It's null if no penaltyDataFound is available.
      • removalDate: The removal date of the penalty, calculated based on the period and the offenceOrConvictionDate. It's null if no penaltyDataFound is available.
      • convictionDate: The conviction date of the endorsement, converted to a string format. It's null if there is no convictionDate in the endorsement.
      • penaltyDate: The offence date of the endorsement, converted to a string format.
      • penaltyPoints: The penalty points associated with the endorsement; it defaults to null if not present in the endorsement.
      • isManuallyAdded: A boolean indicating whether the penalty was manually added; it is set to false.

    3. After creating a curated list of penalties with above properties for each penalty, it is compared with the existing penalties and removes duplicates if any and returns the list.

  3. Once the penalties are retrieved from createPenaltiesDataUsingPenaltiesCodes we call updateDisqualificationDetailsForDriver which updates:

    1. Disqualification status of the driver

    2. Disqualification start date

    3. Disqualification end date

      If the driver is disqualified for life disqualification end date is not present

  4. addPenaltiesAgainstDrivingLicence to save the penalties list to the driving licence record in the database.

  5. addPenaltiesToPointCalculationQueue is called to add penalties to the point calculation queue to calculate and update the penalty points for the driver.

5.2.6 Add licence check history​

addLicenceCheckHistory is called to add the licence check history for a licence record.

This function performs the following operations:

  1. Record license checks, including their checkDate, checkType, checkedOn, checkStatus, response code and message as 'Licence checked successfully', in the database.
  2. Increment the count of auto-checks associated with a specific lease and license record.

After adding the licence check history we update the requestingDriverLicenceCheck field in the database for the specified driver, setting it to false and send a successful JSON response to the client along with a message 'Successfully checked licence for driver', driverId, and the DVLA returned driver licence information as data.

5.3 Configuration​

  1. Environment variable for API key:
  • DVLA_API_KEY
  1. Environment variable for URL:
  • DVLA_API_URL

Status: Draft (Pending Review)
Category: Protected
Authored By: Sohan on Oct 05, 2023