> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MBOM Imports

> Import multi-level Bills of Materials from a CSV file, using Depth or Level notation to define part hierarchies.

## Overview

MBOM imports let you define multi-level part structures in a single CSV — from top-level assemblies down to individual components. ION supports two ways to describe how parts are nested: **Depth** notation and **Level** notation. ION automatically detects which one you are using based on the first column header in your CSV.

## Import options

| Option                    | Default | Description                                                                                                                                                                                      |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Auto-create missing parts | On      | When enabled, any parts in the import that do not already exist in the Parts Library are created automatically. When disabled, referencing a part that does not exist causes a validation error. |
| Always create new version | On      | When enabled, a new mBOM version is always created. When disabled, the latest version is updated in place if it is a draft; otherwise a new version is created.                                  |
| Validation only           | Off     | Run validation without committing changes. Useful for checking a file before a real import.                                                                                                      |

## Columns

| Column                  | Required | Description                                                                                                                                                   |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `depth` or `level`      | Yes      | The first column in your CSV. Determines how the part hierarchy is structured. See sections below.                                                            |
| `part_number`           | Yes      | The part number for this row.                                                                                                                                 |
| `revision`              | Yes      | The part revision.                                                                                                                                            |
| `quantity`              | Yes      | How many of this part are needed in the parent assembly.                                                                                                      |
| `substitutes`           | No       | Alternative parts, formatted as `part_number[revision];part_number[revision]`. Example: `BOLT-300-ALT[A];BOLT-300-METRIC[B]`.                                 |
| `made_on_assembly`      | No       | Whether this part is fabricated as part of the parent assembly. Boolean field (see [accepted values](/administration/ion-importers#accepted-boolean-values)). |
| `reference_designators` | No       | Reference designator strings for the component.                                                                                                               |

<Info>
  Ensure part numbers and revisions match existing records exactly. Part matching is case-insensitive.
</Info>

## Depth notation

Depth notation describes your BOM structure by indenting parts one level at a time, similar to how you might indent items in an outline. The top-level assembly is depth **1**, its direct components are depth **2**, their sub-components are depth **3**, and so on.

To move back up the tree and start a new branch, simply return to a lower depth number. Rows must be listed in the order they appear in the assembly — each component must come after the assembly it belongs to.

**Example:** An assembly (`ASSEMBLY-100`) contains a bracket and a panel. The bracket itself requires four bolts.

| depth | part\_number | revision | quantity |
| ----- | ------------ | -------- | -------- |
| 1     | ASSEMBLY-100 | A        | 1        |
| 2     | BRACKET-200  | B        | 2        |
| 3     | BOLT-300     | A        | 4        |
| 2     | PANEL-400    | A        | 1        |

<Warning>
  You cannot skip depth levels — for example, jumping from depth 1 directly to depth 3 is not allowed. Each component must be listed directly under its parent assembly.
</Warning>

## Level notation

Level notation uses a numbering scheme (e.g., `1`, `1.1`, `1.1.1`) to explicitly identify where each part sits in the assembly tree. This is similar to how work breakdown structures or section numbering works — the number itself tells you the full path from the top-level assembly down to the component.

Unlike Depth notation, **rows can appear in any order** because the level value fully defines each part's position in the hierarchy. ION sorts and organizes the structure for you.

**Example:** The same assembly as above, with rows intentionally listed out of order to show that ordering does not matter.

| level | part\_number | revision | quantity |
| ----- | ------------ | -------- | -------- |
| 1     | ASSEMBLY-100 | A        | 1        |
| 1.2   | PANEL-400    | A        | 1        |
| 1.1   | BRACKET-200  | B        | 2        |
| 1.1.1 | BOLT-300     | A        | 4        |

Here, `1.1` (BRACKET-200) and `1.2` (PANEL-400) are both direct components of `1` (ASSEMBLY-100), and `1.1.1` (BOLT-300) is a sub-component of the bracket — regardless of the row order in the CSV.

<Warning>
  Every parent level must exist somewhere in the file. For example, you cannot define `1.1.1` without also having a `1.1` row. However, the rows do not need to be in any particular order.
</Warning>

## Cycle detection

ION automatically detects circular references in your MBOM. If assembly A contains part B and part B also contains assembly A (directly or through any chain of intermediate parts), the import will fail with a validation error identifying the cycle. This check also applies to substitute parts.

## Related pages

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).