File Import

The File Import feature allows customers to upload CSV or Excel files containing shipment data and automatically create draft declarations. This is ideal for customers with ERP systems, regular shipments, or large volumes of declarations.

Overview

File Import works in three steps:

1. Upload File: Upload a CSV or Excel file with your shipment data
2. Map Columns: Create or select a mapping template to match your file columns to declaration fields
3. Import: Process the file and create draft declarations

Supported File Formats

• CSV: Comma-separated values (.csv)
• Excel: Microsoft Excel workbooks (.xlsx, .xls)
• Encoding: UTF-8 (recommended), ISO-8859-1, Windows-1252

File Requirements

• Header Row: First row must contain column names
• Data Rows: Each subsequent row represents one declaration or declaration line
• Max File Size: 10MB (approximately 50,000 rows)
• Max Rows: 10,000 declarations or 100,000 lines per file

Creating a Mapping Template

Mapping templates define how columns in your file correspond to fields in a declaration. You can create multiple templates for different file formats.

Step 1: Upload Sample File

1. Navigate to File Import > Mapping Templates
2. Click “Create New Mapping”
3. Upload a sample file (CSV or Excel)
4. Give the mapping a descriptive name (e.g., “ERP Export Format”, “Monthly Import Shipments”)

Step 2: Map Header Fields

Map file columns to declaration header fields:

Step 3: Map Line Fields

Map file columns to declaration line fields:

Step 4: Set Data Types and Defaults

For each mapped field, you can:

• Data Type: Text, Number, Date, Boolean
• Format: Date format (e.g., YYYY-MM-DD, DD/MM/YYYY)
• Default Value: Use if column is empty (e.g., default country = “NL”)
• Transformation: Trim whitespace, uppercase, lowercase

Step 5: Configure Grouping

Tell the system how to group rows into declarations:

Option A: One Declaration per Row

• Each row in the file creates a separate declaration with one line

Option B: Group by Reference

• Rows with the same reference value are grouped into one declaration with multiple lines
• Example: All rows with reference = "INV-001" become one declaration

Option C: Group by Custom Field

• Specify which column to use for grouping
• Example: Group by shipment_id or container_number

Step 6: Save and Test

1. Save the mapping template
2. Click “Test Mapping” to upload a test file
3. Review the preview showing how data will be imported
4. Adjust mapping if needed
5. Finalize the template

Importing Files

Once you have a mapping template, you can import files:

Step 1: Upload File

1. Navigate to File Import > Import File
2. Click “Upload File” and select your CSV or Excel file
3. Select the appropriate mapping template
4. Choose import options

Step 2: Review Preview

The system shows a preview of the data to be imported:

• Number of Declarations: How many declarations will be created
• Number of Lines: Total declaration lines
• Validation Errors: Any issues found in the data
• Sample Data: First few rows showing mapped fields

Step 3: Configure Import Settings

Declaration Type

• Select the default declaration type (H1, H7, B1, B4, etc.)
• Can be overridden if your file includes a declaration type column

Declarant

• Choose which declarant to use (auto-filled from your profile)

Draft Status

• Create as “In Progress” (you can review before submitting)
• Create as “Submitted” (immediately send to customs broker)

Error Handling

• Skip Invalid Rows: Continue import, skip rows with errors
• Stop on Error: Cancel entire import if any row has errors

Step 4: Start Import

Click “Start Import” to process the file. The system will:

1. Validate all data against declaration rules
2. Create draft declarations and lines
3. Associate with your customer account
4. Show a summary of the import

Import Progress

For large files, import runs in the background. You’ll see:

• Progress Bar: Percentage complete
• Rows Processed: Number of rows imported
• Errors: Count of errors encountered
• Estimated Time: Time remaining

You can navigate away and return later to check progress.

Import Results

After import completes, you’ll see a summary:

Success

• Number of declarations created
• Number of lines created
• Total value of all declarations

Errors

• Number of rows skipped
• Error details for each failed row
• Download error report (CSV)

Actions

• View created drafts
• Download import log
• Export successful imports to CSV

Common File Import Errors

Invalid Commodity Code

Error: “Invalid commodity code: 123456”

Solution: Ensure HS codes are 8-10 digits and valid in the tariff database.

Missing Required Field

Error: “Consignee name is required”

Solution: Ensure all required fields are present in your file or use default values in the mapping.

Invalid Date Format

Error: “Invalid date: 15/03/2024”

Solution: Use the correct date format in your mapping (e.g., DD/MM/YYYY).

Duplicate References

Error: “Declaration with reference INV-001 already exists”

Solution: Use unique references or enable “Allow Duplicate References” in import settings.

Invalid Country Code

Error: “Invalid country code: Germany”

Solution: Use ISO 2-letter country codes (DE, not Germany).

Invalid Currency

Error: “Invalid currency: Euros”

Solution: Use 3-letter currency codes (EUR, not Euros).

Best Practices

File Preparation

1. Use Consistent Formats: Keep date, number, and code formats consistent across files
2. Include Headers: Always include a header row with column names
3. Validate Data: Check for missing required fields before uploading
4. Test with Small Files: Test new mappings with small files before importing thousands of rows

Mapping Templates

1. One Template per Format: Create separate templates for each file format/source
2. Descriptive Names: Use clear names like “ERP-Export-Monthly” not “Mapping1”
3. Document Fields: Add notes to your template explaining what each column contains
4. Version Templates: When changing formats, create a new template version

Import Strategy

1. Import as In Progress: Create drafts in “In Progress” status to review before submitting
2. Batch Processing: Import files in batches of 1000-2000 rows for better performance
3. Schedule Imports: Import during off-peak hours for large files
4. Archive Files: Keep copies of imported files for audit purposes

Integration with ERP Systems

If you have an ERP system (SAP, Oracle, Microsoft Dynamics, etc.):

1. Export to Standard Format: Configure your ERP to export in a consistent CSV/Excel format
2. Create Mapping Template: Create a template matching your ERP export
3. Automate Export: Set up scheduled exports from your ERP (daily, weekly, etc.)
4. Import via API: Use the Borderbolt API to automate file uploads and imports

For API integration, see API Documentation.

File Import vs AI Import

Use File Import when:

• You have structured data in CSV/Excel format
• You regularly ship similar goods
• You have an ERP system or database
• You need to import many declarations at once

Use AI Import when:

• You have PDF documents (invoices, packing lists)
• Data is unstructured or varies in format
• You have one-off or occasional shipments
• You want to extract data automatically from documents

Both methods create draft declarations that you can review before submitting to your customs broker.

Next Steps

• AI Import - Use AI to extract data from PDF documents
• Portal Drafts - Review and manage imported drafts
• API Integration - Automate file imports via API