Overview

Excel Upload — Device Discovery enables deployment teams to import devices, points, metadata, and ontology mappings into KODE OS using a structured spreadsheet before live data source connectivity is available.

This feature is designed to remove deployment delays caused by network readiness dependencies such as VPN access, firewall approvals, or data source routing. Instead of waiting for live connectivity, teams can begin modeling the building structure immediately using exported device and point information, commonly sourced from Niagara or similar building management systems.

By importing the expected device and point structure into KODE OS ahead of discovery, teams can continue critical deployment activities such as:

• Device organization

• Metadata assignment

• Ontology templating

• Graphics development

• Dashboard configuration

• Virtual device structuring

Once the data source is connected and discovery is completed, KODE OS automatically recognizes the previously imported entities as existing records and begins live point collection without requiring the deployment to be rebuilt.

The feature also supports iterative spreadsheet uploads, allowing teams to continuously add new devices and points or update supported metadata as the deployment evolves.

Excel Upload — Device Discovery helps organizations accelerate deployments, reduce manual configuration work, standardize onboarding processes, and enable parallel execution between deployment and IT/networking teams.

Core Functionality

• Pre-Connection Deployment: Users can import device and point data into the database to begin templating, area assignment, and graphics creation immediately.

• Automatic Merging: Once a physical connection is later established and devices are discovered, the system automatically merges them with the imported data to start collecting live information.

• Virtual Device Creation: The import sheet can be used to split data source folders into separate virtual devices directly during the import process.

Import Requirements

The process requires a template sheet populated with accurate data exported from the original data source (e.g., Niagara) to ensure correct mapping during future discovery. Required fields include:

• Device Information: External ID, external path, and device name.

• Point Information: External ID, external path, name, and point kind.

Sheet Capabilities

Beyond basic data import, the sheet supports full configuration of several deployment aspects:

• Templating: Assigning device types and point ontology (suffixes, prefixes, and display names).

• Location Mapping: Assigning devices to specific floors and zones; the system will automatically create new floors if they do not already exist in the building.

• Enum Mapping: Defining enumerations directly within the spreadsheet.

Process Overview

1. Add Data Source: Initialize the data source within the building profile.

2. Download Template: Access the "Import with sheet" option from the three-dot menu to get the necessary template. Template can be found here.

3. Fill and Import: Populate the sheet, ensuring device names are repeated for every associated point, and upload it.

4. Connect and Discover: Once the connection is live, run device discovery; existing imported devices will show up, requiring only a cache refresh to begin data collection.

Note: The import runs as an asynchronous background job with validation before persistence. Only one Excel discovery job can run per data source at a time.

Required Columns

For devices:

• Device External ID

• Device External Path

• Device Name

For points:

• Point External ID

• Point External Path

• Point Name

• Point Kind

Note: Re-uploading sheets is supported. The system decides whether to create or reuse entities.

Devices

• New physical device → created

• Existing physical device → only these fields can be updated via re-upload (if provided):

• Area

• Location

• Zone

All other device fields remain unchanged and can’t be updated in this version.

Virtual devices

• New virtual device name → created

• Existing virtual device name → reused, and its Area/Location/Zone can be updated (if provided)

Points

• New point External ID → created

• Existing point External ID → core point fields are not overwritten; only these can change, driven by device metadata updates:

• Area (cascaded)

• Device Location (cascaded)

• Device Zone (cascaded).

Updating only the Device External ID from a previous upload

If the uploaded sheet is detected as being in device update mode the job bypasses the full pipeline and only updates device External IDs by their path. No devices or points are created or modified in this mode.

To only update the Device External ID, only fill the:

• Device External ID

• Device External Path

Virtual devices

Virtual devices are used when a data source reports points for multiple logical devices under one physical device/folder.

Rules:

• Virtual devices are defined via a “Virtual Device Name” value on point rows.

• Points with a virtual device name are assigned to that virtual device.

• Points without a virtual device name remain assigned to the base device.

• New virtual devices inherit canonical type, device type, area, and location from the referencing rows.

• Consistency validation is enforced for new virtual device names: mixed canonical type / area / device type / location for the same new virtual device causes the job to fail.
  
  

Areas and device types

• If Area Name does not exist, it can be created automatically (including optional ordering).

• If Device Type does not exist, it can be created automatically.

Ontology mapping and validation

Ontology validation is evaluated per device group.

Rules (high-level):

• If canonical type is not provided, ontology mapping is skipped.

• If canonical type is not recognized, ontology fields may be cleared.

• If ontology field is invalid for the canonical type, import fails for that device group.

• Kind mismatch between point kind (Number/Str/Bool) and ontology field requirements can fail validation.

• When valid, missing ontology defaults are backfilled (display name, precision, COV tolerance, etc.)

What happens when the data source is later discovered

• When the data source is eventually connected and discovery runs, imported devices and points appear as existing.

• Once discovery completes successfully, those points begin collecting normally. 

Importing Devices and Points Using a Spreadsheet Template  

Use the Excel Upload — Device Discovery workflow to create devices, points, metadata assignments, and optional virtual devices in KODE OS through a structured spreadsheet import process. 

1. Navigate to Data sources and open the target data source.

2. Open the overflow menu (three dots) and select Import from Sheet.

3. Click Download Template in the import dialog.(Template)

4. Fill out the template:

• Device identifiers and paths

• Point identifiers and paths

• Optional virtual device name (only where points should be split into a virtual device)

• Optional device metadata (Area/Location/Zone)

• Optional ontology columns (field, display name, precision, COV, default graph, ontology unit, mappings)

5. Upload the completed .xlsx file.

6. Click Import.

Re-upload to add new points or update allowed metadata

Use the same flow above. Re-upload is the recommended approach for iterative enrichment:

• Add new points by introducing new Point External IDs

• Update device metadata (Area/Location/Zone) by setting those columns on device rows

• Update virtual device metadata (Area/Location/Zone) by providing it consistently for that virtual device name

Split a device using virtual devices

1. In the template, keep the base device identifiers the same for the device folder/source device.

2. For points that belong to a logical device, set Virtual Device Name to the desired virtual device name.

3. Ensure all points under the same new virtual device name have consistent:

• Canonical Type

• Area

• Device Type

• Device Location

4. Import the sheet.

Apply ontology templating during import

Provide Device Canonical Type for the relevant device rows (or ensure points provide a consistent canonical type through the group).

1. Fill Ontology Field for points that should be mapped.

2. Optionally set ontology columns (precision, display name, COV tolerance, default graph, unit, mappings).

3. Import the sheet.

4. Review points in Point Modeling after import.

Important: After connectivity is established: turn on collection

1. Establish data source connectivity.

2. Run normal data source discovery.

3. Confirm devices show as existing and points begin collecting after discovery completes.

Below you can find another sheet with most FAQs.