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
| Extension | Format |
|---|---|
.csv | Comma-separated values |
.tsv | Tab-separated values |
.txt | Tab- or comma-separated (auto-detected) |
.xlsx | Microsoft Excel (first sheet is used) |
.xls | Legacy Excel (first sheet is used) |
File naming
The file name must contain one of these keywords (case-insensitive) to be recognized as a BOM:
bombill-of-materials/bill_of_materialsstü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:
- If any line contains a tab, the file is tab-delimited.
- Otherwise, if any line contains a semicolon, the file is semicolon-delimited (common in European exports).
- 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.
| Field | Required | Recognized header names | Description |
|---|---|---|---|
| References | Yes | References, Ref Des, Ref, Reference Designators, Refs, Designators, Designator, Parts, Locations, Location, Positionen | Component reference designators, comma-separated (e.g. R1, R2, R3) |
| Quantity | Yes | Quantity, Qty, Count, Amount, Pcs, Pieces, Number, Menge, Anzahl | Number of components |
| Description | No | Description, Desc, Component, Comp, Part Description, Part Desc, Item Name, Bezeichnung | Component description |
| Type | No | Type, Typ, Component Type, Comp Type, Mount Type, Mounting Type, Category | One of: SMD, THT, Mounting, Other |
| Customer Provided | No | Customer Provided, Cust Provided, Customer, Customer Supplied, Cust Supplied | Yes/No/True/False/1/0 |
| Customer Item No | No | Customer Item No, Cust Item No, Customer Item, Customer Part Number, Customer Part No, Cust Part No, Cust PN | Customer's own part number |
| ERP Item Code | No | BOM Item, Stücklistenartikel | Newmatik ERP item code, shown as a badge on the BOM line |
| Package | No | Package, Footprint, Pkg, FP, Land, Land Pattern, Case, Case Code, Gehäuse | Package or footprint name |
| Comment | No | Comment, Comments, Note, Notes, Remark, Remarks | Free-form text |
| Manufacturer | No | Manufacturer, Mfr, Mfg, Make, Vendor, Brand, Hersteller | Manufacturer name |
| Manufacturer Part | No | Manufacturer Part, MPN, MFPN, Manufacturer Part Number, Mfr Part, Mfg Part, Mfr PN, Mfg PN, Part No, Part Number | Manufacturer part number (used for pricing lookup) |
| Manufacturer + Part | No | Manufacturer/MPN, Hersteller/MPN | Several Manufacturer MPN entries in one cell, separated by commas. The last word of each entry is the MPN. |
| Long Lead | No | Long Lead, Long Lead Time, Lead Time Risk, Long Lead Risk, LLT, Long Lead Item, Long Lead Flag | Marks 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):
| Value | Recognized variants |
|---|---|
SMD | SMD, SMT |
THT | THT, THD, Through Hole, Through |
Mounting | Mounting, Mech, Mechanical |
Other | Anything 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 barecable(typically ≥8 week build-to-order) - Custom magnetics —
custom transformer/inductor/coil/choke,wound transformer/inductor,planar transformer, ortransformer/inductor assy - Factory-programmed parts —
factory programmed,pre-programmed,custom programmed, orprogrammed 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.