Use a project's BOM¶

A project's BOM lists what the project is made of and what it costs. Each line points at a part in the parts catalogue — it does not copy it. Correcting a supplier or a price in the catalogue corrects it on every project that uses that part, immediately, with nothing to sync.

Switching it on¶

The BOM is off by default, so a project only grows a BOM tab when somebody asks for one.

A project admin turns it on in Project settings → BOM. Switching it off again hides the tab and refuses any change — it deletes nothing, and switching it back on restores every line exactly where it was.

Who can see it¶

BOM access is per person, per project, because a BOM holds what the company pays for its parts. A new member starts with no access, including admins.

Tick BOM beside somebody's name in Project settings → Members to let them in. It is all-or-nothing: anyone who can open the tab sees prices.

That includes you. If you switch the BOM on and do not have access yet, Project settings says so beside the switch, with a Give me BOM access button.

Until that box is ticked the BOM tab is not shown at all, so nobody is offered a page they cannot open.

This is a separate permission from catalogue access, and neither implies the other:

Catalogue access, no BOM access — a buyer who maintains supplier data and has no reason to open a project.
BOM access, no catalogue access — somebody building a BOM who cannot edit the shared catalogue. They can still add lines (see Lines that are not in the catalogue, below).

Reading the table¶

Every row shows the part's item number, name and part number. Those are always there. Everything else is a column somebody configured.

Two quantity columns sit side by side and the difference matters:


Qty	how many of this part go into one of its parent
Total Qty	how many the project needs in total

A screw at quantity 4 inside a sub-assembly used 3 times is 12 screws. Extended price multiplies by Total Qty, never by Qty.

Costs that are not complete¶

Where something below a row has no price yet, the figure reads as a bound with a count rather than a number:

≥ A$41.40 · 1 part has no price

That is deliberate. A partial cost that looked like a total would be indistinguishable from a complete one, it would be lower than the truth, and it is exactly the number somebody would quote a customer from. Hover for the exact figure.

A row with no price at all reads 3 parts have no price — "at least nothing" is not a number anybody can act on.

The count on the total is every part in the whole BOM with no price. It is not the same as the count under Missing information, which lists only the details each part's category requires. A part whose category does not ask for a price adds to the total's count but is not listed there. The two numbers will often differ, and both are right.

A sub-assembly you buy complete¶

If you buy an assembly complete rather than building it, mark its part Bought complete in the catalogue. Its own price then becomes the cost, and its children stop being counted — they are the supplier's problem, not a line on your order. Still to buy follows the same rule: it lists the assembly, and reads nothing to buy on the parts inside it. Giving a line its own unit price (an override) does the same to everything below that line.

The children still appear, and they still show a cost — greyed. They are still part of the design, and what the grey says is that those figures do not reach the total. They are useful: they tell you what those pieces would cost if you bought them separately, which is usually why you wanted the number. Open one and the panel says so in words.

Opening a line¶

Click a line, or — without a mouse — Tab to its name and press Enter. The editor opens beside the table with the cursor in Quantity. The Item and Part columns stay in view while you scroll the other columns sideways, so you can always see which line is open.

Saving¶

Changes save when you click away from the editor, and a message confirms it. Ctrl+Enter (⌘+Enter on a Mac) does the same from any field, and so does Esc. The Save button stays at the bottom of the editor, however far down you have scrolled.

Clicking another line saves this one and opens that one, in one click.
If a save is refused, the editor stays open with everything you typed, and the message says why — "Quantity must be greater than zero.", say. Fix it and save again.
Everything in the editor counts: an update you have typed but not yet added, and a value typed under This project's values, are saved along with the rest when you leave. Ctrl+Enter inside the update box adds the update and keeps the editor open.
Only what you changed is saved. If a colleague marks the line Received while you have it open to fix a note, saving your note leaves their status alone. And if the page refreshes while you are typing — it does when you come back from another window — the fields you are editing keep what you typed.

Opening a line and closing it again without changing anything writes nothing, so your name does not end up against an edit you did not make.

Adding lines¶

Type a name in Add a line and press Add. If you have catalogue access you can also search the catalogue and pick a part, or create a new catalogue part and add it in one step.

To add something under an assembly line, open that line and choose Add a line under this.

Lines that are not in the catalogue¶

A line can name something the catalogue has never heard of — packaging, thread-lock, shipping, a part nobody has entered yet. It shows a not in catalogue flag, has no price, and marks the project total as incomplete so the number stays honest.

This is not a dead end. Those lines are listed under Missing information as Not in the catalogue. If you have catalogue access, press Add to catalogue beside one, or in the panel when the line is open. You can correct the name, then confirm: TaskTree creates the catalogue part and the line uses it from then on. Fill in its price and supplier in the catalogue.

The same part twice¶

A part can appear only once in the same place: once under the same assembly, and once in the same group (or once ungrouped there). Adding it a second time beside itself — or dragging it next to itself — is refused with This item is already in the BOM, and the line that is already there opens so you can change its quantity instead.

The same part under a different assembly, or in a different group, is fine: that is a bolt used in two places, and Still to buy already adds the two together ("across 2 lines"). An import is never refused this way, because the CAD decides its own structure — but if one leaves the same part twice in the same place, it shows up under Missing information as On the BOM twice, so it is not bought twice by accident.

Importing from Onshape¶

Import from Onshape takes a BOM exported from Onshape as a CSV and turns it into lines, so forty-nine part names do not get retyped.

Nothing is written until you have read a plan and pressed Import. The first step always shows you what would happen; the file is not applied until you say so.

Naming the source¶

You give each import a source name — the name of the assembly it speaks for, not the name of the file. The name is what a later export of the same assembly uses to find these lines again and update them.

Reuse the same name every time you re-export that assembly. A new name adds a second, separate set of lines rather than updating the first, which is what you want when a project contains two different assemblies and is not what you want otherwise.

Small differences in the name don't count. Capitals, extra spaces and a trailing copy number such as (1) are ignored, so Leveller (1) — what a browser calls a second download of BOM of Leveller.csv — updates the Leveller lines rather than adding them all again. The page also leaves the (1) out when it suggests a name from the file.

If you do type a new name and most of the file's rows share a name with lines the project already has, the plan warns you and names the source those lines came from. Use that source name if the file is a new export of it.

Reading the plan¶

The plan says what each row will do:


New	a line this project does not have yet
Unchanged	already there, and the file says nothing different
Changed	already there, and something moved — it shows you what, from what, to what
Renumbered	already there, and only its item number moved because a row was added or removed above it
Needs a decision	the file cannot settle it on its own
Skipped	you chose not to import it

When a line moves to a different assembly, the plan names both: under Left Assy → under Right Assy.

The same part used in two places is one catalogue part. If a screw appears in two sub-assemblies, the import adds two lines and creates the part once.

Skip this row leaves a row out, and the plan updates straight away. Skipping an assembly skips everything inside it too, so nothing inside it ends up at the top level. A row the file got wrong — say, a quantity that is not a number — can be skipped as well, instead of fixing the file first.

Quantities must be numbers greater than zero, with at most four decimal places and below 100,000,000. A decimal comma (1,5) or exponent notation (1e3) is listed as a row that cannot be read, with the reason.

A quantity can carry the part's own unit, as in 2.5 m or 250 mL. If the unit is not the part's, the row is listed as a problem: '2.5 m' is in m, but this part is measured in g. A part that is counted in each, including every part the import creates, needs a whole number.

It also lists lines the file does not mention. Those are reported and left alone. The importer never deletes anything: an export made with a filter applied looks exactly like an assembly that has shrunk, and there is no way to tell the difference from the file. If the design really has lost a part, delete that line yourself on the BOM.

Lines you added by hand are never touched. Packaging, consumables, thread-lock, shipping, labour — none of that is in a CAD export, and an import neither changes nor reports them.

Rows that need a decision¶

Some rows genuinely cannot be resolved from the file, and the importer asks rather than guessing:

Two rows that look identical. If an export has three rows named Magnet, the file cannot say whether that is one part used three times or three different parts. Both are perfectly possible, so you choose for each one. This stops happening once those parts have part numbers.
A part number that belongs to something else. If a row is called Sensor Board and carries a part number the catalogue holds under a different name, you are asked to confirm they are the same part. Usually somebody renamed it upstream; occasionally the number is a typo, and agreeing to that one silently would put the wrong part on an order.

Pick an answer for each, press Re-check the plan, and the plan updates. Import stays greyed out until nothing is outstanding. Each existing line can be the answer for one row only: once you choose it for one row, it is greyed out for the others.

Columns¶

The importer matches the export's column headings to TaskTree's fields and shows you what it chose, so you can correct it. Change one and the plan updates.

No column is dropped silently. Headings TaskTree has no use for are listed with a few of their values, so you can see what you are leaving behind. Mfg Process is the usual one.

Onshape's Vendor column fills the part's Supplier. It only fills a Supplier that is empty: a supplier somebody typed in the catalogue is kept, and the plan shows the file's value as not written: kept: already set by hand.

A Quantity column and a Name column are required. If neither heading is recognised, the plan stops and asks which column holds it, rather than assuming every quantity is 1. Mapping a column to Item number by hand (for example Pos) builds the assembly structure from it.

Comma, semicolon or tab. Excel in some regions saves "CSV" with semicolons between the columns. The importer works out which one the file uses and says so when it is not a comma. If item numbers come back as duplicates, the file has probably been opened and saved in Excel, which turns 1.10 into 1.1; export it again from Onshape and upload it unopened.

Catalogue values need catalogue access¶

Values such as Material or Supplier are stored on the catalogue part, which every project using that part shares. So:

Without catalogue access, the import adds and updates lines but writes no catalogue values. The plan lists each one it is leaving out as not written: needs catalogue access. Someone with access can import the same file again to write them.
An empty cell never deletes a value. If the export has nothing in a column for a part, whatever the catalogue holds stays.
The plan shows the part's current value on the left of each change, so you can see what you are replacing.

With catalogue access you can keep a column as a new field, which is usually how a genuinely new kind of information gets added. You only answer that once: the next export with the same heading maps straight to the field you created, whatever its capitalisation or spacing has become.

Once the columns are right, save the mapping under a name and the next person does not have to work it out again.

Assemblies whose contents are missing¶

An export can contain an assembly without containing the parts inside it. Those import as a single line flagged contents not exported — not as an empty assembly, which would cost nothing and look finished. The flag is what tells you to go back to Onshape and export that assembly properly.

What a finished import leaves behind¶

Every run is listed at the bottom of the import page with its counts and a link to the exact file that was uploaded. When somebody asks where a quantity came from months later, the answer is the file itself rather than a reconstruction.

Builds¶

A build is one run of the product — "EVT ×5", "Beta ×20" — made from this project's BOM. The project keeps one BOM; a build is not a copy of it, so a fix made to the BOM today reaches every build that has not been built yet.

The Builds strip sits above the table, one card per build, showing its name and units, whether it is Planned, Completed or Cancelled, its date and what it costs. + New build adds one.

Dates¶

A build has a typed planned date, or it follows a milestone task of this project, or it has no date yet. A build that follows a task shows the task with a link mark (🔗 Beta ships · 14 Nov 2026) and moves when the task moves. If the task has no due date it says no date, and if the task is deleted the build is left undated.

Planned builds claim stock¶

While a build is Planned it claims the stock it will need, so other projects cannot count that stock as free. Two planned builds both claim. Cancel build releases the claim; Plan again brings it back. A cancelled build can be deleted.

Completing a build¶

When the build has been made, choose Complete…. The dialog lists every part the build takes from the shelf, each at the build's units times what the BOM needs, following the same build-or-buy rule as Still to buy: a part you buy complete is used whole, and a catalogue assembly you build uses its components. Change any quantity that was different — a part scrapped, an extra unit made, a part not fitted (0). A part that is not on the BOM cannot be added here: if a substitute was used, set the original to what was really used and Count the substitute on its part page. Lines with no catalogue part are recorded but use no stock.

Complete build does three things at once:

takes the stock off the shelf, as a Used by build entry in each part's stock history;
freezes the build's record;
marks the build Completed, which releases its claim.

Stock may go below zero; that means the shelf needs counting.

The record¶

A completed build's Record is the BOM as it was built: each line's part number, name, revision, quantity, build-or-buy rule, supplier and unit cost on the day, and the stock each part actually used. It never changes, even when the catalogue does. Export CSV downloads it.

Reopening a build¶

If a completion was a mistake, Reopen puts its stock back, discards its record and makes it Planned again. Only the project's most recent completion can be reopened, and only by the person who completed it or an admin of the project. The stock history keeps both the use and the reversal (Reopened — reversed), so nothing disappears.

If a project is deleted, the stock its builds used stays used, and each entry in the stock history still names the build it went to.

Tracking what to buy¶

The BOM answers "what is this made of". Five columns make it also answer "what still needs buying, and where has it got to?"

Qty on hand¶

How many are in the store room — one number for the whole workspace, not per project, because it is one shelf. Nobody types it: it comes from the part's stock record, which changes when stock is received or counted in the part's Stock section, under Parts Catalogue. It can be below zero, which means the record has missed something and the shelf needs counting.

An import never touches it.

Still to buy¶

Worked out for you, and it is the column most people will actually work from. It is what this project needs minus the stock nobody else has claimed, and both halves are worth understanding.

What this project needs follows one rule for what is built and what is bought, the same rule the cost uses:

A line with lines below it is built. It asks for nothing itself; the parts below it are bought. It reads built from below.
Unless its part is bought complete. Then the line is bought whole, and the lines below it are shown for reference only. They read inside a bought item and ask for nothing. Cable harnesses are the usual case.
A catalogue assembly on a line with nothing below it is built from its catalogue components. Its components go on the buy list, expanded down to anything bought complete, and they are listed in the line's cell, each with its own figure. The line reads built from catalogue components. For example, "Wiring" defined as 3 m of cable and 2 connectors puts the cable and the connectors on the list.
Anything else is simply bought.

Every rule except a plain bought is named in the cell, so a zero always says why.

It is the rolled-up figure, summed across every line that buys the part. A bolt used four times inside a sub-assembly built three times is twelve bolts, and a bolt that appears on three separate lines is one requirement, not three. Where that happens the cell says across 3 lines, so you do not add it up twice.

Only planned builds count. The BOM describes one unit, so what this project needs is the per-unit figure times the units of each Planned build in the Builds strip, added together: an EVT of five and a Beta of twenty need twenty-five of everything. Completed and cancelled builds claim nothing. With no planned build at all, the column says No planned build instead of a number, so an empty column is never mistaken for "fully stocked". See Builds.

The total is still the cost of one unit. Each build in the strip shows its own cost — "Beta ×20 = US$…" — marked as partial whenever the total is.

The stock you may count on is the stock on the shelf plus on order that no other project's BOM is relying on. Stock on order counts because it is on its way: forty bolts in transit cover a need of forty, so nobody is asked to order them again. If there are twelve in stock and another project needs ten of them, this project may count on two — so with a need for ten, it says 8, and so does the other project.

That deliberately buys more than the shelf strictly needs. Ordering eight too many costs the price of eight bolts and leaves a surplus the next project uses; ordering eight too few stops a build for however long the lead time turns out to be, having looked fine all along.

The figure shows its working, always — "2 of 12 in stock free — 10 claimed by Gamma · Beta ×20", naming the project and its build, or "14 of 4 in stock + 40 on order free" when some is on its way. It has to, because this is the one number on the BOM that can change when somebody edits a different project. If it moves and you want to know why, the sentence underneath says who, and each project's name opens its BOM.

If the claim comes from a project whose BOM you cannot open, it says "claimed by another project" instead of naming it. The quantity is still counted, because the stock really is shared. A project with its BOM switched off claims nothing, and so does one with no planned build. Other projects' claims follow the same build-or-buy rule as this one's: a line they build claims nothing itself, nor do the parts inside an item they buy complete or a line marked Not needed, and a catalogue assembly they build claims its components.

Status¶

Five states: Not started, Quoting, Ordered, Received and Not needed. Deliberately few. A longer list is one where two people file the same situation differently and the filter quietly stops finding things; anything more specific belongs in an update.

Not needed is worth using. Without it, lines nobody intends to buy sit at Not started forever and you read past them every time. A Not needed line, and everything below it, is left out of this build: it adds nothing to the total or to its group's subtotal, reads nothing to buy, and claims no stock from other projects. It stays on screen, greyed, so you can change your mind.

Expected¶

The date it is due. Past dates are flagged, but an empty one never is — blank means nobody knows yet, which is not the same as late. A line that has already been received, or that is marked Not needed, is never flagged either.

Latest update¶

A dated, attributed note — and the history is the point. Open a line and type what happened: "Quoted 4 weeks", "Chased", "Promised Friday". The column shows the most recent one; the line's panel shows all of them, newest first, each with who wrote it and when.

Updates are kept, not edited. There is no way to change one or delete one, and that is on purpose: the reason to keep a record of what a supplier promised is that somebody will later want to know what was promised and when. If an entry is wrong, add another saying so — the way you would in a ledger.

This is not the line's Note, which is still there and still means what it did: a standing sentence about this project's use of the part, like "substituting this on the Delta build".

All five columns are in the CSV export, the same as everything else on the screen (see Exporting to a spreadsheet).

Groups¶

A group is a named heading over lines that sit side by side — three slightly different battery terminals that read as one thing, say. It shows its name, how many lines it holds and what they cost together, and it folds like an assembly.

A group is only a heading. It has no quantity and multiplies nothing, so every figure on the page — each line's total quantity, its price, Still to buy, the project total — is exactly what it would be ungrouped. A group's cost is marked incomplete the same way the total is, when a line in it has no price.

To make one, open a line and type a name under New group with this line. The heading appears where the line was, with the line in it.
To add lines to it, drag them onto the heading, or use Move to… in the line's editor.
Rename and Delete group are on the heading. Deleting a group keeps its lines; they stay where the group was.

A group holds lines from one level — the top of the BOM, or inside one assembly. Moving a line to a different assembly takes it out of its group. An import does not know about groups, so grouping an imported line never changes how the next import matches it — but if an import puts a line back under its CAD assembly, it leaves its group there.

In the CSV export a group is a heading row with its lines under it, the same as on screen.

Moving lines¶

Drag a line by the ⠿ handle at the start of its row.

Up or down among its neighbours to reorder it. The order you set survives the next import.
Onto a group heading to put it in the group, or beside a line in a group to join that group there.
Onto an assembly row to move it inside that assembly, or out of one to the top level or into another.

A line that lands in a different assembly is multiplied by that assembly's quantity, which changes what you buy — so the move asks first and says the numbers: "Moving M3 screw into Cap sub-assembly (×3) changes its total from 4 to 12." For a line that came from an import it also warns that the next import of that source will move it back to where the CAD has it.

A line cannot be dropped inside itself or anything under it, and the row turns red before you let go if the drop will be refused.

Without a mouse, open the line (Tab to its name, Enter) and use Move to…: pick where it should go and press Move. It puts the line last there and asks the same question when the assembly changes; Tab stays inside that question until you answer it. Group headings can be dragged to reorder them too; a group stays at its own level.

Collapsing and hiding¶

Click the triangle on an assembly row to fold its branch. A folded assembly still shows the cost of everything inside it, so a collapsed BOM never under-totals.
Click the triangle on a group heading to fold the group, which shows its lines' cost in the heading.
Columns at the top of the page lets you hide columns you do not need.

All of these live in the page's address, so the link you copy shows what you are looking at. Paste a narrowed BOM into a chat and the other person sees the same thing. Nothing is saved and nobody else's view changes.

Exporting to a spreadsheet¶

Export CSV downloads what is on screen: the columns you are showing, in order, and the rows you can see. It opens in Excel as you would expect.

Prices are numbers, so you can total them. The currency is in the column heading, for example Extended price (US$).
Unpriced parts says, on every row, how many parts under it have no price. Anything other than 0 means that row's cost is a lower bound — the same thing the ≥ mark means on screen.
Counted in total is No for rows inside an assembly the project buys complete, which are greyed on screen. Their prices are real but are not part of the total.
Still to buy appears once per part, on its first row; later rows of the same part are blank. That way the column adds up to what you actually need to buy.
Buy rule says on every row which rule applied: bought, bought complete, built from below, inside a bought item, built from catalogue components or not needed.
Components get rows of their own. A line built from catalogue components is followed by a row for each component: its name and part number, its quantity per unit in Total qty, and its Still to buy. Its Buy rule reads, for example, component of 2 (bought).
Folded branches are left out, as on screen, and the message after the export says how many lines that is. Expand them first to export everything.

When a part has a newer revision¶

A line whose part has been revised shows a newer revision flag. Nothing moves by itself. A revision is a different physical thing at a different price, so moving a project onto it would change what the project builds and what it costs without anybody deciding to.

Open the line and use Move this line to the newer revision when you want it. One click, and only the line you are looking at.

Deleting a line¶

Deleting an assembly line deletes everything under it. The button says how many rows that is before you confirm, because on a folded branch the size of what you are about to remove is invisible.

Which columns everybody sees¶

Columns are one set for the whole workspace, not per project — the reason to have a template at all is that two projects' BOMs can be read side by side.

Anybody with catalogue access can change it at Catalogue → BOM columns. Adding or removing a column changes what every project shows; it never deletes a value, so a column removed today can come back tomorrow with everything still in it.

The item number, part number and name are not on that list. They are the row itself, and a BOM with the part name hidden is not a BOM.