Metadata

The user-defined custom columns of the Program Data sheet and their per-space values. Accessed via snaptrude.program.metadata.

In program mode a metadata header is a custom column (e.g. "Department Code", "Occupancy", "Finish Level") on the Program Data sheet; every space can carry one value per header. This is the same store the Program tab reads and writes — values set here appear in the default Program Data sheet and in every custom sheet that shows the column, and values typed into the sheet are read back here. The store lives in the editor, so no method in this namespace needs the Program tab open.

All methods are host API calls that return Promises. Reads never throw for a miss (get returns null, list* return []). Writes are undoable (one undo step per call) and autosaved.

At a glance

Method	What it does	Mutates?
listHeaders()	List the custom columns (metadata headers) of the program sheet	—
createHeader(name, options?)	Create a custom column (reuses an existing one of the same name)	✓ (undoable)
get(spaceId)	One space's values keyed by header id, or null	—
list(spaceIds?)	Values for many spaces (or every space) in one call	—
update(spaceId, values)	Sparse write of a space's values (null clears)	✓ (undoable)
updateMany(items)	The same for up to 1000 spaces as one undo step	✓ (undoable)

Spaces only

Departments and labels also carry metadata in the engine, but this namespace covers spaces (Mass/Floor components) — the per-space case. Header ids are stable across sessions; use them (not header names) as the keys in values.

Custom sheets can group by a header

Every header id returned here is also a valid property id for program.spreadsheet.createCustomSheet's groupBy / properties, so a metadata column such as "Sub-department" can drive a custom hierarchy.

Types

PluginProgramMetadataHeader

A metadata header — one custom column of the Program Data sheet.

Property	Type	Description
headerId	string	Stable header id (the key used in metadata values)
name	string	Column header text
description	string	Column description ("" when none)
columnIndex	number	Zero-based column index on the Program Data sheet

PluginProgramMetadataRecord

One space's metadata values.

Property	Type	Description
spaceId	ComponentHandle	The space's component id
values	Record<string, cell>	Header id → value, one entry per header the space has a value for

Cells are string | number | boolean | null (the spreadsheet cell union).

PluginProgramMetadataUpdateItem

One item of updateMany — { spaceId: ComponentHandle; values: Record<string, cell> }, mirroring the update arguments. PLUGIN_PROGRAM_METADATA_BATCH_LIMIT (1000) caps a batch.

Functions

listHeaders()

List the metadata headers (custom columns) of the Program Data sheet, in column order.

• Returns: { headers: PluginProgramMetadataHeader[] } — empty when the project has no custom columns.

createHeader(name, options?)

Create a metadata header (a custom column on the Program Data sheet). Header names are unique per sheet: when a header with the same name already exists it is reused and returned (no duplicate column), so re-running a plugin is safe. The new column is appended after the sheet's existing custom columns.

• Parameters:
  • name: string — Column header text (non-empty).
  • options.description: string? — Text shown in the column's description row.
• Returns: The created (or reused) PluginProgramMetadataHeader.
• Throws: If name is blank.

get(spaceId)

Get one space's metadata values, keyed by header id.

• Parameters:
  • spaceId: ComponentHandle — The space to read.
• Returns: PluginProgramMetadataRecord | null — null when no space has that id.

list(spaceIds?)

List metadata values for many spaces at once — one host round-trip regardless of count. Prefer this over a get loop.

• Parameters:
  • spaceIds: ComponentHandle[]? — Spaces to read (unknown ids are skipped); omit for every space in the project.
• Returns: { records: PluginProgramMetadataRecord[] }.

update(spaceId, values)

Update a space's metadata values (sparse). Only the headers present in values change; null clears a value. Every key must be an existing headerId.

• Parameters:
  • spaceId: ComponentHandle — The space to write.
  • values: Record<string, cell> — Header id → new value (null clears); at least one entry.
• Returns: The space's full PluginProgramMetadataRecord after the write.
• Throws: If the space or any header id does not exist.

updateMany(items)

Update metadata values on many spaces in one undoable step. Results are in input order. Capped at 1000 items.

• Parameters:
  • items: PluginProgramMetadataUpdateItem[] — The spaces and the values to write on each.
• Returns: { records: PluginProgramMetadataRecord[] } — one record per item, in input order.
• Throws: If any space or header id does not exist (nothing is written).

Example

Store an "Occupancy" value on every space of a department and read it back.

const header = await snaptrude.program.metadata.createHeader("Occupancy", {
  description: "People per room"
});

const { departments } = await snaptrude.program.departments.list();
const clinic = departments.find((d) => d.name === "Clinic");
const { members } = await snaptrude.program.areas.listMembers("departments", clinic.id);

await snaptrude.program.metadata.updateMany(
  members.map((m) => ({ spaceId: m.id, values: { [header.headerId]: 4 } }))
);

const { records } = await snaptrude.program.metadata.list(members.map((m) => m.id));
for (const r of records) console.log(r.spaceId, r.values[header.headerId]);