Enhance facility name fetching for OH Rx (#24437)

* feat: Add prescription tracking support to UHD

- Add tracking attribute to UnifiedHealthData::Prescription model as array
- Update VistaPrescriptionAdapter to parse trackingInfo from VistA responses
- Add date formatting for shippedDate (VistA format to ISO 8601)
- Refactor adapter methods to eliminate MethodLength violation
- Update serializer to include tracking data in API responses
- Set is_trackable dynamically based on tracking data presence
- Update all related test files to use tracking array format
- Remove tracking_information attribute (no backwards compatibility needed)

Tracking objects include: prescriptionName, prescriptionNumber, ndcNumber,
prescriptionId, trackingNumber, shippedDate, carrier, otherPrescriptions

* feat: Add Oracle Health prescription tracking support

- Add tracking information parsing from FHIR MedicationDispense identifiers
- Extract tracking number, prescription number, carrier, shipped date from identifiers
- Add NDC number extraction from medicationCodeableConcept coding
- Set is_trackable dynamically based on tracking data presence
- Refactor build_prescription_attributes to eliminate MethodLength violation
- Add comprehensive test coverage for Oracle Health tracking scenarios
- Handle multiple MedicationDispense resources with tracking data
- Gracefully handle missing tracking data with empty arrays

Oracle Health tracking objects include: prescriptionName, prescriptionNumber,
ndcNumber, prescriptionId, trackingNumber, shippedDate, carrier, otherPrescriptions

* Fix NDC extraction to use individual dispense level

- Move NDC extraction from top-level MedicationRequest to individual MedicationDispense resources
- Update extract_ndc_number method to work with dispense parameter instead of resource
- Update corresponding spec tests to reflect new NDC extraction behavior
- Ensures FHIR compliance where each dispense can have its own medication coding

* Add VistA tracking specs

* Split adapter spec into EHR specific files

* feat: Enhanced facility name extraction for Oracle Health prescriptions

- Updated extract_facility_name to use 3-digit station number extraction from latest dispense
- Added 3-tier fallback strategy: Rails cache → Lighthouse API → station number
- Created FacilityNameCacheJob for hourly VHA facility name caching with 4-hour TTL
- Added comprehensive StatsD metrics for cache performance monitoring
- Updated prescription model to include type attribute
- Enhanced test coverage for facility name extraction scenarios
- Added periodic job scheduling at 37 minutes past hour
- Removed legacy fallbacks to encounter and performer for focused approach

Improves facility name resolution for Oracle Health prescriptions by using
VHA station numbers from dispense locations with intelligent caching strategy.

* rubocop

* Style updates

* Simplify facility name logic

* Fix prescription_id type in OracleHealthPrescriptionAdapter to maintain consistency

* remove unnecessary compact call

* rubocop

* Enhance facility name extraction by implementing cache fallback and API retrieval in OracleHealthPrescriptionAdapter

* Implement caching for facility name retrieval in fetch_facility_name_from_api method

* Fix facility name cache pagination and TTL

* Add explicit client load

* Normalize refill orders before building UHD payload

* Allow UHD facility cache fallback to full facility identifier

* rubocop

* Add CODEOWNERS entry for app/sidekiq/unified_health_data/facility_name_cache_job.rb

* Add CODEOWNERS entry for spec/sidekiq/unified_health_data/facility_name_cache_job_spec.rb

* Use Rails.cache.exist? to determine facility-name cache hits

Recognize explicit cache entries (including nil) by checking Rails.cache.exist?
instead of relying on the truthiness of Rails.cache.read. Update related
specs to stub Rails.cache.exist? (and provide a default) so tests reflect the
new cache-hit semantics.

* UnifiedHealthData: paginate Lighthouse facilities using response.links['next']

Replace manual page increment and batch-size stop logic with following the
response.links['next'] URL. Parse next link query params and request the
next page from the Lighthouse client. This ensures robust pagination
based on API-provided links.

Update specs to stub response.links by default and assert subsequent
pages are requested using the next link's query params.

* Improve var name

* UnifiedHealthData: adjust facility lookup logging levels and update specs

- Log invalid station extraction as error when station format can't be parsed
- Change Lighthouse "no facility" log from info to warn
- Escalate API failure logging from warn to error
- Update specs to expect the new logging behavior and stub logger calls

* Back model change out in favor of separate PR

* rubocop

* UnifiedHealthData: coerce labs_logging_date_range_days to integer in LabsRefreshJob

Call .to_i when reading Settings.mhv.uhd.labs_logging_date_range_days and update the spec to match so date arithmetic always uses an integer.

* Fix log level expectation

Author: acrollet

.github/CODEOWNERS

@@ -502,6 +502,7 @@ app/sidekiq/terms_of_use @department-of-veterans-affairs/octo-identity
 app/sidekiq/test_user_dashboard @department-of-veterans-affairs/qa-standards @department-of-veterans-affairs/backend-review-group
 app/sidekiq/test_user_dashboard/daily_maintenance.rb @department-of-veterans-affairs/qa-standards @department-of-veterans-affairs/backend-review-group
 app/sidekiq/transactional_email_analytics_job.rb @department-of-veterans-affairs/vfs-authenticated-experience-backend @department-of-veterans-affairs/backend-review-group
+app/sidekiq/unified_health_data/facility_name_cache_job.rb @department-of-veterans-affairs/va-cto-health-products @department-of-veterans-affairs/backend-review-group
 app/sidekiq/unified_health_data/labs_refresh_job.rb @department-of-veterans-affairs/va-cto-health-products @department-of-veterans-affairs/backend-review-group
 app/sidekiq/user_actions_cleanup_job.rb @department-of-veterans-affairs/octo-identity
 app/sidekiq/va_notify_dd_email_job.rb @department-of-veterans-affairs/va-notify-write @department-of-veterans-affairs/backend-review-group
@@ -1893,6 +1894,7 @@ spec/sidekiq/simple_forms_api/form_remediation/upload_retry_job_spec @department
 spec/sidekiq/terms_of_use @department-of-veterans-affairs/octo-identity
 spec/sidekiq/test_user_dashboard @department-of-veterans-affairs/qa-standards @department-of-veterans-affairs/backend-review-group
 spec/sidekiq/transactional_email_analytics_job_spec.rb @department-of-veterans-affairs/vfs-authenticated-experience-backend @department-of-veterans-affairs/backend-review-group
+spec/sidekiq/unified_health_data/facility_name_cache_job_spec.rb @department-of-veterans-affairs/va-cto-health-products @department-of-veterans-affairs/backend-review-group
 spec/sidekiq/unified_health_data/labs_refresh_job_spec.rb @department-of-veterans-affairs/va-cto-health-products @department-of-veterans-affairs/backend-review-group
 spec/sidekiq/user_actions_cleanup_job_spec.rb @department-of-veterans-affairs/octo-identity
 spec/sidekiq/va_notify_dd_email_job_spec.rb @department-of-veterans-affairs/va-notify-write @department-of-veterans-affairs/backend-review-group

app/sidekiq/unified_health_data/facility_name_cache_job.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'lighthouse/facilities/v1/client'
+
+module UnifiedHealthData
+  # FacilityNameCacheJob
+  #
+  # This Sidekiq job fetches VHA facilities from the Lighthouse Facilities API
+  # and caches a mapping of station_number -> facility_name in Rails cache.
+  # The cache is set to expire after 4 hours to ensure fresh data with hourly refreshes.
+  #
+  # Why:
+  # - Prescription processing needs facility names for station numbers from Oracle Health
+  # - Making individual API calls per prescription is inefficient and can hit rate limits
+  # - HealthFacility table excludes some facilities that VHA includes
+  # - Rails cache provides fast lookups with automatic expiration
+  #
+  # How:
+  # - Fetches all VHA facilities from Lighthouse API
+  # - Extracts station numbers from facility IDs (removes 'vha_' prefix)
+  # - Stores station_number -> facility_name mapping in Rails cache
+  # - Sets 4-hour TTL with hourly refresh for reliability
+  #
+  class FacilityNameCacheJob
+    include Sidekiq::Job
+
+    CACHE_KEY_PREFIX = 'uhd:facility_names'
+    BATCH_SIZE = 1000
+
+    # retry for ~30 minutes max since job runs every hour
+    # https://github.com/sidekiq/sidekiq/wiki/Error-Handling
+    sidekiq_options retry: 3
+
+    sidekiq_retries_exhausted do |msg|
+      Rails.logger.error("[UnifiedHealthData] - #{msg['class']} failed with no retries left: #{msg['error_message']}")
+      StatsD.increment('unified_health_data.facility_name_cache_job.failed_no_retries')
+    end
+
+    def perform
+      facility_map = fetch_vha_facilities
+      cache_facility_names(facility_map)
+
+      Rails.logger.info("[UnifiedHealthData] - Cached #{facility_map.size} VHA facility names")
+      StatsD.increment('unified_health_data.facility_name_cache_job.complete')
+      StatsD.gauge('unified_health_data.facility_name_cache_job.facilities_cached', facility_map.size)
+    rescue => e
+      Rails.logger.error("[UnifiedHealthData] - Error in #{self.class.name}: #{e.message}")
+      StatsD.increment('unified_health_data.facility_name_cache_job.error')
+      raise "Failed to cache facility names: #{e.message}"
+    end
+
+    private
+
+    def fetch_vha_facilities
+      facilities_client = Lighthouse::Facilities::V1::Client.new
+      all_facilities = []
+
+      Rails.logger.info('[UnifiedHealthData] - Fetching VHA facilities from Lighthouse API')
+
+      response = facilities_client.get_paginated_facilities(
+        type: 'health',
+        per_page: BATCH_SIZE,
+        page: 1
+      )
+
+      loop do
+        all_facilities.concat(extract_vha_facilities(response))
+
+        # Check if there's a next page link
+        break unless response.links&.dig('next')
+
+        response = fetch_next_page(facilities_client, response.links['next'])
+      end
+
+      # Convert to hash for easy lookup
+      all_facilities.to_h { |facility| [facility[:station_number], facility[:name]] }
+    end
+
+    def extract_vha_facilities(response)
+      response.facilities.filter_map do |facility|
+        next unless facility.id.start_with?('vha_')
+
+        station_number = facility.id.sub(/^vha_/, '')
+        { station_number:, name: facility.name }
+      end
+    end
+
+    def fetch_next_page(client, next_url)
+      next_url = URI.parse(next_url)
+      next_params = URI.decode_www_form(next_url.query).to_h.transform_keys(&:to_sym)
+      client.get_paginated_facilities(next_params)
+    end
+
+    def cache_facility_names(facility_map)
+      return if facility_map.empty?
+
+      Rails.logger.info('[UnifiedHealthData] - Caching facility names for 4 hours')
+
+      # Cache current facility names using Rails cache
+      facility_map.each do |station_number, facility_name|
+        cache_key = "#{CACHE_KEY_PREFIX}:#{station_number}"
+        Rails.cache.write(cache_key, facility_name, expires_in: 4.hours)
+      end
+
+      Rails.logger.info("[UnifiedHealthData] - Cache operation complete: #{facility_map.size} facilities cached")
+    end
+  end
+end

app/sidekiq/unified_health_data/labs_refresh_job.rb

@@ -36,7 +36,7 @@ def find_user(user_uuid)
 
     def date_range
       end_date = Date.current
-      days_back = Settings.mhv.uhd.labs_logging_date_range_days
+      days_back = Settings.mhv.uhd.labs_logging_date_range_days.to_i
       start_date = end_date - days_back.days
       [start_date, end_date]
     end

lib/periodic_jobs.rb

@@ -278,4 +278,8 @@
 
   # Daily cron job to check for PDF Form version changes
   mgr.register('0 12 * * *', 'FormPdfChangeDetectionJob')
+
+  # Hourly job to cache facility names for UHD prescriptions
+  # Runs at 37 minutes past the hour to avoid resource contention
+  mgr.register('37 * * * *', 'UnifiedHealthData::FacilityNameCacheJob')
 }

lib/unified_health_data/adapters/oracle_health_prescription_adapter.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'lighthouse/facilities/v1/client'
+
 module UnifiedHealthData
   module Adapters
     class OracleHealthPrescriptionAdapter
@@ -128,19 +130,30 @@ def extract_refill_remaining(resource)
       end
 
       def extract_facility_name(resource)
-        # Primary: dispenseRequest.performer
-        performer_display = resource.dig('dispenseRequest', 'performer', 'display')
-        return performer_display if performer_display
-
-        # Fallback: check contained Encounter for location
-        if resource['contained']
-          encounter = resource['contained'].find { |c| c['resourceType'] == 'Encounter' }
-          if encounter
-            location_display = encounter.dig('location', 0, 'location', 'display')
-            return location_display if location_display
-          end
+        # Get latest dispense using existing helper
+        latest_dispense = find_most_recent_medication_dispense(resource['contained'])
+        return nil unless latest_dispense
+
+        # Get .location.display from latest dispense
+        location_display = latest_dispense.dig('location', 'display')
+        return nil unless location_display
+
+        # First try the legacy 3-digit station number
+        three_digit_station = location_display.match(/^(\d{3})/)&.[](1)
+        facility_name = attempt_facility_lookup(three_digit_station)
+        return facility_name if facility_name
+
+        # If that fails, try the full facility identifier before the first hyphen (e.g., 648A4)
+        facility_identifier = location_display.split('-').first
+        # Valid format: 3 digits + up to 2 alpha (e.g., 648A, 648A4)
+        valid_station_regex = /^\d{3}[A-Za-z0-9]{0,2}$/
+        if facility_identifier.present? && facility_identifier != three_digit_station &&
+           facility_identifier.match?(valid_station_regex)
+          return attempt_facility_lookup(facility_identifier)
         end
 
+        Rails.logger.error("Unable to extract valid station number from: #{location_display}")
+
         nil
       end
 
@@ -286,6 +299,45 @@ def find_most_recent_medication_dispense(contained_resources)
           when_handed_over ? Time.zone.parse(when_handed_over) : Time.zone.at(0)
         end
       end
+
+      def fetch_facility_name_from_api(station_number)
+        facility_id = "vha_#{station_number}"
+        cache_key = "uhd:facility_names:#{station_number}"
+
+        begin
+          facilities_client = Lighthouse::Facilities::V1::Client.new
+          facilities = facilities_client.get_facilities(facilityIds: facility_id)
+
+          facility_name = if facilities&.any?
+                            facilities.first.name
+                          else
+                            Rails.logger.warn(
+                              "No facility found for station number #{station_number} in Lighthouse API"
+                            )
+                            nil
+                          end
+
+          # Cache the result (including nil) to avoid repeated API calls
+          # Keep TTL aligned with FacilityNameCacheJob refresh cadence (4 hours)
+          Rails.cache.write(cache_key, facility_name, expires_in: 4.hours)
+
+          facility_name
+        rescue => e
+          Rails.logger.error("Failed to fetch facility name from API for station #{station_number}: #{e.message}")
+          StatsD.increment('unified_health_data.facility_name_fallback.api_error')
+          nil
+        end
+      end
+
+      def attempt_facility_lookup(station_identifier)
+        return nil if station_identifier.blank?
+
+        cache_key = "uhd:facility_names:#{station_identifier}"
+        cached_name = Rails.cache.read(cache_key)
+        return cached_name if Rails.cache.exist?(cache_key)
+
+        fetch_facility_name_from_api(station_identifier)
+      end
     end
   end
 end

lib/unified_health_data/service.rb

@@ -96,15 +96,16 @@ def get_prescriptions(current_only: false)
     end
 
     def refill_prescription(orders)
+      normalized_orders = normalize_orders(orders)
       with_monitoring do
-        response = uhd_client.refill_prescription_orders(build_refill_request_body(orders))
+        response = uhd_client.refill_prescription_orders(build_refill_request_body(normalized_orders))
         parse_refill_response(response)
       end
     rescue Common::Exceptions::BackendServiceException => e
       raise e if e.original_status && e.original_status >= 500
     rescue => e
       Rails.logger.error("Error submitting prescription refill: #{e.message}")
-      build_error_response(orders)
+      build_error_response(normalized_orders)
     end
 
     def get_care_summaries_and_notes
@@ -279,8 +280,8 @@ def build_refill_request_body(orders)
         patientId: @user.icn,
         orders: orders.map do |order|
           {
-            orderId: order['id'].to_s,
-            stationNumber: order['stationNumber'].to_s
+            orderId: order[:id].to_s,
+            stationNumber: order[:stationNumber].to_s
           }
         end
       }
@@ -295,6 +296,16 @@ def build_error_response(orders)
       }
     end
 
+    def normalize_orders(orders)
+      return [] if orders.blank?
+
+      orders.map do |order|
+        next order unless order.respond_to?(:with_indifferent_access)
+
+        order.with_indifferent_access
+      end
+    end
+
     def parse_refill_response(response)
       body = response.body