feature/APPEALS-21478: Update Geo-matching to use zip code instead of street address

app/jobs/fetch_hearing_locations_for_veterans_job.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class FetchHearingLocationsForVeteransJob < ApplicationJob
+class FetchHearingLocationsForVeteransJob < CaseflowJob
   queue_with_priority :low_priority
   application_attr :hearing_schedule
 

app/services/bgs_address_service.rb

@@ -53,7 +53,9 @@ def cache_key
   def fetch_bgs_record
     Rails.cache.fetch(cache_key, expires_in: 24.hours) do
       bgs.find_address_by_participant_id(participant_id)
-    rescue Savon::Error
+    rescue Savon::Error => error
+      Raven.capture_exception(error)
+      Rails.logger.warn("Failed to fetch address from BGS for participant id: #{participant_id}: #{error}")
       # If there is no address for this participant id then we get an error.
       # catch it and return an empty array
       nil

app/services/external_api/va_dot_gov_service.rb

@@ -125,6 +125,67 @@ def validate_address(address)
       ExternalApi::VADotGovService::AddressValidationResponse.new(response)
     end
 
+    # Verifies a veteran's zip code and returns its associated geographic coordinates in latitude and longitude.
+    #
+    # @param zip_code [String] A veteran's five-digit zip code
+    #
+    # @return        [ExternalApi::VADotGovService::AddressValidationResponse]
+    #   A wrapper around the VA.gov API response that includes the geocode (latitude and longitude) associated
+    #   with the veteran's zip code.
+    #
+    #   Note: The response will include an "AddressCouldNotBeFound" and "lowConfidenceScore" messages
+    #
+    # API Documentation: https://developer.va.gov/explore/verification/docs/address_validation
+    #
+    # Expected JSON Response from API:
+    #
+    # ```
+    # {
+    #   "messages": [
+    #     {
+    #       "code": "ADDRVAL112",
+    #       "key": "AddressCouldNotBeFound",
+    #       "text": "The Address could not be found",
+    #       "severity": "WARN"
+    #     },
+    #     {
+    #       "code": "ADDR306",
+    #       "key": "lowConfidenceScore",
+    #       "text": "VaProfile Validation Failed: Confidence Score less than 80",
+    #       "severity": "WARN"
+    #     }
+    #   ],
+    #   "address": {
+    #     "addressLine1": "Address",
+    #     "zipCode5": "string",
+    #     "stateProvince": {},
+    #     "country": {
+    #       "name": "United States",
+    #       "code": "USA",
+    #       "fipsCode": "US",
+    #       "iso2Code": "US",
+    #       "iso3Code": "USA"
+    #     }
+    #   },
+    #   "geocode": {
+    #     "calcDate": "2023-10-12T20:27:04Z",
+    #     "latitude": 40.7029,
+    #     "longitude": -73.8868
+    #   },
+    #   "addressMetaData": {
+    #     "confidenceScore": 0.0,
+    #     "addressType": "Domestic",
+    #     "deliveryPointValidation": "MISSING_ZIP",
+    #     "validationKey": 359084376
+    #   }
+    # }
+    # ```
+    def validate_zip_code(address)
+      response = send_va_dot_gov_request(zip_code_validation_request(address))
+
+      ExternalApi::VADotGovService::ZipCodeValidationResponse.new(response)
+    end
+
     # Gets full list of facility IDs available from the VA.gov API
     #
     # @param ids [Array<String, Symbol>] facility ids to check
@@ -388,6 +449,32 @@ def address_validation_request(address)
       }
     end
 
+    # Builds a request for the VA.gov veteran address validation endpoint using only the veteran's five-digit zip code.
+    # This will return "AddressCouldNotBeFound" and "lowConfidenceScore" messages. However, given a valid zip code, the
+    # response body will include valid coordinates for latitude and longitude.
+    #
+    # Note 1: Hard code placeholder string for addressLine1 to avoid "InvalidRequestStreetAddress" error
+    # Note 2: Include country name to ensure foreign addresses are properly handled
+    #
+    # @param address [Address] The veteran's address
+    #
+    # @return        [Hash] The payload to send to the VA.gov API
+    def zip_code_validation_request(address)
+      {
+        body: {
+          requestAddress: {
+            addressLine1: "address",
+            zipCode5: address.zip,
+            requestCountry: { countryName: address.country }
+          }
+        },
+        headers: {
+          "Content-Type": "application/json", Accept: "application/json"
+        },
+        endpoint: ADDRESS_VALIDATION_ENDPOINT, method: :post
+      }
+    end
+
     def track_pages(pages)
       DataDogService.emit_gauge(
         metric_group: "service",

app/services/external_api/va_dot_gov_service/zip_code_validation_response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Inherits most of its behavior from AddressValidationResponse, but redefines a successful response
+# as one where a zip code returns valid geographic coordinates (regardless of whether a specific
+# addres could be found.
+
+class ExternalApi::VADotGovService::ZipCodeValidationResponse < ExternalApi::VADotGovService::AddressValidationResponse
+  def error
+    message_error || response_error || foreign_address_error
+  end
+
+  private
+
+  # The coordinates_invalid? check prevents the creation of a HearingAdminActionVerifyAddressTask when
+  # the response contains valid geographic coordiantes sufficient to complete geomatching
+  def message_error
+    messages&.find { |message| message.error.present? && coordinates_invalid? }&.error
+  end
+
+  # When using only an appellant's zip code to validate an address, an invalid zip code will return
+  # float values of 0.0 for both latitude and longitude
+  def coordinates_invalid?
+    return true if body[:geocode].nil?
+
+    [body[:geocode][:latitude], body[:geocode][:longitude]] == [0.0, 0.0]
+  end
+
+  def foreign_address_error
+    if coordinates_invalid? && address_type == "International"
+      Caseflow::Error::VaDotGovForeignVeteranError.new(
+        code: 500,
+        message: "Appellant address is not in US territories."
+      )
+    end
+  end
+
+  def address_type
+    body.dig(:addressMetaData, :addressType)
+  end
+end

app/services/va_dot_gov_address_validator.rb

@@ -25,8 +25,8 @@ class VaDotGovAddressValidator
     # Address was in the Philippines, and assigned to RO58.
     philippines_exception: :defaulted_to_philippines_RO58,
 
-    # Foreign addresses need to be handled by an admin.
-    created_foreign_veteran_admin_action: :created_foreign_veteran_admin_action,
+    # Address was foreign (not Philippines), and assigned to RO11.
+    foreign_veteran_exception: :defaulted_to_pittsburgh_RO11,
 
     # An admin needs to manually handle addresses that can't be verified.
     created_verify_address_admin_action: :created_verify_address_admin_action
@@ -47,38 +47,19 @@ def update_closest_ro_and_ahls
     update_closest_regional_office
     destroy_existing_available_hearing_locations!
     create_available_hearing_locations
-
     { status: :matched_available_hearing_locations }
   end
 
   def valid_address
     @valid_address ||= if valid_address_response.success?
                          valid_address_response.data
                        else
-                         validate_zip_code
+                         manually_validate_zip_code
                        end
   end
 
   def state_code
-    map_country_code_to_state
-  end
-
-  def closest_regional_office
-    @closest_regional_office ||= begin
-      return unless closest_ro_response.success?
-
-      # Note: In `ro_facility_ids_to_geomatch`, the San Antonio facility ID and Elpaso facility Id is passed
-      # as a valid RO for any veteran living in Texas.
-      return "RO62" if closest_regional_office_facility_id_is_san_antonio?
-      return "RO49" if closest_regional_office_facility_id_is_el_paso?
-
-      RegionalOffice
-        .cities
-        .detect do |ro|
-          ro.facility_id == closest_ro_facility_id
-        end
-        .key
-    end
+    map_state_code_to_state_with_ro
   end
 
   def available_hearing_locations
@@ -143,6 +124,23 @@ def ro_facility_ids_to_geomatch
 
   private
 
+  def closest_regional_office
+    @closest_regional_office ||= begin
+      return unless closest_ro_response.success?
+      # Note: In `ro_facility_ids_to_geomatch`, the San Antonio facility ID and Elpaso facility Id is passed
+      # as a valid RO for any veteran living in Texas.
+      return "RO62" if closest_regional_office_facility_id_is_san_antonio?
+      return "RO49" if closest_regional_office_facility_id_is_el_paso?
+
+      RegionalOffice
+        .cities
+        .detect do |ro|
+          ro.facility_id == closest_ro_facility_id
+        end
+        .key
+    end
+  end
+
   def update_closest_regional_office
     appeal.update(closest_regional_office: closest_regional_office_with_exceptions)
   end
@@ -174,7 +172,7 @@ def create_available_hearing_location(facility:)
   end
 
   def valid_address_response
-    @valid_address_response ||= VADotGovService.validate_address(address)
+    @valid_address_response ||= VADotGovService.validate_zip_code(address)
   end
 
   def available_hearing_locations_response
@@ -220,15 +218,13 @@ def closest_ro_facility_id
     closest_ro_response.data.first&.dig(:facility_id)
   end
 
-  def validate_zip_code
-    if address.zip_code_not_validatable?
-      nil
-    else
-      lat_lng = ZipCodeToLatLngMapper::MAPPING[address.zip[0..4]]
+  def manually_validate_zip_code
+    return if address.zip_code_not_validatable?
 
-      return nil if lat_lng.nil?
+    lat_lng = ZipCodeToLatLngMapper::MAPPING[address.zip[0..4]]
 
-      { lat: lat_lng[0], long: lat_lng[1], country_code: address.country, state_code: address.state }
-    end
+    return if lat_lng.nil?
+
+    { lat: lat_lng[0], long: lat_lng[1], country_code: address.country, state_code: address.state }
   end
 end

app/services/va_dot_gov_address_validator/error_handler.rb

@@ -11,20 +11,17 @@ def initialize(appeal:, appellant_address:)
   def handle(error)
     if check_for_philippines_and_maybe_update
       :philippines_exception
+    elsif foreign_veteran_errors.any? { |klass| error.instance_of?(klass) }
+      appeal.va_dot_gov_address_validator.assign_ro_and_update_ahls("RO11")
+
+      :foreign_veteran_exception
     elsif verify_address_errors.any? { |klass| error.instance_of?(klass) }
       create_admin_action_for_schedule_hearing_task(
         instructions: "The appellant's address in VBMS does not exist, is incomplete, or is ambiguous.",
         admin_action_type: HearingAdminActionVerifyAddressTask
       )
 
       :created_verify_address_admin_action
-    elsif foreign_veteran_errors.any? { |klass| error.instance_of?(klass) }
-      create_admin_action_for_schedule_hearing_task(
-        instructions: "The appellant's address in VBMS is outside of US territories.",
-        admin_action_type: HearingAdminActionForeignVeteranCaseTask
-      )
-
-      :created_foreign_veteran_admin_action
     else
       # :nocov:
       raise error # rubocop:disable Style/SignalException

app/services/va_dot_gov_address_validator/validations.rb

@@ -4,19 +4,16 @@ module VaDotGovAddressValidator::Validations
   private
 
   # :nocov:
-  def map_country_code_to_state
-    case valid_address[:country_code]
+  def map_state_code_to_state_with_ro
+    case valid_address[:state_code]
     # Guam, American Samoa, Marshall Islands, Micronesia, Northern Mariana Islands, Palau
-    when "GQ", "AQ", "RM", "FM", "CQ", "PS"
+    when "GU", "AS", "MH", "FM", "MP", "PW"
       "HI"
-    # Philippine Islands
-    when "PH", "RP", "PI"
-      "PI"
-    # Puerto Rico, Vieques, U.S. Virgin Islands
-    when "VI", "VQ", "PR"
+    # U.S. Virgin Islands
+    when "VI"
       "PR"
-    when "US", "USA"
-      valid_address.dig(:state_code)
+    else
+      valid_address[:state_code]
     end
   end
   # :nocov:

lib/caseflow/error.rb

@@ -46,7 +46,7 @@ class VaDotGovMissingFacilityError < VaDotGovAPIError; end
   class VaDotGovInvalidInputError < VaDotGovAPIError; end
   class VaDotGovMultipleAddressError < VaDotGovAPIError; end
   class VaDotGovNullAddressError < StandardError; end
-  class VaDotGovForeignVeteranError < StandardError; end
+  class VaDotGovForeignVeteranError < SerializableError; end
 
   class FetchHearingLocationsJobError < SerializableError; end