vendure-data-hub-plugin

Import and Export Wizards

Step-by-step guides for using the visual wizards to import and export data.

Table of Contents

Overview

Data Hub provides visual wizards for common import and export tasks, eliminating the need to write code for simple data operations.

When to Use Wizards

Use Wizards:

Use Pipelines:

Accessing Wizards

  1. Navigate to Data Hub in the Vendure admin
  2. Click Import Wizard or Export Wizard
  3. Follow the step-by-step interface

Import Wizard

Import data from files or external sources into Vendure entities.

Step 1: Choose Template

Select a pre-built template or start from scratch.

Import Templates

Available Templates:

Starting from Scratch: Click Custom Import to configure manually.

Step 2: Select Source

Choose where your data comes from.

File Upload

  1. Click Upload File
  2. Select file (CSV, JSON, XML, XLSX)
  3. Configure format options

CSV Options:

JSON Options:

XML Options:

Excel Options:

HTTP API

  1. Enter API URL
  2. Configure authentication
  3. Set data path
  4. Configure pagination (if needed)

Database

  1. Select connection
  2. Choose table or enter SQL query
  3. Preview data

FTP/SFTP

  1. Select connection
  2. Enter file path
  3. Configure format

Step 3: Preview Data

Review first 10 rows of source data.

Data Preview

Actions:

Step 4: Select Target Entity

Choose the Vendure entity to import into.

Available Entities:

Step 5: Map Fields

Map source fields to target entity fields.

Field Mapping

Auto-Mapping

Click Auto-Map to automatically match fields by name.

Matches:

Manual Mapping

Drag source fields to target fields or use dropdowns.

Required Fields (marked with *):

Optional Fields:

Field Transformations

Apply transformations during mapping:

  1. Click Transform icon
  2. Select transformation type
  3. Configure options

Available Transformations:

Example: Create slug from name

Source: name = "Product Name"
Transform: slugify
Result: slug = "product-name"

Step 6: Configure Import Options

Set how data should be imported.

Strategy

CREATE:

UPDATE:

UPSERT:

MERGE:

Match Field

Field used to find existing records (for UPDATE/UPSERT):

Conflict Resolution

When source and Vendure data differ:

SOURCE_WINS:

VENDURE_WINS:

MERGE:

MANUAL_QUEUE:

Validation Mode

STRICT:

LENIENT:

Step 7: Configure Batching

Control import performance.

Batch Size:

Concurrency:

Example Settings:

Scenario Batch Size Concurrency
Small import (< 1000) 100 2
Large import (> 10,000) 500 4
Complex products 50 2
Simple customers 200 4

Step 8: Validation and Preview

Validate data before importing.

Validation

Validation Checks:

Preview Changes:

Actions:

Step 9: Execute Import

Run the import and monitor progress.

Execution

Progress Indicators:

Real-Time Logs:

Actions During Import:

Step 10: Review Results

View import results and handle errors.

Results

Summary:

Failed Records:

Actions:

Export Wizard

Export Vendure data to files or external systems.

Step 1: Choose Template

Select export template or create custom export.

Available Templates:

Step 2: Select Source Entity

Choose what to export.

Available Entities:

Filters: Add filters to export subset of data:

Example Filters:

Entity: Product
Filters:
  - enabled = true
  - createdAt > 2024-01-01
  - tags contains 'featured'

Step 3: Select Fields

Choose which fields to include in export.

Field Selection

Field Selection:

Related Entities:

Step 4: Configure Format

Choose output format and options.

CSV

Options:

JSON

Options:

XML

Options:

Excel (XLSX)

Options:

Step 5: Configure Destination

Choose where to send exported data.

Download

Export to browser download:

File System

Save to server:

FTP/SFTP

Upload to remote server:

S3

Upload to cloud storage:

Email

Send via email:

Step 6: Execute Export

Run export and download results.

Progress:

Actions:

Step 7: Review and Download

Download exported file.

Summary:

Actions:

Templates

Save and reuse import/export configurations.

Creating Templates

  1. Complete wizard configuration
  2. Click Save as Template
  3. Enter template details:
    • Name
    • Description
    • Category
    • Visibility (Private/Shared)

Using Templates

  1. Start wizard
  2. Select template
  3. Optionally customize
  4. Execute

Managing Templates

Navigate to Data Hub > Templates

Actions:

Field Mapping

Advanced field mapping techniques.

Default Values

Set default values for unmapped fields:

Field: enabled
Default: true

Computed Values

Use expressions to compute values:

Field: slug
Expression: ${sku}.toLowerCase()

Conditional Mapping

Map different sources based on conditions:

Field: price
If: has_sale_price
  Then: sale_price
  Else: regular_price

Array Handling

Map array fields:

Source: tags (comma-separated)
Transform: Split by ','
Target: tags (array)

Look up related entities:

Field: collection
Lookup: Collection
Match By: slug
Source Field: collection_slug

Validation and Preview

Validation Rules

Built-in Rules:

Custom Rules: Add custom JavaScript validation:

// Validate SKU format
function validateSKU(value) {
    return /^[A-Z0-9-]{4,20}$/.test(value);
}

Preview Changes

Before importing, preview what will happen:

Created Records:

Updated Records:

Errors:

Troubleshooting

Common Issues

Issue: Import fails with “Required field missing”

Solution:

  1. Check field mappings
  2. Ensure required fields are mapped
  3. Or set default values for required fields

Issue: “Duplicate key” error during import

Solution:

  1. Check match field is correct
  2. Verify source data has unique values
  3. Or use CREATE strategy to skip duplicates

Issue: Slow import performance

Solution:

  1. Increase batch size (500-1000)
  2. Reduce concurrency if database is bottleneck
  3. Disable validation in lenient mode
  4. Import during off-peak hours

Issue: Some fields not updating

Solution:

  1. Check conflict resolution strategy
  2. Use SOURCE_WINS instead of VENDURE_WINS
  3. Or use MERGE to update only changed fields

Issue: Date/time parsing errors

Solution:

  1. Specify date format in transformation
  2. Common formats:
    • YYYY-MM-DD
    • DD/MM/YYYY
    • MM/DD/YYYY HH:mm:ss

Issue: Export times out

Solution:

  1. Add filters to reduce dataset
  2. Export in smaller batches
  3. Schedule export during off-peak hours
  4. Increase export timeout in settings

Getting Help

Best Practices

Import Best Practices

  1. Start Small
    • Test with 10-100 records first
    • Verify results before full import
  2. Validate First
    • Always run validation
    • Fix errors before importing
  3. Use Templates
    • Save successful configurations
    • Reuse for similar imports
  4. Backup Data
    • Backup database before large imports
    • Export current data for rollback
  5. Monitor Progress
    • Watch for errors during import
    • Pause if error rate is high

Export Best Practices

  1. Use Filters
    • Only export needed data
    • Reduces file size and time
  2. Schedule Large Exports
    • Run during off-peak hours
    • Avoid impacting store performance
  3. Choose Appropriate Format
    • CSV for tabular data
    • JSON for nested data
    • Excel for business users
  4. Secure Sensitive Data
    • Encrypt exports containing PII
    • Use secure transfer methods (SFTP, S3)
    • Delete temporary files

See Also

This site is open source. Improve this page.