Skip to main content
Skip to main content
User Guides

Material Imports

Learn how to efficiently manage your materials catalog through bulk imports and updates using CSV files.

Overview​

The Material Import feature provides a powerful way to manage large numbers of materials efficiently. This tool helps you:

  • Add or update hundreds of materials at once
  • Maintain data consistency across your catalog
  • Save time compared to manual entry
  • Process changes in the background
  • Track and verify all updates

Key Features​

  • Bulk Operations: Handle multiple materials in a single operation
  • Background Processing: Continue working while imports run
  • Progress Tracking: Monitor import status and results
  • Data Validation: Ensure data accuracy before import
  • Flexible Updates: Create new or update existing materials

Benefits​

Time Efficiency​

  • Reduce manual data entry
  • Process large catalogs quickly
  • Update multiple fields at once
  • Automate repetitive tasks
  • Handle bulk changes efficiently

Data Quality​

  • Consistent data formats
  • Validated information
  • Complete material records
  • Accurate relationships
  • Traceable updates

Prerequisites​

Before starting an import, ensure you have:

  • Valid Material Groups in your store
  • Valid Units of Measure (UOM) in your store
  • Your material data prepared in CSV format
TIP

The import will fail if referenced Material Groups or UOMs don't exist in your store.

Importing Materials​

To import materials:

  1. Select Inventory from the landing page dropdown
Accessing Inventory section
  1. Click Import on the Materials landing page
Opening import section
  1. Download and fill out the template
Downloading template
  1. Upload your completed CSV file
Uploading CSV file
  1. Map your fields and click Continue
Mapping CSV fields
  1. Review your data and click Submit
Reviewing and submitting import

CSV Template Fields​

Required Fields​

FieldDescription
nameDescriptive name that clearly identifies the material
material_identifierUnique identifier used for updates - must be consistent across systems
material_group_nameValid group name from your store - organizes materials logically
unit_of_measure_nameValid UOM from your store - ensures consistent quantity measurements

Optional Fields​

FieldDescription
descriptionDetailed description of material characteristics and usage
material_type_nameMust match existing type - defines material properties and validation
requires_batch_identifierSet to "true" for batch-tracked materials, "false" otherwise
requires_serial_identifierSet to "true" for serialized materials, "false" otherwise
image_url_1 to image_url_5Valid URLs for material images - helps with visual identification
barcode_type_1/value_1 to type_5/value_5Pairs of barcode type and value for material tracking
property_name_1/value_1 to name_5/value_5Custom property pairs for additional material attributes
common_part_number_1 to number_5Alternative part numbers for cross-referencing

Field Guidelines​

Material Names​

  • Use clear, descriptive names
  • Follow consistent naming conventions
  • Include relevant specifications
  • Avoid abbreviations unless standard
  • Keep names concise but meaningful

Identifiers​

  • Use consistent identifier formats
  • Ensure uniqueness across systems
  • Include relevant prefixes if needed
  • Document identifier structure
  • Maintain identifier history

Groups and Types​

  • Verify group existence before import
  • Use correct group names exactly
  • Match type names precisely
  • Consider group hierarchies
  • Plan for future categorization

Custom Properties​

  • Use standardized property names
  • Provide complete property pairs
  • Follow value format requirements
  • Document property purposes
  • Consider reporting needs
TIP

For barcode types, use standard formats like QR Code, PDF417, Data Matrix, Code 39, Code 128, GS1-128, EAN-8/13, UPC-A/E.

Import Process​

During import:

  1. Each row is validated for required fields and data format
  2. System checks material_identifier:
    • New identifiers create materials
    • Existing identifiers update materials
  3. Images, barcodes, and properties are applied
  4. Results are available in the import history

Update Behavior​

When updating existing materials:

  • Barcodes are completely replaced with new values
  • Image URLs are refreshed from the CSV
  • Properties are replaced with new values
  • Material type changes may be blocked if required fields exist

Troubleshooting​

Common errors and solutions:

  • "Material group does not exist": Create the group first
  • "Unit of measure does not exist": Add the UOM first
  • "Material type does not exist": Fix the type name or leave blank
  • Invalid barcode type: Use standard format
  • Boolean fields: Use exactly "true" or "false"
  • Image URLs: Must be valid web links

Best Practices​

Preparation​

  • Back up your data before large imports
  • Test with a small sample first
  • Verify all referenced data exists
  • Clean and validate your CSV data
  • Document your import process

CSV File Management​

  • Use the provided template
  • Keep consistent column order
  • Validate data formats
  • Remove duplicate entries
  • Save backups of import files

Import Process​

  • Start with small batches
  • Monitor import progress
  • Review error messages carefully
  • Document any issues encountered
  • Keep import logs for reference

Data Validation​

  • Check required field values
  • Verify field relationships
  • Validate data formats
  • Review special characters
  • Test complex field values

Post-Import​

  • Verify imported records
  • Check relationships
  • Test material functionality
  • Document any issues
  • Update related records
TIP

When updating existing materials, consider exporting the current data first. This provides a backup and helps you understand the existing data structure.

Previous
Material Types
Next
Location Types