Importing File Data

Import large numbers of files efficiently using bulk upload, CSV import, and automated tools.

Import Methods Overview

Available import methods:

1. Bulk file upload (UI)
2. CSV import with file URLs
3. FTP/SFTP batch upload
4. API programmatic import
5. Cloud storage sync

Choose based on:

< 50 files: Bulk upload (UI)
50-500 files: CSV import
500+ files: API or FTP
Ongoing: Cloud storage sync

Bulk File Upload (UI)

Using File Uploader

Upload multiple files:

Step-by-step:

1. Alva → Files → Upload Files
2. Click upload area or drag files
3. Select multiple files (Ctrl/Cmd+Click)
4. Wait for upload completion
5. Verify all files uploaded

Supported formats:

Documents: PDF, DOCX, XLSX, PPTX
Images: JPG, PNG, GIF, SVG
Video: MP4, MOV, AVI, WebM
Audio: MP3, WAV, AAC
Archives: ZIP, RAR, 7Z
Other: All file types supported

Upload Limits

File constraints:

Per-file limits:

Max file size: 5 GB per file
Recommended: < 500 MB for best performance

Larger files: Contact support for assistance

Batch limits:

Files per batch: 100 files (recommended)
Total batch size: 10 GB (recommended)

Larger batches: Split into multiple uploads

Progress Tracking

Monitor upload:

Progress indicators:

Individual files:
• File name
• Size
• Upload progress (%)
• Status (Uploading/Complete/Failed)

Overall:
• Total files: 247
• Completed: 185
• Failed: 2
• Remaining: 60
• Estimated time: 5 minutes

Handle failures:

Failed uploads:
1. Click "Retry Failed"
2. Or remove and re-add
3. Check file not corrupted
4. Verify file size within limits

CSV File Import

CSV Format

Import files via CSV:

CSV structure:

filename,file_url,product_sku,expiry_days,download_limit,tags
Chapter-1.pdf,https://example.com/files/ch1.pdf,COURSE-001,60,5,"course,chapter1"
Chapter-2.pdf,https://example.com/files/ch2.pdf,COURSE-001,60,5,"course,chapter2"
Bonus.zip,https://example.com/files/bonus.zip,COURSE-001,90,10,"course,bonus"
Ebook.pdf,https://example.com/files/ebook.pdf,EBOOK-123,30,3,"ebook,pdf"

Required columns:

filename: Display name for file
file_url: URL to download file from

Optional columns:
product_sku: Auto-map to product
expiry_days: Download expiry (default: 60)
download_limit: Max downloads (default: 5)
tags: Comma-separated tags

Creating Import CSV

Prepare CSV file:

Option 1: Spreadsheet:

1. Open Excel/Google Sheets
2. Create columns: filename, file_url, product_sku, etc.
3. Fill in data
4. Export as CSV
5. Save: file-import.csv

Option 2: Generate from list:

# Python script to generate CSV from file list
import csv
import os

files_dir = '/path/to/files/'
output_csv = 'import.csv'

with open(output_csv, 'w', newline='') as csvfile:
    writer = csv.writer(csvfile)
    writer.writerow(['filename', 'file_url', 'product_sku'])

    for filename in os.listdir(files_dir):
        if filename.endswith('.pdf'):
            file_url = f'https://example.com/files/{filename}'
            sku = filename.split('-')[0]  # Extract SKU from filename
            writer.writerow([filename, file_url, sku])

Importing CSV

Upload CSV file:

Import process:

1. Alva → Files → Import from CSV
2. Upload CSV file
3. Preview import:
   • Shows first 10 rows
   • Validates format
   • Identifies errors
4. Map columns (if not standard)
5. [Start Import]
6. Monitor progress

Validation:

✓ CSV format valid
✓ All required columns present
✓ File URLs accessible
⚠ 3 product SKUs not found
❌ 2 file URLs invalid

Errors must be fixed before import

Column Mapping

Map CSV columns:

If columns differ:

CSV Import → Column Mapping

Your CSV          → Alva Field
File Name         → filename
Download URL      → file_url
SKU               → product_sku
Days Valid        → expiry_days
Max Downloads     → download_limit
Categories        → tags

Save mapping:

☑ Save column mapping for future imports
Name: "Standard Product Import"
Reuse: Next time, mapping auto-applied

FTP/SFTP Upload

FTP Access

Enable FTP upload:

Setup FTP:

Settings → Advanced → FTP Upload
☑ Enable FTP file upload

Credentials generated:
Host: ftp.alvaapps.com
Port: 21 (FTP) or 22 (SFTP)
Username: shop_12345_upload
Password: [Generated password]

Path: /uploads/shop_12345/

Security:

⚠️ Use SFTP (port 22) for encryption
⚠️ Change password regularly
⚠️ Whitelist IP addresses (optional)

FTP Client Setup

Connect via FTP client:

FileZilla example:

1. Open FileZilla
2. Host: ftp.alvaapps.com
3. Username: shop_12345_upload
4. Password: [Generated password]
5. Port: 22 (SFTP)
6. [Quickconnect]

Upload files:

1. Local site: Browse to files folder
2. Remote site: /uploads/shop_12345/
3. Select files
4. Right-click → Upload
5. Wait for completion

Auto-Import from FTP

Automatic processing:

Configure auto-import:

Settings → Advanced → FTP Upload → Auto-Import
☑ Enable automatic import

Schedule: Every hour (default)
or: Real-time (Enterprise)

Actions:
☑ Import uploaded files automatically
☑ Match to products by filename/SKU
☑ Send notification when complete
☑ Move processed files to /processed/

File naming convention:

For auto-mapping:
{product_sku}_{filename}.pdf

Examples:
COURSE-001_chapter-1.pdf → Maps to SKU: COURSE-001
EBOOK-123_guide.pdf → Maps to SKU: EBOOK-123

No SKU: Manual mapping required

API Import

Using API for Import

Programmatic file import:

API endpoint:

POST /api/files/import
Authorization: Bearer {api_key}
Content-Type: application/json

Body:
{
  "files": [
    {
      "filename": "Chapter-1.pdf",
      "url": "https://storage.example.com/ch1.pdf",
      "product_sku": "COURSE-001",
      "expiry_days": 60,
      "download_limit": 5,
      "tags": ["course", "chapter1"]
    },
    {
      "filename": "Chapter-2.pdf",
      "url": "https://storage.example.com/ch2.pdf",
      "product_sku": "COURSE-001",
      "expiry_days": 60,
      "download_limit": 5,
      "tags": ["course", "chapter2"]
    }
  ],
  "auto_map": true,
  "notify": true
}

API response:

{
  "status": "success",
  "imported": 2,
  "failed": 0,
  "files": [
    {
      "filename": "Chapter-1.pdf",
      "file_id": "file_abc123",
      "status": "imported",
      "product_mapped": true
    },
    {
      "filename": "Chapter-2.pdf",
      "file_id": "file_def456",
      "status": "imported",
      "product_mapped": true
    }
  ],
  "job_id": "import_xyz789"
}

Batch Import Script

Example import script:

Node.js:

const fetch = require('node-fetch');
const fs = require('fs');

const API_KEY = process.env.ALVA_API_KEY;
const API_URL = 'https://yourshop.com/api/files/import';

async function importFiles(filelist) {
  const files = filelist.map(file => ({
    filename: file.name,
    url: file.url,
    product_sku: file.sku,
    expiry_days: 60,
    download_limit: 5
  }));

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      files: files,
      auto_map: true
    })
  });

  const result = await response.json();
  console.log(`Imported: ${result.imported} files`);
  console.log(`Failed: ${result.failed} files`);

  return result;
}

// Load files from JSON
const filelist = JSON.parse(fs.readFileSync('files.json'));
importFiles(filelist);

Cloud Storage Sync

Sync from Cloud Storage

Supported providers:

Available integrations:

☑ Google Drive
☑ Dropbox
☑ OneDrive
☑ Amazon S3
☑ Cloudflare R2
☑ BackBlaze B2

Google Drive Integration

Connect Google Drive:

Setup:

1. Settings → Integrations → Google Drive
2. [Connect Google Drive]
3. Authorize access
4. Select folder to sync
5. Configure sync settings

Sync settings:

Folder: /Digital Products/
Sync frequency: Every 6 hours
Subfolder handling: Create packs from subfolders
File naming: Preserve Drive filenames
Auto-map: ☑ By filename (SKU prefix)
Notification: ☑ Email on sync complete

Sync process:

1. Scan Google Drive folder
2. Detect new/changed files
3. Download to Alva storage
4. Auto-map to products (if enabled)
5. Send notification

Dropbox Integration

Connect Dropbox:

Setup:

1. Settings → Integrations → Dropbox
2. [Connect Dropbox]
3. Authorize app
4. Select folder: /Alva Digital Downloads/
5. [Start Sync]

Sync options:

☑ Two-way sync (Dropbox ↔ Alva)
○ One-way sync (Dropbox → Alva only)

Two-way:
• Upload to Dropbox → Syncs to Alva
• Upload to Alva → Syncs to Dropbox

One-way:
• Dropbox is source of truth
• Changes only flow Dropbox → Alva

Amazon S3 Sync

S3 bucket sync:

Configuration:

Settings → Integrations → Amazon S3

Bucket: your-digital-files
Region: us-east-1
Access Key: AKIA...
Secret Key: [Hidden]

Prefix: products/
Sync: Every 12 hours

Sync rules:

Include: *.pdf, *.zip, *.mp4
Exclude: *.tmp, *.log
Max file size: 5 GB
Auto-map: By S3 object key (contains SKU)

Import Settings

Default Import Settings

Configure defaults:

File defaults:

Settings → Import Settings → Defaults

Expiry days: 60 (applied to all imports)
Download limit: 5
Storage location: Primary (R2)
CDN: ☑ Enable immediately
Visibility: Private (download link required)

Product mapping:

Auto-map: ☑ Enabled
Match by:
  ☑ Product SKU in filename
  ☑ Product title match (fuzzy)
  ☐ Manual mapping only

Confidence threshold: 80% (for fuzzy matching)
Unmapped files: Leave unmapped, notify admin

Import Notifications

Get notified:

Notification settings:

Settings → Import Settings → Notifications

☑ Email when import complete
☑ Email if import errors
☐ SMS for large imports (1000+ files)

Recipients:
• shop@example.com
• manager@example.com

Email includes:
• Import summary
• Success/failure count
• Unmapped files
• Error details

Troubleshooting Imports

Common Issues

Files not importing:

Check:

1. File size within limits (< 5 GB)
2. File URL accessible (test in browser)
3. Correct file format
4. Network connection stable
5. Storage quota available

Test file URL:

curl -I https://example.com/files/test.pdf

Expected: 200 OK
If 404: File not found
If 403: Access denied (check permissions)

CSV import errors:

Error: "Invalid CSV format"
Solution: Check CSV structure, ensure proper commas, no missing fields

Error: "File URL not accessible"
Solution: Verify URLs return 200 OK, not 404/403

Error: "Product SKU not found"
Solution: Verify SKU exists in Shopify, check for typos

Error: "Duplicate filename"
Solution: Rename files to be unique, or enable overwrite

FTP upload issues:

Problem: Can't connect to FTP
Solution:
1. Verify credentials correct
2. Check firewall not blocking port 21/22
3. Use SFTP (port 22) not FTP (port 21)
4. Test with different FTP client

Problem: Upload stalls/timeout
Solution:
1. Use smaller batches
2. Check internet connection
3. Enable passive mode
4. Try during off-peak hours

Import Validation

Pre-Import Validation

Validate before importing:

Validation checks:

1. File accessibility
2. File size within limits
3. Format supported
4. Product SKUs exist
5. No duplicate filenames
6. Metadata valid

Validation report:

Total files: 247
✓ Valid: 240
⚠ Warnings: 5 (large files)
❌ Errors: 2 (invalid URLs)

Errors:
• file_123.pdf: URL returns 404
• file_456.zip: File size exceeds 5GB

Warnings:
• file_789.mp4: Large file (3.2GB), upload may take time

Action: Fix errors before proceeding

Post-Import Verification

Verify import success:

Check:

☐ All files imported
☐ Files mapped to correct products
☐ Download links work
☐ Expiry/limits set correctly
☐ Tags applied
☐ No corrupted files

Test downloads:

1. Select random sample (10 files)
2. Generate download links
3. Download files
4. Verify file integrity
5. Check file opens correctly

Best Practices

1. Organize Files Before Import

Preparation:

✓ Consistent naming convention
✓ Include SKU in filename (for auto-mapping)
✓ Group related files in folders
✓ Remove unnecessary files
✓ Optimize file sizes

Naming convention:

Good:
COURSE-001_Chapter-1.pdf
COURSE-001_Chapter-2.pdf
EBOOK-123_Guide.pdf

Bad:
file1.pdf
download.pdf
untitled_final_FINAL_v3.pdf

2. Import in Batches

Batch strategy:

Small batches (< 100 files): Less risk, easier to fix issues
Test batch first: Import 5-10 files, verify, then full import

Benefits:

• Faster individual imports
• Easier error handling
• Can pause between batches
• Less strain on system

3. Use CSV for Large Imports

Why CSV:

✓ Easy to review before import
✓ Can edit in spreadsheet
✓ Reusable for future imports
✓ Version control friendly
✓ Audit trail

4. Validate Before Importing

Pre-import validation:

✓ Test file URLs
✓ Verify product SKUs exist
✓ Check file sizes
✓ Ensure no duplicates
✓ Preview in small batch

Saves time: Catching errors before import

5. Document Your Process

Documentation:

✓ CSV template used
✓ Naming convention
✓ Import settings
✓ Date of import
✓ Success metrics
✓ Issues encountered

Why: Reproducible imports, troubleshooting reference

Next Steps

Migrating from Other Apps - Migration guide
Bulk File Operations - Managing files in bulk
Data Migration Best Practices - Advanced tips