Reference

BOM File Format

Specification for BOM file import including supported formats, column mapping, and examples.

BOM File Format

Gerbtrace can import Bill of Materials files and enrich them with pricing and availability data from the Elexess API. This page documents the supported file formats, column detection rules, and examples.

Supported file types

ExtensionFormat
.csvComma-separated values
.tsvTab-separated values
.txtTab- or comma-separated (auto-detected)
.xlsxMicrosoft Excel (first sheet is used)
.xlsLegacy Excel (first sheet is used)

File naming

The file name must contain one of these keywords (case-insensitive) to be recognized as a BOM:

  • bom
  • bill-of-materials / bill_of_materials
  • stückliste / stueckliste

Examples: BOM.csv, project-bom.xlsx, Bill_of_Materials.tsv

Delimiter detection (CSV/TSV/TXT)

The parser auto-detects the delimiter by inspecting the first 5 lines:

  1. If any line contains a tab, the file is tab-delimited.
  2. Otherwise, if any line contains a semicolon, the file is semicolon-delimited (common in European exports).
  3. Otherwise, the file is treated as comma-delimited.

Quoted fields (double quotes) are supported. Escaped quotes inside quoted fields use "".

Columns

The first row must be a header row. Columns are auto-mapped by matching the header text against known keywords. All matching is case-insensitive, folds accents (Gehäuse matches Gehause) and ignores non-alphanumeric characters (spaces, underscores, hyphens are stripped before matching). Gerbtrace looks for the header row in the first 30 rows, so title or filter rows above it are fine.

FieldRequiredRecognized header namesDescription
ReferencesYesReferences, Ref Des, Ref, Reference Designators, Refs, Designators, Designator, Parts, Locations, Location, PositionenComponent reference designators, comma-separated (e.g. R1, R2, R3)
QuantityYesQuantity, Qty, Count, Amount, Pcs, Pieces, Number, Menge, AnzahlNumber of components
DescriptionNoDescription, Desc, Component, Comp, Part Description, Part Desc, Item Name, BezeichnungComponent description
TypeNoType, Typ, Component Type, Comp Type, Mount Type, Mounting Type, CategoryOne of: SMD, THT, Mounting, Other
Customer ProvidedNoCustomer Provided, Cust Provided, Customer, Customer Supplied, Cust SuppliedYes/No/True/False/1/0
Customer Item NoNoCustomer Item No, Cust Item No, Customer Item, Customer Part Number, Customer Part No, Cust Part No, Cust PNCustomer's own part number
ERP Item CodeNoBOM Item, StücklistenartikelNewmatik ERP item code, shown as a badge on the BOM line
PackageNoPackage, Footprint, Pkg, FP, Land, Land Pattern, Case, Case Code, GehäusePackage or footprint name
CommentNoComment, Comments, Note, Notes, Remark, RemarksFree-form text
ManufacturerNoManufacturer, Mfr, Mfg, Make, Vendor, Brand, HerstellerManufacturer name
Manufacturer PartNoManufacturer Part, MPN, MFPN, Manufacturer Part Number, Mfr Part, Mfg Part, Mfr PN, Mfg PN, Part No, Part NumberManufacturer part number (used for pricing lookup)
Manufacturer + PartNoManufacturer/MPN, Hersteller/MPNSeveral Manufacturer MPN entries in one cell, separated by commas. The last word of each entry is the MPN.
Long LeadNoLong Lead, Long Lead Time, Lead Time Risk, Long Lead Risk, LLT, Long Lead Item, Long Lead FlagMarks structurally long-lead items (Yes/No/True/False/1/0, or a free-form lead-time note). See Long Lead column.

At least 2 columns must be successfully matched for auto-detection to succeed. If auto-detection fails, Gerbtrace prompts you to manually map the columns.

Type values

The Type column accepts these values (case-insensitive):

ValueRecognized variants
SMDSMD, SMT
THTTHT, THD, Through Hole, Through
MountingMounting, Mech, Mechanical
OtherAnything else, or when the column is missing

Multiple manufacturers per line

A single component can have multiple manufacturer options. There are two ways to represent this:

Repeated rows with the same references

Duplicate the row for each alternate manufacturer. The parser groups rows by the References column and merges manufacturer entries:

References,Quantity,Description,Manufacturer,MPN
"R1, R2",2,10K Resistor,Yageo,RC0402FR-0710KL
"R1, R2",2,10K Resistor,Samsung,RC1005F1002CS

This produces one BOM line with two manufacturers.

Rows with only a manufacturer and MPN

A row that holds nothing but a manufacturer and an MPN adds that MPN to the line above it:

References,Quantity,Description,Manufacturer,MPN
"D1, D2",2,LED white,Maker A,LED-A
,,,Maker B,LED-B

This produces one BOM line with two manufacturers.

Manual entry in the UI

After importing, click any BOM line and use the edit modal to add additional manufacturers.

ERP BOM Export

The Newmatik ERP report BOM Export (open an approved BOM, run the report, then export it to Excel) imports as is, in English or German, with or without the Collapse Manufacturer and MPN and Per Location options:

  • Locations become the references; BOM Item is kept as the ERP item code.
  • Every approved MPN of an item becomes a manufacturer of its line.
  • Per Location exports, which repeat an item on one row per designator, become one line per item again.
  • Items in a "Customer Provided" item group are marked customer provided.
  • Lines without locations, such as the PCB, are imported without references, so they are not placed.

The default layout (MPNs not collapsed) is the safest: it keeps manufacturer and MPN in separate cells.

Customer Provided column

The Customer Provided column indicates whether the customer supplies this component (i.e., it does not need to be sourced). Accepted true values: Yes, True, 1, Y. Everything else is treated as false.

Long Lead column

The Long Lead column flags items whose long procurement lead time is a property of the commodity class itself — for example custom cables and harnesses, custom-wound magnetics, factory-programmed parts, or custom-marked devices. This is intentionally focused on structural lead times, not on transient market shortages or allocation cycles, which change too rapidly to track on the BOM itself.

Accepted boolean values: Yes / No / True / False / 1 / 0 / Y / N. Any other non-empty string (e.g. 12 week vendor quote) is treated as true and stored as the lead-time reason note shown in the BOM detail pane.

If the column is missing, Gerbtrace runs a conservative heuristic against each line's description, comment, package, and customer item number. It flags items matching:

  • Cables and harnesses — wire harness, cable assy/assembly, ribbon cable, flex cable, FFC, jumper cable, or bare cable (typically ≥8 week build-to-order)
  • Custom magnetics — custom transformer/inductor/coil/choke, wound transformer/inductor, planar transformer, or transformer/inductor assy
  • Factory-programmed parts — factory programmed, pre-programmed, custom programmed, or programmed EEPROM/MCU/flash/...
  • Custom-marked parts — custom marking/label/logo/silkscreen/laser mark

An explicit value in the column always wins over the heuristic, so source-of-truth BOMs can opt parts in or out without being overridden. Manual edits in the BOM detail pane likewise persist across re-imports.

Example BOM file

References,Quantity,Description,Type,Package,Manufacturer,MPN,Customer Provided,Long Lead,Comment
"R1, R2, R3",3,10K 0402 Resistor,SMD,0402,Yageo,RC0402FR-0710KL,No,No,
"C1, C2",2,100nF MLCC,SMD,0402,Samsung,CL05B104KO5NNNC,No,No,
U1,1,ARM Cortex-M0+ MCU,SMD,QFP-48,Microchip,PIC16F684-I/ST,No,No,Main controller
J1,1,USB-C Connector,SMD,USB-C,Wurth,632723300011,No,No,
W1,1,Wire harness 8-pin to JST,Mounting,,Custom,HARN-8P-001,No,8 week build,Power harness
H1,1,M3 Standoff,Mounting,,,,Yes,No,Customer supplies standoffs

Field mapping fallback

If the parser cannot auto-detect your column layout (fewer than 2 columns matched), a mapping dialog appears. You can manually assign each BOM field to a column from your file. A preview of the first 3 data rows is shown to help verify the mapping.