README

Description

Data Import adds template-driven spreadsheet imports to Enso.

The package validates uploaded files against JSON template definitions, splits work into queued jobs, tracks import progress and status, generates rejected-row workbooks when needed, and exposes the API endpoints required by the Enso import UI.

It supports multi-sheet XLSX imports as well as CSV and TXT imports, with configurable structure validation, queue separation, and retention policies.

Seeder-style imports can also resolve the acting Enso user through the configurable seederUserId setting, which is useful when imports are executed outside a regular authenticated request.

Installation

Install the package:

composer require laravel-enso/data-import

Run the package migrations:

php artisan migrate

Optional publishes:

php artisan vendor:publish --tag=data-import-config
php artisan vendor:publish --tag=data-import-factory
php artisan vendor:publish --tag=data-import-mail
php artisan vendor:publish --tag=data-import-examples

'configs' => [
    'userGroups' => [
        'label' => 'User Groups',
        'template' => 'app/Imports/Templates/userGroups.json',
    ],
],

If you use seed-style imports that need a tracked Enso user, configure the fallback user id:

'seederUserId' => env('DATA_IMPORT_SEEDER_USER_ID', 1),

The ExcelSeeder service uses this value to resolve the user passed into import hooks and track-who aware models when there is no authenticated session.

The package schedules these maintenance commands daily:

enso:data-import:purge
enso:data-import:cancel-stuck

Features

Template-driven import definitions using JSON files.
Queue-based splitting and processing for large imports.
Support for xlsx, csv, and txt uploads.
Strict or flexible structure validation.
Rejected-row report generation with an extra errors column.
Shared mail layout and preview registration through laravel-enso/mails, including a download link for uploaded import files.
Downloadable import templates generated from the JSON definition.

Usage

Create an importer class that implements the package contract:

use LaravelEnso\DataImport\Contracts\Importable;
use LaravelEnso\DataImport\Models\Import;
use LaravelEnso\Helpers\Services\Obj;

class UserGroupImporter implements Importable
{
    public function run(Obj $row, Import $import)
    {
        UserGroup::create($row->all());
    }
}

Point a template configuration entry to a JSON template that defines sheets, columns, and the importer class. The package can then:

serve the generated template workbook
validate uploaded files against the template
queue the import when the structure is valid

When the import runs through the seeder-oriented flow, the package resolves the acting user from config('enso.imports.seederUserId'). Set DATA_IMPORT_SEEDER_USER_ID to an Enso user that should own created records, approvals, and audit metadata produced by those imports.

API

HTTP routes

POST api/import/store
DELETE api/import/{import}
GET api/import/download/{import}
GET api/import/initTable
GET api/import/tableData
GET api/import/exportExcel
PATCH api/import/{import}/cancel
PATCH api/import/{import}/restart
GET api/import/options
GET api/import/{type}
GET api/import/{type}/template
GET api/import/{rejected}/rejected

Artisan commands

enso:data-import:purge
enso:data-import:cancel-stuck

Extension points

Importable
BeforeHook
AfterHook
Authenticates
Authorizes

Deferred imports

Pass startNow: false to upload() or attach() when the file should be validated and stored before the import is started explicitly.

External finalization

Override finalizesExternally() on the import model when the consuming application owns finalization after the package finishes processing the rows.

Depends On

Required Enso packages:

Required external package:

openspout/openspout ↗

Companion frontend package:

@enso-ui/data-import ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!

laravel-enso / data-import

Maintainers

Package info

Statistics

Security