Departments

Read and edit the department groupings of the active program. In program mode a department is a named, colored grouping of spaces with an optional area target — this namespace covers the program-planning view (identity, color, membership, target); the underlying space geometry is read and edited through the geometry namespaces, not here. Accessed via snaptrude.program.departments.

All methods are host API calls that return Promises. Reads never throw for a missing department (get returns null, list returns []). assign is an undoable membership change; setTargetArea sets the goal that snaptrude.program.metrics compares allocated area against.

At a glance

Method	What it does	Mutates?
list()	List every department with color and area target	—
get(departmentId)	Get a single department by id	—
create(name, color)	Create a named, colored department	✓
update(departmentId, options?)	Sparse rename / recolor of a department	✓
assign(departmentId, spaceIds)	Move spaces into a department	✓ (undoable)
unassign(spaceIds)	Return spaces to the Default department	✓
setTargetArea(departmentId, targetArea, units?)	Set the area goal the program metrics compare against	✓

One department per space

A space belongs to exactly one department. assign re-homes a space from whatever department it was in; unassign returns it to the Default department — there is no "no department" state.

Where units lives

Per the area-units convention, list carries units once on the response envelope (every targetArea in the array is in that unit). get, update, and setTargetArea return a bare record, so units sits on the record itself.

Types

PluginProgramDepartment

A department in the active program. Its targetArea is in the enclosing response's units.

Property	Type	Description
id	string	Unique department id
name	string	Display name
color	string	CSS hex color string (e.g. "#b5e1dc")
targetArea	number | null	Target area in the response's units, or null if no target is set

PluginProgramDepartmentRecord

A PluginProgramDepartment carrying its area units on the record itself — the shape returned by get, update, and setTargetArea.

Property	Type	Description
id	string	Unique department id
name	string	Display name
color	string	CSS hex color string (e.g. "#b5e1dc")
targetArea	number | null	Target area in units, or null if no target is set
units	"ft2" | "m2"	The unit targetArea is reported in

Functions

list()

List the departments in the active program — every department, well-known (Default, Site, …) and user-created, with its identity, color, and area target (when one has been set).

• Returns: { units: "ft2" | "m2", departments: PluginProgramDepartment[] } — departments is empty when the project has none; every targetArea is in units.

const { units, departments } = await snaptrude.program.departments.list();
for (const d of departments) console.log(d.name, d.color, d.targetArea, units);

---

get(departmentId)

Get a single department by id.

• Parameters:
  • departmentId: string — the id of the department to read
• Returns: PluginProgramDepartmentRecord | null — null if no department has that id; the record carries its own units.

const { departments } = await snaptrude.program.departments.list();
const dept = await snaptrude.program.departments.get(departments[0].id);
if (dept) console.log(dept.name, dept.targetArea, dept.units);

---

create(name, color)

Create a new department in the active program. The new department starts empty — put spaces in it with assign, and set its area goal with setTargetArea.

• Parameters:
  • name: string — display name of the new department
  • color: string — CSS hex color string (e.g. "#b5e1dc")
• Returns: { departmentId: string } — id of the new department (read the full record back with get).
• Throws: If the department could not be created.

const { departmentId } = await snaptrude.program.departments.create("Bedrooms", "#b5e1dc");

---

update(departmentId, options?)

A sparse update of a department's name and/or color — omitted fields are left unchanged. Use setTargetArea to change the area target (not this method).

• Parameters:
  • departmentId: string — the id of the department to update
  • options.name: string | undefined — new display name (unchanged if omitted)
  • options.color: string | undefined — new CSS hex color (unchanged if omitted)
• Returns: PluginProgramDepartmentRecord — the updated record, with the units for its targetArea.
• Throws: If no department has the given id.

const dept = await snaptrude.program.departments.update("dep_123", { name: "Suites" });

---

assign(departmentId, spaceIds)

Assign one or more spaces to a department — an undoable membership change. A space belongs to exactly one department, so assigning re-homes it from any previous one. Paired with unassign.

• Parameters:
  • departmentId: string — the department to assign the spaces to
  • spaceIds: ComponentHandle[] — the ids of the spaces to move into the department (at least one)
• Returns: { departmentId: string, spaceIds: ComponentHandle[] } — the department and the space ids that were assigned.
• Throws: If the department does not exist or a space id is invalid.

await snaptrude.program.departments.assign("dep_123", ["sp_1", "sp_2"]);

---

unassign(spaceIds)

Remove one or more spaces from their department. Each space is returned to the Default department — there is no "no department" state, so unassigning means reassigning to Default. Paired with assign.

• Parameters:
  • spaceIds: ComponentHandle[] — the ids of the spaces to return to the Default department (at least one)
• Returns: { spaceIds: ComponentHandle[] } — the space ids that were returned to Default.
• Throws: If a space id is invalid.

await snaptrude.program.departments.unassign(["sp_1"]);

---

setTargetArea(departmentId, targetArea, units?)

Set a department's target area — the goal snaptrude.program.metrics compares allocated area against. Pass units to say what unit targetArea is in; it defaults to the project's area units. Read the target back from get (targetArea).

• Parameters:
  • departmentId: string — the id of the department whose target to set
  • targetArea: number — the target area, in units
  • units: "ft2" | "m2" | undefined — unit of targetArea (defaults to the project's area units)
• Returns: PluginProgramDepartmentRecord — the updated record with its units.
• Throws: If no department has the given id.

await snaptrude.program.departments.setTargetArea("dep_123", 2000, "ft2");

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	update, assign, setTargetArea	No department has the given departmentId	—
HANDLE_INVALID	assign, unassign	A space id cannot be resolved to a component	—
OPERATION_FAILED	update	The engine rejected the update of an existing department	handles — the department id

Reads never throw: get returns null for an unknown id and list returns an empty array. assign/unassign do not throw for locked or site-restricted spaces — the engine silently skips them, and the returned spaceIds reflect only the memberships that actually changed.