Network Sites

Overview

Network Sites in gaiia represent the physical and logical locations that make up an ISP's network — POPs, headends, cabinets, splitter enclosures, remote DSLAMs, towers, huts, and any other place where you need to track what's installed and what it connects to. A Network Site is the anchor that ties together the equipment at a location, the IP space serving that location, the customers downstream of it, and the incidents that affect it.

Network Sites are designed to answer questions your NOC, field techs, and support team ask every day:

• What's installed at this location, and what else depends on it?
• If this cabinet goes down, which customers are affected?
• Which IP prefixes are assigned here?
• Where is this site on the map, and how does it connect to the rest of the network?

Network Sites are referenced by Inventory, Incidents, Work Orders, Tickets, and the NetBox integration.

How Network Sites work in gaiia

A Network Site has:

• A name and reference ID. The name is how people find the site in the UI; the reference ID is a stable external identifier you control (useful for CSV imports, integrations, and aligning with a system of record outside gaiia).
• An address and coordinates. Full structured address fields (line 1, line 2, locality, region, postal code, country, county, premise, thoroughfare, sub-building) plus latitude and longitude for map placement.
• Assigned inventory. Any number of inventory items (equipment) can be assigned to the site. Those items can themselves have upstream/downstream relationships, which the site's topology and map views use to show how everything connects.
• IP blocks. One or more CIDR prefixes can be associated with the site, with optional descriptions. These can be managed manually or kept in sync automatically via the NetBox integration.
• Custom fields. Configurable per-tenant fields (text, dropdown, text list, number, number list, toggle) so you can capture the attributes your business actually cares about — e.g. power feed, rack ID, fiber panel, landlord contact.
• Tickets, work orders, projects, and documents. Attached directly to the site so that the full operational history of a location lives in one place.

Creating a Network Site

Network Sites live under Network → Sites. To create one:

1. Click Create Network Site on the list page.
2. Enter a Name (required)
3. Fill in the address fields. If you provide Latitude and Longitude, the site will be placed on the map view automatically.

4. Save.

   
    

   

You can then assign inventory, IP blocks, and custom field values on the site's detail page. Users need the network.sites.edit permission to create or modify sites, and network.sites.view to see them.

Viewing Network Sites

The Network Sites list shows every site in your tenant, sortable by name, address, coordinates, or creation date, with 25 rows per page by default. A search bar at the top lets you filter by name or reference ID.

From the list, click any site to open its detail page, which uses a tabbed layout:

• Details — name, reference ID, address, coordinates, and custom field values.
• Connected Devices — the full topology of inventory reachable from this site (see below).
• Equipment — inventory items directly assigned to the site.
• IP Blocks — CIDR prefixes associated with the site, with their descriptions.
• Work Orders — any work orders scheduled at or referencing this site.
• Tickets — support tickets that reference the site.
• Documents — attached files (photos, as-builts, contracts, access instructions, etc.).
• Projects — longer-running project work tied to this site.

Assigning items to a Network Site

Inventory (equipment)

Any inventory item can be assigned to a Network Site from the site's Equipment tab. This is how you express "this OLT lives at this POP." Once assigned, the item will appear in the site's Equipment tab and participate in the site's topology and map views.

IP blocks / Prefixes

IP blocks (or IP Prefixes) are added from the IP Blocks tab on the site detail page. Each block is a CIDR prefix (IPv4 or IPv6) with an optional description. Blocks can be edited or removed from the same tab.

If you run the NetBox integration, prefixes that NetBox assigns to a site of the same name will appear here automatically — see NetBox integration below.

Custom fields

Custom field definitions are configured at the tenant level by users with the network.settings.edit permission. The supported types are:

• Text — free-form short string.
• Dropdown — single selection from a predefined list.
• Text list — an arbitrary list of strings.
• Number — single numeric value.
• Number list — an arbitrary list of numbers.
• Toggle — on/off.

Once defined, fields appear on every Network Site's detail page and can be filled in per site. Use them for anything your team references repeatedly — power circuit IDs, fiber panel numbers, landlord contacts, access codes, site class — so it's always in the same place.

Upstream and downstream relationships, and the map view

One of the most important things Network Sites do is visualize how the network actually fits together. gaiia supports two complementary views: a Connected Devices (logical topology) view and a Map (physical/geographic) view.

Connected Devices (logical topology)

Inventory items in gaiia can declare upstream and downstream relationships to other inventory items. For example, a customer ONT is downstream of a splitter, which is downstream of an OLT port, which is downstream of an OLT chassis.

The Network Site Connected Devices tab shows direct downstream children of site-assigned equipment — one hop, downstream, paginated.

Upstream assignments between inventory items are managed on the inventory item itself, not on the Network Site directly. Once the inventory is wired up correctly, the Network Site view stays in sync automatically.

Topology visual map

Any piece of equipment in gaiia — whether viewed directly from Inventory or via a Network Site's Equipment tab — has a Linked devices sub-tab with a visual topology map. It's a graph of the equipment and what it connects to, rendered as boxed device cards joined by connecting lines, with the selected item in the middle and its upstream and downstream neighbors radiating out.

Each node on the graph shows the essentials at a glance: model, manufacturer, unique ID, the Network Site the device is assigned to, and the account it serves (when applicable).

A Depth control in the top-right corner lets you expand the graph one hop at a time in each direction. It starts at 1 — showing only direct neighbors — and can be increased to walk further up toward the core of the network and further down toward customer premises.

A Link devices action on the same toolbar lets you add new upstream/downstream relationships directly above the map.

Network Sites and incidents

Network Sites are integrated with gaiia's Incident Manager. When an incident is opened, you can quickly scope it to the parts of the network it actually affects by impacting the relevant Network Sites.

Adding impacted sites to an incident

When creating a new incident, or when editing the details on an existing incident, add any network sites via the Network sites field. Search for and add any sites affected by the outage or event.

Once added, the incident tracks which sites are impacted and surfaces that on the map and in reporting.

Automatically pulling in impacted accounts

The real power comes from the Add Accounts from Network Sites action on an incident.

When you trigger this, gaiia walks the downstream topology of every impacted Network Site and adds each customer account served by the downstream inventory to the incident's impacted accounts list — automatically. By default, only accounts with an active service status are included, so paused or cancelled accounts aren't pulled in as collateral damage. This removes a huge amount of manual work during an outage: instead of guessing who's affected, you add the sites that are down and gaiia enumerates the customers for you.

NetBox integration

If you use NetBox as your IPAM / DCIM system of record, gaiia keeps IP prefix assignments (IP Blocks) in sync with NetBox automatically. When a prefix is assigned to a site in NetBox, gaiia creates or updates the matching IP block on the Network Site of the same name in gaiia. Site matching is by exact name (case-sensitive), so name your NetBox sites and gaiia Network Sites the same way.

For the full setup and field-mapping details, including supported NetBox versions, webhook configuration, and troubleshooting, see the NetBox Integration article.

API access

Network Sites are fully available through the gaiia GraphQL API. You can list, create, update, and manage sites, IP blocks, and custom field values programmatically; query the topology of a site; and perform the incident operations described above.

The full API reference, including the Network Site schema and every available query and mutation, is at app.gaiia.com/docs/overview.

Useful starting points in the schema:

• networkSite / networkSites
• createNetworkSite / updateNetworkSite
• networkTopology / paginatedConnectedDevicesForNetworkSite
• networkSiteIpBlocks, addIpBlocksToNetworkSite, removeIpBlocksFromNetworkSite, updateNetworkSiteIpBlock
• networkSiteCustomFieldDefinitions
• addImpactedAccountsToIncidentFromNetworkSites

Recommendations for ISPs

• Model every location that matters, but nothing more. Create a Network Site for anything you'd dispatch a tech to, reference in an incident, or need to trace inventory through.
• Wire up upstream/downstream relationships on inventory. The value of the Connected Devices and incident-automation features scales directly with how accurately your inventory topology is modeled.
• Always populate latitude and longitude. Sites without coordinates won't appear on the map.
• Define custom fields for the things your team looks up constantly.
• Use documents and work orders on the site.
• Name sites the same way in gaiia and NetBox.