Live

Design BOM Ingestion

RTMify Live ingests hardware Design BOMs from CSV exports, grouped Design BOM workbooks, and optional read-only Design BOM Sync sources. SolidWorks is one supported export source. The resulting graph anchors each product to a DesignBOM, its BOMItem tree, and any explicit requirement or test references declared on those BOM rows.

Design BOM is not an as-built record

This page describes the product design-intent structure: the named hardware BOM attached to a Product in the Live graph. It is distinct from an as-built BOM, device history record, or production history record, which would capture what was actually manufactured, serialized, substituted, or reworked in a specific build. Live uses the Design BOM to answer engineering traceability, coverage, and where-used questions; it is not a manufacturing execution log.

Download Design BOM Template (.xlsx) View template guide

What Live supports now

Source Path Notes
CSV export from SolidWorks, Altium, PLM, or ERP Inbox drop or POST /api/v1/bom Best fit for one BOM per submission. Same path also accepts hardware JSON, CycloneDX JSON, and SPDX JSON.
Design BOM workbook (.xlsx) Inbox drop or POST /api/v1/bom/xlsx Workbook must contain an exact Design BOM tab. Groups are split by full_product_identifier + bom_name and processed independently.
Secondary Design BOM Sync Dashboard Settings → Design BOM Sync Optional read-only secondary source. Supports Google Sheets, Excel Online, or a local XLSX file.

Product prerequisite

Every hardware Design BOM is anchored to a Product by exact identifier. In the primary RTM workbook, the programmatically provisioned Product tab is: assembly, revision, full_identifier, description, Product Status, RTMify Status.

Exact match still matters

For single-file CSV and JSON ingest, a missing product still fails with BOM_NO_PRODUCT_MATCH. Grouped workbook/XLSX ingest is softer: missing-product groups are reported as warnings and do not abort the whole workbook.

Lifecycle semantics

Obsolete products are hidden from default Design BOM list, tree, item, usage, and impact views. Superseded and EOL remain queryable, but BOM gap views exclude them by default. Unknown nonblank Product Status values write back as PRODUCT_UNKNOWN_STATUS on the Product tab.

Column mapping

These are the hardware Design BOM columns Live understands today.

Column Required Notes
bom_name Yes One named Design BOM within a product. CSV/JSON expect one bom_name per submission. Workbook/XLSX ingest can contain multiple groups.
full_identifier or full_product_identifier Yes Exact Product.full_identifier anchor. Workbook/XLSX ingest groups by this field plus bom_name.
parent_part Yes Parent item part number.
parent_revision Optional Blank or absent values default to "-".
child_part Yes Current row part number.
child_revision Optional Blank or absent values default to "-".
quantity Yes Occurrence quantity on the CONTAINS edge.
ref_designator No Preserved on the containment edge.
description No Stored on the BOMItem.
supplier No Stored on the BOMItem and preserved on the CONTAINS edge.
category No Stored on the BOMItem.
requirement_ids / requirement_id No Comma-, semicolon-, or pipe-separated requirement IDs.
test_ids / test_id No Comma-, semicolon-, or pipe-separated test or test-group IDs.
Notes / RTMify Status Ignored for ingest Accepted on workbook/XLSX input and ignored by Design BOM parsing.

Critical operational detail: derive parent_part when the export is flat

SolidWorks and other flat BOM exports often need one reshape step before ingest. If you want a nested Design BOM tree, derive parent_part from the item-number hierarchy or assembly structure in the source export. The downloadable Design BOM workbook already uses the target column names.

Download the workbook See the full Design BOM template guide

Requirement and test trace fields

Requirement and test identifiers are first-class Design BOM trace input. Export them as BOM columns and map them to the dedicated trace columns below.

Requirement IDs

Map your source data to requirement_ids or requirement_id. Live stores the declared values on the BOMItem and creates REFERENCES_REQUIREMENT edges for exact matches to Requirement nodes.

Test IDs

Map your source data to test_ids or test_id. Live resolves exact IDs to Test first, then TestGroup, and creates REFERENCES_TEST edges for resolved matches.

Unresolved refs stay visible

If an ID does not resolve, the Design BOM still ingests. The raw IDs remain on the BOMItem, and the ingest response includes BOM_UNRESOLVED_REQUIREMENT_REF or BOM_UNRESOLVED_TEST_REF warnings instead of failing the ingest.

Ingest paths

Inbox drop

Drop .csv, .json, or .xlsx into the Live inbox. Successful BOM ingests move to processed/; failures move to rejected/.

cp design_bom.xlsx ~/.rtmify/inbox/

Warning-only BOM ingests still land in processed/; Live mirrors those warnings into runtime diagnostics.

HTTP API

Use POST /api/v1/bom for hardware CSV and hardware JSON. Use POST /api/v1/bom/xlsx for grouped Design BOM workbooks. Lifecycle-aware GET routes accept include_obsolete=true or include_inactive=true when you explicitly want non-current products.

curl -X POST http://127.0.0.1:8000/api/v1/bom/xlsx \
  -H "Authorization: Bearer <token>" \
  -F "file=@RTMify_Design_BOM_Template.xlsx"

The workbook route returns per-group status, warnings, and row counts instead of one all-or-nothing result.

Design BOM Sync

The dashboard settings expose an optional read-only secondary source named Design BOM Sync. That source is separate from the primary RTM workbook and supports Google Sheets, Excel Online, or a local XLSX file.

  • —GET /api/design-bom-sync
  • —POST /api/design-bom-sync/validate
  • —POST /api/design-bom-sync
  • —DELETE /api/design-bom-sync

This source is read-only. Live ingests it but never writes status back into that workbook.

Replacement semantics

Same product + BOM name replaces the prior Design BOM

Design BOM replacement is keyed by (full_product_identifier, bom_type, bom_name). Re-uploading the same hardware BOM key replaces the prior Design BOM subtree for that product and name. If you want multiple hardware inventories to coexist, give them distinct bom_name values.

Graph shape

Product (full_identifier = "ASM-1000-REV-C")
  └─[HAS_DESIGN_BOM]→ DesignBOM (bom_name = "pcba", bom_type = "hardware", bom_class = "design")
       ├─[CONTAINS qty=1]→ BOMItem (part = "PCB-SUB-001", revision = "A")
       │    ├─[CONTAINS qty=4]→ BOMItem (part = "C0805-10UF", revision = "B")
       │    │    ├─[REFERENCES_REQUIREMENT]→ Requirement (REQ-010)
       │    │    └─[REFERENCES_TEST]→ Test or TestGroup (TG-007)
       │    └─[CONTAINS qty=12]→ BOMItem (part = "R0402-10K", revision = "-")
       └─[CONTAINS qty=2]→ BOMItem (part = "CONN-DF12-6P", revision = "A")

The Design BOM hangs off the same Product node as requirements, risks, tests, serial numbers, and code evidence, so BOM-centered impact and coverage questions stay on the same graph.

How to query it

"List the Design BOMs for ASM-1000-REV-C."
"Where is FBRFET-3300 used?"
"Show unresolved requirement or test refs in the power-supply BOM."
"Explain the BOM impact if supplier X EOLs part LM5166DRCR."
"List Design BOMs including obsolete products."
"Show BOM gaps including superseded and EOL products."
"Show the linked requirements and tests for BOM item C0805-10UF/B."
"Read design-bom://ASM-1000-REV-C/pcba and summarize trace coverage."

The key MCP affordances include:

  • get_bom and get_bom_item for tree and item drill-down, with include_obsolete on get_bom
  • list_design_boms, find_part_usage, bom_gaps, and bom_impact_analysis, each with lifecycle override flags where relevant
  • the design-bom://<full_product_identifier>/<bom_name> resource
  • prompts such as inspect_bom_item_traceability, eol_impact, bom_coverage, and component_substitute

Dashboard report availability

The Reports group in the dashboard includes a product-scoped Design BOM report in PDF, Markdown, and DOCX. Software inventory listings such as list_software_boms span both manual SOUP registers and automated CycloneDX/SPDX ingests.

Exporting from SolidWorks

Which BOM export to use

Use the assembly BOM export that gives you one row per child occurrence with part number, revision, quantity, and any custom property columns you need to preserve. Live ingests exported BOM rows, not the native SolidWorks assembly model.

Map custom properties to trace columns

If SolidWorks stores requirement or test identifiers in custom properties, export them as columns and rename them to requirement_ids and test_ids before ingest.

Reshape flat exports

If the export is flat, derive parent_part from the item-number hierarchy so Live can build a nested tree. Keep the final CSV aligned to the supported column schema.

Expected final CSV shape

The final exported file should look like any other hardware Design BOM CSV: one bom_name, one exact full_product_identifier, and the standard parent/child/quantity columns plus any optional trace fields.

Exporting from other sources

SolidWorks is only one source path. Altium or other EDA exports, PLM/ERP exports, and hand-built CSV or XLSX workbooks all work as long as the final artifact matches the supported hardware Design BOM column schema.

Known limits

Limit Current behavior
SolidWorks configuration semantics Live ingests exported BOM rows, not the full SolidWorks model. Suppressed components or alternate configurations only appear if they are present in the exported BOM or workbook.
Unmapped CAD properties Only mapped Design BOM columns are preserved. Other custom properties do not enter the graph.
Grouped workbook product missing Workbook/XLSX ingest warns per group and continues. Single-file CSV/JSON ingest still hard-fails if the Product anchor is missing.
Design-history / chain semantics BOM trace links are visible and queryable, but they do not yet change profile-chain gap logic or design-history semantics.

Error and warning reference

  • —BOM_NO_PRODUCT_MATCH — single-file CSV or JSON targeted a Product that does not exist
  • —NO_DESIGN_BOM_TAB — workbook upload did not contain a Design BOM tab
  • —BOM_UNRESOLVED_REQUIREMENT_REF — a declared requirement ID did not resolve
  • —BOM_UNRESOLVED_TEST_REF — a declared test or test-group ID did not resolve
  • —BOM_CIRCULAR_REFERENCE — ingest detected a cycle in the BOM tree
  • —Workbook/XLSX grouped ingest reports missing-product groups as warnings rather than aborting the whole upload
  • —Invalid workbook bytes return invalid_xlsx from POST /api/v1/bom/xlsx