Workbook Overview

Your workbook has three sheets you'll work in, plus reference sheets that help you along the way.

Sheets you fill out

Reference sheets (do not edit)

Color coding

The workbook highlights cells automatically to flag problems:

How to use this guide

Work through each step in order:

1. Step 1 — List your equipment (entities sheet)
2. Step 2 — Define relationships (relations sheet)
3. Step 3 — Assign data points (points sheet)
4. Tips — gotchas, conventions, and rules of thumb

The relations and points sheets reference entity names, so the entities sheet must be filled out first.

Step 1 — List your equipment (entities sheet)

Each row is one piece of equipment in your building. You fill in columns A and B only — columns C through G are calculated automatically.

Note: Floors, Spaces, and Rooms should not be created via workbook. Instead, reference the existing Place in the relations tab when required

If you need to remove a row, delete the entire row (right-click the row number → Delete Row). Don't just clear or delete the visible cells, or the hidden metadata will be left behind and trigger validation errors.

If you sort this sheet, make sure your sort selection covers every column — including the hidden ones — so the metadata stays attached to the right row.

Rules

• Names must be unique — no two entities can share the same name.
• Type must come from the _entity_types list — use the dropdown or copy a value from that sheet. Do not use a point type here (e.g., Temperature_Sensor is a point type, not an entity type).
• Every entity should have at least one relationship or point — if columns C through G are all zero, the row highlights yellow as a warning.

Naming conventions from completed examples

• Use a building or system prefix to keep names clear: ABC-CHWP-2, AHU-01.
• Name sub-components by appending to the parent: AHU-01-CoolingCoil, AHU-01-SupplyFan, AHU-01-OAD.
• Keep names consistent — once you pick a convention, use it throughout.

Common entity types

Refer to the _entity_types sheet for the full list of 2,000+ valid types.

Step 2 — Define relationships (relations sheet)

Each row defines one connection between two entities from your entities sheet. This is how you describe how the equipment you listed in Step 1 relates to each other — what contains what, what feeds what, etc.

If you need to remove a row, delete the entire row (right-click the row number → Delete Row). Don't just clear or delete the visible cells, or the hidden metadata will be left behind and trigger validation errors.

If you sort this sheet, make sure your sort selection covers every column — including the hidden ones — so the metadata stays attached to the right row.

Rules

• Source: Use column B (name) for entities you created. Use column A (lookup_id) only for entities that already exist in the system. Never fill both.
• Target: Same rule — use column D (name) or column E (lookup_id), not both.
• relation_type must be one of the four valid types (see below).
• No duplicate rows — if all five columns match an existing row exactly, it highlights yellow.

Referencing existing Entities or Places

When adding relations that involve Floors, Spaces, or Rooms, these Places should first be created outside of the workbook workflow to ensure the Floor Level or Space Code is attached. These Places can then be referenced by using the Mapped ID in the source_lookup_id or target_lookup_id columns

Relationship types explained

Typical patterns

AHU with components

Terminal unit feeding a zone

Pump located in a mechanical room

Point belonging to previously created Thing

VAV with location of a Floor

Field controller controls a VAV

Step 3 — Assign data points (points sheet)

Each row represents one data point from your BAS or IoT system. Many points may be pre-populated from a live data import — your job is to fill in or correct the isPointOf (column B) and type (column C) columns with the entities you've created.

Unassigned and unclassified points are skipped. Points with blank isPointOf and type won't be included in the import. If you don't know where a point belongs, you can leave it blank and come back to it later.

Rules

• isPointOf must match an entity name — if the value doesn't exist in the entities sheet column A, the cell highlights red. To assign a point to a previously existing entity, use the relations tab.
• type must come from the _point_types list — if the value isn't in the valid list, the cell highlights red.
• Use the point's BAS name (column D) and description (column E) to determine the correct type and which entity it belongs to.

How to assign points

1. Look at the name column (D) — this is the original BAS point name (e.g., NAE38/N2 Trunk 1.NC44_HDW VMA-12.LWTU1-10 COMMONSP).
2. Use your knowledge of the building systems to determine which equipment this point belongs to.
3. Enter that equipment's name in the isPointOf column (B) — it must exactly match a name from the entities sheet.
4. Determine the point type from the name/description and enter it in column (C).

Bulk-assigning points

When you have hundreds or thousands of points, filling in isPointOf one row at a time is impractical. Use the point metadata columns (name, device_instance, ip_address, etc.) to identify groups of points that belong to the same entity, then assign them all at once.

Common point types

Refer to the _point_types sheet for the full list of 1,300+ valid types.

Tips

Workflow

• Work through the sheets in order: entities first, then relations, then points. The relations and points sheets reference entity names, so those need to exist first.
• Watch the colors: Fix all red cells before submitting. Yellow cells are worth reviewing but may be acceptable (e.g., a top-level building entity with no outgoing relationships).
• Check the auto-calculated columns: After adding relations and points, look at columns C–G in the entities sheet. If an entity has all zeros, it probably needs relationships or points added.

When you're updating a workbook that has already been imported, don't delete entities, relations, or points unless you actually want them gone. Anything you remove will be treated as a removal from the building model — the entity will be dematerialized from the graph.

Don't touch reference sheets

The _entity_types, _point_types, _relationship_types, and _metadata sheets are system-managed. Editing them may cause validation errors.