Locations and Sites guide

What it is

A Location is a physical place: a building, a floor, a server room, a rack, a customer site, a service vehicle. Locations nest inside each other, and the things you manage — assets, spare-parts stock, subnets, VLANs, wall jacks, receiving sessions, purchase-order deliveries — attach to one, so you can always answer “what is at this site, and how full is it?”

Concepts

Noun	What it is
Location	One physical place. Has a type, an optional short code, an address, and a parent.
Hierarchy	Parent/child nesting to any depth: Site → Floor → Room → Rack.
Materialized path	Each location stores its ancestor chain, so a whole subtree can be rolled up at once.
Floor plan	An uploaded image of a location, with clickable hotspots that link to sites/assets.
Rack elevation	A U-by-U front/rear layout of a `RACK` location.
PDU	A power distribution unit inside a location, with a measured draw in watts.
Environmental sensor	A temperature / humidity / airflow / leak / door / smoke reading point.
Access grant	Who may enter, by what means (key, badge, PIN, biometric, combination, remote, escorted), until when.
Document	A file attached to a site — lease, floor plan PDF, permit, wiring diagram.
Audit log	Every create, edit, move and archive of a location, field by field.

Location types

WAREHOUSE, STOREROOM, CUSTOMER_SITE, VEHICLE, ZONE, RACK, SHELF, BIN, DATA_CENTER, BUILDING, FLOOR, WING, ROOM, CLOSET, CAGE, ROW, and CUSTOM — when you pick CUSTOM, the label you type is stored in customLabel and shown everywhere the type would be.

Roles and permissions

Reads are open to every role in every portal. Every mutation — locations and all sub-resources — requires organization administrator or above.

Action	CUSTOMER	power user	organization administrator	MSP technician	MSP administrator	platform administrator
View locations, tree, detail	●	●	●	●	●	●
View assets / stock / power at a site	●	●	●	●	●	●
Create, edit, re-parent, archive	—	—	●	●	●	●
Floor plans, racks, PDUs, sensors	—	—	●	●	●	●
Access grants, documents	—	—	●	●	●	●
Network ports, panels, connections	—	—	●	●	●	●

MSP technician ranks above organization administrator in the hierarchy, so organization administrator is deliberately the floor: an MSP technician floor would be stricter and would lock organization admins out of their own sites.

Portals

Portal	Path	What it shows
MSP	`/msp/locations`	The MSP’s own sites plus every managed client’s
Org	`/org/locations`	That organization’s sites
Customer	`/user/locations`	Read-only list and detail of the organization’s sites

Visibility on the MSP side resolves through AccountManagementLink, not the primary managedByAccountId alone — a co-managing MSP sees the client’s sites too.

Walkthroughs

Build a site hierarchy

Locations → New Location. Give it a name, pick BUILDING (or DATA_CENTER), and leave Parent Location empty so it becomes a root.
Fill in the address. Start typing in the address box and the autocomplete fills city, province, postal code, latitude, longitude and the IANA timezone in one go.
Optionally give it a code — a short label like YYC-HQ. Codes are unique within your account; a duplicate is refused with a clear message.
New Location again, this time setting Parent Location to the building and type FLOOR, then ROOM, then RACK. For a rack, set Total Rack Units (usually 42) — without it there is no elevation to draw.
Back on Locations, the left-hand tree shows the nesting. Click a node to filter the table to its children.

To re-parent later, open the location, Edit Location, and change Parent Location. Every descendant’s stored ancestor chain is rewritten in the same transaction, and a move that would put a site under its own descendant is refused.

Put assets and stock at a site

Assets → New Asset (or open an existing asset and Edit).
Under Site, pick the location. The list offers only active sites your tenant owns; an identifier from another tenant is refused.
Use Location detail for the free-text bit that is not a record — “Floor 2, desk 15”.
Open the site and the Assets tab now lists it, the header Assets tile counts it, and the site can no longer be archived while it is there.
Stock arrives through Receiving, which requires a location. It then shows on the site’s Inventory tab with on-hand, reserved and available quantities.

Lay out a rack

Open a RACK location. The Rack View tab appears only for that type.
Click any U slot. Set the front or rear side, a label, an asset identifier and the slot’s power draw.
Save. Failures appear in the dialog — a permission refusal is no longer indistinguishable from success.
Clear empties a slot. Clearing an already-empty slot is treated as done; anything else reports.
Rack Summary gives occupied vs total U and the front/rear split.

Track power and environment

Open a site → Power & Environment.
Add PDU: name, side (front/rear/left/right), outlet count, max amps, voltage, phase, and the measured draw in watts.
Add Sensor: type, warning and critical thresholds, last reading.
The Power Budget panel compares the site’s maxPowerWatts against the summed draw of every PDU in the site and everything under it — a rack’s PDU counts toward the building that contains it.
Locations → Capacity Planning rolls the same numbers up across every site, flags anything at 80% (warning) or 90% (critical) on rack or power, and lists the offenders.

Upload a floor plan and link hotspots

Open a site → Floor Plan → Add Floor Plan. Upload a PNG or JPEG.
Rename / Scale sets the plan’s name and its real-world scale in pixels per metre. Make Primary promotes one plan when a site has several.
Edit Annotations places hotspots. A hotspot may link to another location or to an asset; both are resolved inside your tenant before they are saved, so a hotspot can never point at another tenant’s record.
In view mode, clicking a hotspot navigates to that site or asset in the portal you are already in.

Control site access

Open a site → Access.
Grant Access: pick a person (or type a name, email and phone for an external holder), choose the access type, record the badge number, PIN or combination, set an access level, and set an expiry if it is temporary.
Revoke stamps revokedAt; the grant stays on the record as history.

Read the change history

Open a site → Audit Log. Every create, field-level edit, move and archive is recorded with who did it, from which IP, and when. Filter by action, page through with Previous/Next — the header count is the true total, not the page size.

Configuration

Setting	What it does	If unset
`name`	Display name	Required
`type`	One of the 17 location types	Required
`customLabel`	The label shown when `type = CUSTOM`	Falls back to “Custom”
`code`	Short site code, unique within the account	Blank; the site is identified by name
Address fields	Street, city, province, postal code, country (default `CA`)	Address panel shows dashes
`latitude` / `longitude`	Recorded from the address autocomplete; shown as coordinates	Coordinates row hidden
`timezone`	IANA zone; drives the site’s local clock on the detail page	No local-time row. See Limits
`parentId`	Parent in the hierarchy	The location is a root
`customerOrgId`	Links a `CUSTOMER_SITE` to a client organization	No Customer row
`maxCoolingBTU`, `maxWeightKg`	Recorded and displayed; no calculation reads them	Row hidden
`totalRackUnits`	Rack height in U; required to draw an elevation	Rack View asks you to set it
`floorArea`, `ceilingHeight`	Recorded and displayed	Row hidden
`commissionedAt`, `decommissionedAt`	In-service and out-of-service dates	Rows show dashes
`primaryContactPersonId` or static name/email/phone	Site contact; a linked person wins over the static fields	Contact panel empty
`photoUrl`	Site photo shown on the Overview tab	No photo panel
`sortOrder`	Ordering among siblings	`0`; ties break on type then name
`isActive`	Archived sites read “Inactive” and are hidden from the tree by default	`true`

Plan tiers

Locations and Sites carries no plan gate. There is no entitlement check, no tier check and no seat cap anywhere in it. Every paying tier gets the whole feature. What a person sees is decided by portal and role only.

Note that assets do carry a per-tier cap (assertAssetLimit on asset creation), so the number of things you can place at a site is bounded by your asset entitlement even though the sites themselves are not.

Troubleshooting

Message	Cause
`A location with code "X" already exists`	Codes are unique per account. Pick another or clear the other site’s code.
`Unknown timezone "X" — use an IANA zone such as America/Edmonton`	The zone is not one Node’s ICU data knows. Use `Region/City`.
`Location cannot be its own parent`	`parentId` equals the location’s own id.
`Cannot move location under its own descendant`	The target parent is somewhere below this node. Move the subtree first.
`Parent location belongs to a different organization`	A site’s tree cannot span two tenants.
`Cannot delete location with child locations`	Archive or re-parent the children first.
`Cannot delete location with assigned assets`	Move the assets to another site, or clear their site.
`Cannot delete location with inventory items`	Transfer the stock first.
`Cannot delete location with active receiving sessions`	Complete or cancel the receiving session.
`Cannot permanently delete a location with receiving history`	Permanent delete only; archive instead to keep the history.
`Cannot permanently delete a location with network records (subnets, VLANs or ports) assigned to it`	Detach the IPAM records first, or archive instead.
`Cannot permanently delete a location referenced by a contract`	Remove the contract’s site scoping first.
`Location is not a rack`	Rack-unit routes only accept `type = RACK`.
`Position must be between 1 and N`	The rack’s `totalRackUnits` is smaller than the slot you asked for.
`Customer organization not found`	`customerOrgId` is not an organization you can see. Foreign and non-existent read the same.
`Linked location not found` / `Linked asset not found`	A floor-plan hotspot pointed outside your tenant.
`locationId does not reference a location in your organization`	An asset was filed against a site you do not own.
`Ship-to location not found`	A purchase order named a site outside your account.
`Organization not managed by this MSP`	The `organizationId` filter is outside your managed set.
`Insufficient role`	Mutations require organization administrator or above.

Limits and known behaviour

timezone is informational. It drives the site’s local clock on the detail page and nothing else. SLA clocks, business hours and scheduling windows all resolve their zone from the organization-level BusinessHours record. A site in America/Vancouver under an organization whose business hours say America/Toronto is worked to Toronto hours.
maxCoolingBTU, maxWeightKg, floorArea and ceilingHeight are recorded and displayed but nothing calculates against them. Only maxPowerWatts and totalRackUnits drive utilization.
Latitude and longitude are recorded and displayed as coordinates. There is no map view, no distance calculation and no routing.
The Capacity Planning dashboard rolls up root-level sites, up to 100 of them, fetching each one’s stats. Each site’s figure already includes its whole subtree.
Deleting is archiving. DELETE sets isActive = false and keeps the row. Permanent deletion exists on the org router only, and refuses any site that still has records pointing at it.
Archiving does not cascade. A site with children cannot be archived at all; archive or re-parent the children first.
/ancestors, /descendants, /move, /reorder, /inventory and the single-floor-plan GET are org-scope only. The MSP router does not serve them. Re-parenting from the MSP portal goes through PUT /:id, which does the same work.
Rack elevations need a height. A RACK with no totalRackUnits shows a prompt to set one rather than drawing a default.
The audit log records locations, not their sub-resources. Creating a PDU or revoking an access grant is not written to LocationAuditLog.