# Company Field Extraction - Frontend Implementation Guide

## Overview

This document describes changes made to centralize company field extraction logic in the HV Dashboard. These changes were implemented in the backend for testing purposes but should be properly implemented by the frontend team.

## What Changed

### 1. Centralized Company Field Extraction

Previously, company field extraction logic was duplicated across multiple locations with inconsistent priority orders. The changes introduce a standardized approach using a centralized helper function.

### 2. Files Modified

- `hv-dashboard/hv-dashboard.php` (lines ~1011, ~1129)
- `hv-dashboard/includes/Providers/class-records-data-provider.php` (lines ~450, ~1052)

## Technical Details

### Previous Behavior

Company fields were extracted using different, region-specific logic scattered throughout the codebase:
- Different priority orders for LATAM vs other regions
- Inconsistent fallback mechanisms
- Duplicated extraction logic in multiple places

### New Behavior

All company field extraction now uses the centralized helper function `esa_extract_company_field()` with a unified priority order:

**Priority Order:**
1. `[company]` - Primary field
2. `[company_name]`, `[empresa]`, or `[hitachi_company]` - Region-specific variations
3. `[enduser_company]` - Alternative field
4. User meta fields - Final fallback

### Query Changes

The records data provider now fetches additional company-related fields:

**Added to `value_fields` array:**

'company', 'company_name', 'empresa', 'enduser_company', 'hitachi_company'

This ensures all possible company field variations are available in the submission data.

## Implementation Required

### 1. Update Submission Details Endpoint

**Location:** `hv-dashboard/hv-dashboard.php:1011`

Replace the simple `company_name` extraction with the centralized helper:

// OLD CODE (remove):
if ( isset( $submission->company_name ) ) {
    $submission_data['user_info']['company_name'] = $submission->company_name;
}

// NEW CODE (implement):
// Get company name using centralized helper function with priority order:
// 1. [company] 2. [company_name], [empresa], or [hitachi_company] 3. [enduser_company] 4. user fields fallback.
$company_name = function_exists( 'esa_extract_company_field' )
    ? esa_extract_company_field( $submission )
    : ( isset( $submission->company_name ) ? $submission->company_name : '' );
if ( ! empty( $company_name ) ) {
    $submission_data['user_info']['company_name'] = $company_name;
}

### 2. Update End User Account Fallback

**Location:** `hv-dashboard/hv-dashboard.php:1129`

Update the fallback logic for `end_user_account` to use the centralized helper:

// OLD CODE (remove):
if ( ! empty( $end_user_account ) ) {
    $submission_data['end_user_account'] = $end_user_account;
} elseif ( isset( $submission->company_name ) && ! empty( $submission->company_name ) ) {
    $submission_data['end_user_account'] = $submission->company_name;
}

// NEW CODE (implement):
if ( ! empty( $end_user_account ) ) {
    $submission_data['end_user_account'] = $end_user_account;
} else {
    // Fallback to company field using centralized helper with priority order:
    // 1. [company] 2. [company_name], [empresa], or [hitachi_company] 3. [enduser_company] 4. user fields fallback.
    $company_fallback = function_exists( 'esa_extract_company_field' )
        ? esa_extract_company_field( $submission )
        : ( isset( $submission->company_name ) ? $submission->company_name : '' );
    if ( ! empty( $company_fallback ) ) {
        $submission_data['end_user_account'] = $company_fallback;
    }
}

### 3. Update Records Data Provider Query

**Location:** `hv-dashboard/includes/Providers/class-records-data-provider.php:450`

Add company field variations to the query's `value_fields` array:

// OLD CODE:
'value_fields' => array( 'year_quarter', 'partner_account_number', 'category', 'claim_date', 'amount' ),

// NEW CODE:
'value_fields' => array( 'year_quarter', 'partner_account_number', 'category', 'claim_date', 'amount', 'company', 'company_name', 'empresa', 'enduser_company', 'hitachi_company' ),

### 4. Simplify Company Extraction in Records Loop

**Location:** `hv-dashboard/includes/Providers/class-records-data-provider.php:1052`

Replace the complex inline company extraction logic (68 lines) with the centralized helper:

// OLD CODE (remove ~68 lines of inline logic):
// Get company.
// Priority: enduser_company, company_name, empresa (LATAM), company
$company = '';
$is_latam = ( 'wpLATAM_' === $prefix );
$company_source = 'not_found';
// ... (many lines of complex extraction logic)

// NEW CODE (implement):
// Get company using centralized helper function with priority order:
// 1. [company] 2. [company_name], [empresa], or [hitachi_company] 3. [enduser_company] 4. user fields fallback.
$company = function_exists( 'esa_extract_company_field' )
    ? esa_extract_company_field( $submission )
    : '';

if ( empty( $company ) ) {
    $company = '—';
}

## Benefits

1. **Consistency:** All company field extraction uses the same logic and priority order
2. **Maintainability:** Changes to extraction logic only need to be made in one place
3. **Reliability:** Centralized testing ensures consistent behavior across all endpoints
4. **Simplification:** Removes ~68 lines of duplicated extraction logic

## Testing Requirements

After implementing these changes, the frontend team should test:

1. Company field display in submission details
2. Company field display in records listing
3. End user account fallback behavior
4. Different form variations (CANADA, LATAM, APAC) to ensure all field name variations work
5. Edge cases: missing fields, empty values, user meta fallbacks

## Related Functions

Ensure the centralized helper function `esa_extract_company_field()` is available and properly implemented in the trait file (`trait-esa-query-methods.php`).

## Questions or Issues?

Contact the backend team for clarification on the centralized helper function implementation or priority order logic.

---

**Document Version:** 1.0
**Date:** 2026-01-28
**Branch:** `fix-company-field`