Import Loans

What This Page Does

The Import Loans page (import-loans.php) provides a 3-step wizard for bulk-importing loan records via CSV, XLSX, or XLS file upload. Each row is matched to an existing customer using their IPPS number, validated, and inserted into the loans table with auto-generated serial numbers.

The page handles both GET (render the UI) and POST (AJAX actions) in a single file. POST requests are detected immediately on load via $_SERVER['REQUEST_METHOD'], and JSON output is locked down before any includes can contaminate the response.

Page Structure

The page renders three step panels (#step1, #step2, #step3) only one of which is visible at a time. A visual progress bar above them reflects the current step state (active / done).

API Endpoints

Both actions are self-hosted — they POST to the current page URL ('' in the JS fetch). The action field in the FormData body distinguishes the operation.

A Preview Request Fields

B Import Request Fields

Step 1 — Configure

The opening step collects the three inputs required before parsing can begin: target branch, optional ministry override, and the file itself. The Preview button remains disabled until both branch and file are set — enforced by checkBtn() which runs on every change event.

A Branch Selection

Selecting a branch fires onBranchChange(). This reads branchMinistry[branchId] — a PHP-injected JS map of branch_id → ministry_fk — and auto-selects the linked ministry in the ministry dropdown. The ministry selection then triggers onMinistryChange() to display the rate badge.

function onBranchChange(sel) {
  checkBtn();
  const branchId  = parseInt(sel.value) || 0;
  const linkedMin = branchMinistry[branchId] || 0;
  const minSel    = document.getElementById('ministrySelect');

  if (linkedMin && minSel) {
    minSel.value = linkedMin;
    onMinistryChange(minSel, true); // fromBranch=true → different hint text
  }
}

B Ministry Override

When a ministry is selected (either manually or via branch auto-fill), onMinistryChange() highlights the dropdown with an override-active CSS class, updates the hint text, and shows a rate badge displaying the ministry's min_percent value sourced from the ministryData JS map.

C File Drop Zone

Accepts CSV, XLSX, and XLS files up to 5 MB. Supports both click-to-browse and drag-and-drop. On drop, the file is injected into the hidden <input type="file"> via a DataTransfer object so the same fileSelected() handler path runs for both methods.

Step 2 — Preview

Triggered by clicking "Preview Import". The JS doPreview() function builds a FormData object, immediately transitions to Step 2, shows a skeleton loading state, and POSTs to action=preview. The PHP handler parses the file, matches every IPPS against the customers table, resolves ministry/rate/branch, computes loan financials, and returns a JSON array of preview row objects.

A Stats Strip

B Preview Table Columns

C Error Export

If any rows have errors, a "Export Errors" button appears. Clicking it calls downloadErrors() which builds a CSV in memory from all error rows and triggers a browser download as import_errors.csv. No server round-trip needed.

Step 3 — Confirm & Import

Navigating to Step 3 calls buildSummary(ok) which computes total loan value and renders a summary grid. Only rows with status === "ok" are counted here; error rows are silently excluded.

A Summary Grid

Five cells: Loans to Import (count), Total Loan Value (₦ formatted), Target Branch, Ministry, and Interest Rate. If any rows will be skipped, a gold warning box below the grid states how many and why.

B Import Execution

Clicking "Import Now" calls doImport(). A simulated progress bar increments to 88% every 60 ms while the fetch is in-flight, then jumps to 100% on completion. The import button and Back button are both hidden once the import completes to prevent double-submission via the importDone guard flag.

async function doImport() {
  if (importDone) return;   // guard against double-click
  // ...
  importDone = true;          // set immediately on success
  document.getElementById('importActions').style.display = 'none';
}

C Result Panel

On success, showResult('success', count, msg) renders a large ✓ count, a subtitle with the success message, and two action buttons — "View All Loans" (link to loans.php) and "Import More" (reloads the page). On failure, a ✗ panel with the error message is shown instead.

Resolution Priority

Ministry, interest rate, and branch can each come from multiple sources. The PHP preview handler applies a strict priority chain so the most-specific source always wins.

A Ministry Resolution

B Interest Rate Resolution

// Priority 1: explicit CSV column
$loan_pct_raw = trim($r['loan_percentage'] ?? $r['interest_rate'] ?? '');

// Priority 2 + 3: ministry rate or default
$loan_pct = (is_numeric($loan_pct_raw) && floatval($loan_pct_raw) > 0)
    ? $loan_pct_raw
    : $min_pct;   // $min_pct already resolves ministry → default

C Branch Resolution

The global branch selected in the UI is the default for all rows. A per-row branch column (name or code) can override this for individual rows — the PHP handler looks it up in a $branchMap keyed by both strtolower(branch_name) and strtolower(branch_code). If no per-row branch column exists, the global branch ID is used.

Serial Generation

Loan serials are auto-generated — they must not be included in the CSV file. Each serial is unique within the company and sequential from the current loan count.

// Format: YYYYMMDD-{comp_id padded 3}-{count padded 6}
$serial = date('Ymd')
  . '-'
  . str_pad($cp_id, 3, '0', STR_PAD_LEFT)
  . str_pad($loanCount, 6, '0', STR_PAD_LEFT);
$loanCount++;   // increments for each row in the loop

Example: 20250115-002-000047 — company 2, the 47th loan. The preview step pre-assigns serials so they are visible before confirmation, but the import step re-generates them fresh (starting from the live count at import time) to account for any loans added between preview and confirm.

CSV Column Reference

Column names are trimmed and matched case-insensitively. A BOM (\xEF\xBB\xBF) is stripped from the first column header automatically. Alternate aliases (ipps_number, net_pay, interest_rate, etc.) are also accepted.

Preview Row Schema

Each object in the rows array returned by action=preview — and stored in the JS previewRows variable — has the following shape.

Database Insert Fields

The action=import handler inserts into the loans table using a prepared statement with 22 bound parameters. All loans are inserted with loan_status = 'disbursed'.

JavaScript State Variables

JavaScript Functions

Error Handling

Errors are classified into three categories: row-level validation errors (block import), row-level warnings (non-blocking), and request/server errors (block the entire action).

A Row Validation Errors

B Row Warnings

C Server / Request Errors