Building a Reusable Excel Mapping System

I built a Laravel and React workspace that lets users connect different Excel formats to one data model, validate configurations, and reuse approved mappings for future uploads.

LaravelReactExcel mappingVersioned draftsWebSockets

The Challenge

Customer files used different column names, layouts, and value formats. Building a separate importer for every format slowed onboarding, required developer support, and made changes difficult to maintain.

The Solution

Preview and map the file

Users select the header row, review sample data, and connect each Excel column to the correct platform field through a visual workspace.

Validate and transform values

Required fields, data types, countries, dates, units, relationships, defaults, and duplicate mappings are checked before large datasets are processed.

Publish reusable versions

Mappings move through draft, published, archived, and historical states, allowing a new version to be prepared without changing the active configuration.

Handle changing file formats

A guided update compares new headers with the existing mapping, identifies added or removed columns, and keeps production uploads on the published version until approval.

Safe Collaboration

Company-level permissions keep mappings separated between organizations. Edit locks prevent two users from changing the same draft, while published and historical versions remain protected from accidental updates.

Background Processing

Large-file analysis runs through Laravel queues. Private WebSocket events notify the React interface when processing finishes, giving users immediate feedback without repeatedly polling the server.

Testing and Safeguards

  • Required fields, default values, data types, and transformations
  • Draft, published, archived, and historical versions
  • Mapping import, export, edit locks, and file-format updates
  • Company permissions and large Excel previews

Result

  • Supported different customer file structures through one workflow
  • Reduced the need for customer-specific import code
  • Made approved mappings reusable across future uploads
  • Found configuration problems before large datasets were processed
  • Allowed source formats to change without disrupting the active mapping

Key Takeaway

A reusable import system needs more than matching column names. Validation, version history, permissions, background processing, and a clear interface make the configuration safe for non-technical users.

Technologies

PHP, Laravel, React, TypeScript, Inertia.js, PostgreSQL, Laravel Queues, WebSockets, Amazon S3, Laravel Vapor, Pest, and PHPUnit.