Instances

While an Item defines the type of product (e.g., "Widget Model A"), an Instance represents a specific, traceable, serialized occurrence of that Item within your inventory.

Why Instances Matter

Instances are central to Hegemi, especially for items with BOMs. They're the whole point of this software. When a product is assembled from components, each assembled unit is an instance of that product. The instance tracks:

• Which specific components were installed into this unit.
• When they were installed, by whom.
• The full attachment history if parts were ever swapped out.

This creates a complete digital twin of the physical product.

Creating an Instance

Instances are created from the Inventory tab of an item's detail view. Click New instance to create one.

For items with a BOM, you'll see the option Create & reserve child BOMs. When checked, Hegemi will automatically create new serialized instances for all sub-assemblies throughout the BOM, recursively, and attach them with a "Reserved" status. This is the typical workflow when starting a new build: you get a full set of serial numbers assigned for the entire product tree upfront.

Instance Editor

When you click on an instance, you open its editor with three tabs:

Info Tab

Edit the instance's basic properties:

• Serial: The unique identifier for this instance.
• Status: Track the build lifecycle (Planned, Building, Ready, Complete, Out of Order).
• Description: Notes about this specific unit.
• Custom Fields: Any custom fields you've configured for instances.

Instance BOM Tab

This is the heart of instance tracking. For items with a BOM, this tab displays the hierarchical structure of all the components.

Each line item shows:

• The part reference (e.g., "4 each Screw M3")
• A completion bar showing the attach status of items across all slots
• An Attach button to attach parts to that slot

The completion bar uses colors to indicate status:

• Installed (Green): Part is physically installed.
• Reserved (Blue): Part is reserved for this slot, but not yet installed. Useful for queuing parts for a build.
• Available (Amber): Part is in stock and can be attached.
• Missing (Red): Part is not in stock. You may need to order it.

Attaching Parts

To attach a part:

1. Click the Attach button next to the line item (appears as a small arrow button).
2. Choose the source: From Inventory or Create New.
3. Set the quantity and action (Install or Reserve).
4. Click Attach.

For multi-quantity line items (e.g., "8 each Screw"), you can expand the hierarchy to see individual "slots" (1 of 8, 2 of 8, etc.) and attach to them individually if needed.

Reservations

Click on a Reserved badge to upgrade it to Installed with a single click. This is useful when you've pre-allocated parts and are now physically installing them.

Bulk Attach

If you need to attach parts to many line items at once, use the Attach Selected feature. Check the rows you want to fill, then click Attach Selected to attach available inventory in bulk.

Issues Tab

Track maintenance tickets, repair orders, or other tasks associated with this specific instance. Issues have:

• A name and description
• Open/closed status
• Comments (with notifications to followers)
• An event history

This is useful for tracking problems that arise with a specific unit after it has been built or deployed.

BOM Revisions

Items with BOMs can have multiple Revisions. If you need to update the BOM (add a new component, change a quantity, etc.), you can create a new revision of the item.

Instances are tied to a specific revision. If you have a partially-built instance on Rev A and you need to migrate it to Rev B, you can use the Revision Selector dropdown in the Instance BOM tab header. Hegemi will attempt to migrate existing attachments to matching line items in the new revision. Attachments for items that no longer exist in the new BOM will be detached.

Completion Status Graph

Every BOM instance displays a horizontal completion status graph that summarizes the attach state of all its line items, recursively throughout the entire subassembly tree.

This graph appears:

• In the Inventory tab of the Item editor (for each serialized instance)
• In the Instance BOM editor header
• In the Deliverables list when instances are associated

It provides an at-a-glance view of how "complete" the build is.