Content Import Panel
The Content Import Panel is a self-service dashboard in Medusa where publishers upload and manage digital content for ingestion into Publica.la. It replaces the previous workflow that required SFTP clients and manual coordination with our team.
Publishers access the panel at their assigned Medusa URL, upload content files and a metadata spreadsheet, and launch the import. The system validates, processes, and ingests everything into Farfalla automatically.
Who uses it
| Role | Access | What they do |
|---|---|---|
| Publisher team members | Medusa dashboard (Livewire) | Upload files, manage imports, replace content |
| Publica.la admins | Medusa Nova | Create teams, assign API keys, configure content intakes |
Key concepts
- Content Intake: A configured content source for a tenant. Each intake has its own S3 bucket and Farfalla API key. Admins create these via Nova.
- Team: A group of users that share a single Farfalla API key. All content imported by any team member is visible to the entire team.
- Import: A single import session consisting of uploaded files plus a metadata spreadsheet. Each import tracks its own status and history.
- Import Record: One row from the spreadsheet, representing a single product to ingest.
Dashboard sections
The panel has four main sections, accessible from the left sidebar:
New Upload
This is the primary workflow. It has two steps presented as accordion sections:
Step 1: Upload content files
- Drag and drop or browse to select files (EPUB, PDF, MP3, JPG, PNG)
- Files upload directly from the browser to S3 via presigned URLs (no server relay)
- Progress bar per file with real-time status
- Up to 500 files per import, 500 MB per file
- Concurrent uploads (configurable, default 5 simultaneous)
Step 2: Upload metadata spreadsheet
- Accepts XLSX, XLS, or CSV (max 10 MB, up to 10,000 rows)
- The system auto-detects the spreadsheet format (Publica.la or VitalSource)
- Shows a preview of the first 5 rows for confirmation
- Header validation requires at least 60% of expected columns to match
- Users can override the auto-detected format if needed
Validation and launch
After both uploads complete, the system validates:
- All files referenced in the spreadsheet exist in the upload
- No duplicate external IDs against previously ingested products
- Required fields are present (title, file type)
- File types are valid (epub, pdf, mp3, physical)
If validation finds errors, the panel displays the top 50 issues. The user can fix and re-upload, or choose Continue with errors to skip invalid rows and proceed with valid ones only.
Clicking Start Import creates import records in batches of 500 and dispatches processing jobs.
Import History
A table listing all imports for the current content intake.
| Column | Description |
|---|---|
| Date | When the import started |
| Type | Import or File Update |
| Spreadsheet | Original filename |
| Format | Publica.la or VitalSource |
| Items | Total records in the spreadsheet |
| Status | Done, Failed, Partial, Processing |
| Duration | Time from start to completion |
| User | Email of the team member who launched it |
Status indicators:
- Green (Done): All records ingested successfully
- Red (Failed): Import failed entirely
- Amber (Partial): Some records succeeded, some failed
- Blue (Processing): Import is still running
Expanding a row shows additional detail:
- While processing: Progress bar with counts (created/errors/remaining), live polling every 5 seconds
- After completion: Final stats, first 10 error messages, and a Download CSV button for the full report
The CSV report includes: Row number, External ID, Title, File Type, Status, Error Message.
Products
A table of all successfully ingested products for the team, sorted by ingestion date (newest first). This section shows the cumulative result of all imports.
Columns: ISBN/External ID, Title, Upload date, Uploaded by.
Paginated (20 per page).
File Update
Allows replacing content files (EPUB, PDF, MP3) for products that were already imported. Two main use cases:
- Dummy to original: Teams that import with placeholder files first (to get metadata in quickly) and replace with final binaries later
- Content correction: Replacing a file to fix errata or publish a new edition
Flow:
- Upload replacement files (same process as New Upload file section)
- The system matches files to existing products by external ID
- Validation confirms the external ID exists and the product was previously ingested
- The replacement triggers a full re-ingestion in Farfalla (not just a file swap; all derivatives like Smart Zoom and pagination are regenerated)
Spreadsheet formats
Publica.la format
The standard Publica.la spreadsheet. Required columns:
| Column | Description | Example |
|---|---|---|
| ISBN | External identifier | 978-84-123-4567-8 |
| Type | File format | epub, pdf, mp3, physical |
| Name | Product title | The Butterfly Garden |
| File URL | Filename or full URL | butterfly.epub |
| Lang | Language code | es, en, pt |
| Prices | Currency:amount pairs | USD:19.99|BRL:89.90 |
| Authors | Author names | Author One|Author Two |
| Publishers | Publisher name | Editorial ABC |
Optional columns: Description, Publication Date, Cover File URL, Keywords, Narrators, Categories, Audience, Free, Retail Enabled, Countries, Collections, Editions, Allow Preview.
Custom metadata is supported via taxonomy_* columns (e.g., taxonomy_genre, taxonomy_age_group). Values are passed through to Farfalla as custom taxonomies.
List separators: Use |, ;, or , to separate multiple values in a single cell.
Price format: CurrencyCode:Amount pairs separated by |. Example: ARS:1000|USD:20|BRL:89.90.
Date format: The system accepts DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD, and Excel serial dates. All are normalized to YYYY-MM-DD.
VitalSource format
Used for content migrated from VitalSource catalogs. This format uses a 3-row header structure:
- Row 1: Group headers (e.g., "Basic", "Asset Identifiers")
- Row 2: Column headers (used for field mapping)
- Row 3: System names (skipped during parsing)
Required columns:
| Column | Description |
|---|---|
| VBID | VitalSource Book ID (external identifier) |
| Title | Product title |
| Imprint | Publisher imprint |
| Kind | Content type |
| Print ISBN | Print edition ISBN |
| E ISBN | Digital edition ISBN |
| Author Name | Author |
| Edition | Edition number/name |
| Language | Language code |
| Publication Date | Publication date |
Optional: Price columns per currency (USD Digital List Price, GBP Digital List Price), BISAC codes, sales rights, sampling settings, description.
File matching: In VitalSource format, files are matched by VBID prefix. For example, a file named L-999-70114.epub matches the row with VBID L-999-70114. Multiple files per VBID are supported (one content file plus an optional cover image).
Teams and access control
All operations in the Import Panel are scoped by team. A team groups users who share a single Farfalla API key; content imported by any member is visible to the entire team. Roles include Admin, Team Member, and Viewer.
For the full access model, onboarding flow, and Nova admin setup, see Teams and Access Control.
Limits and configuration
| Parameter | Default | Description |
|---|---|---|
| Max files per import | 500 | Maximum content files in a single upload session |
| Max file size | 500 MB | Per-file size limit |
| Max spreadsheet rows | 10,000 | Maximum rows in the metadata spreadsheet |
| Max spreadsheet size | 10 MB | File size limit for XLSX/XLS/CSV |
| Batch size | 50 | Records sent per API call to Farfalla |
| Upload concurrency | 5 | Simultaneous file uploads to S3 |
| Retry attempts | 3 | Maximum retries on server/rate-limit errors |
| Retry delay | 30 seconds | Wait time between retries |
| Presigned URL TTL | 60 minutes | Validity of S3 upload URLs |
| Stale import threshold | 5 minutes | Time before stuck imports are auto-rescued |
Related documentation
- Teams and Access Control: Multi-tenant access model, roles, and admin setup
- ONIX Intake Overview: Automated ONIX XML processing (separate pipeline)
- Setting Up a New ONIX Intake: Nova configuration for ONIX intakes
- Upload Methods: Overview of all content upload methods in Publica.la