Pathways¶

Pathways represent the physical routes that cables follow between structures and locations. Outdoor pathways have a LineString geometry defining their geographic path; indoor pathways (between two locations) have no geometry.

Pathway Types¶

Conduit¶

A pipe or duct that cables are pulled through. Conduits are the most common pathway type for underground infrastructure.

Aerial Span¶

An overhead route, typically between poles.

Geometry of an aerial span¶

An aerial span hangs between two supports, so its geometry is not drawn freely:

• Both ends must be attached. Each end needs a structure with geometry: the start/end structure, or the structure enclosing the start/end location (see How pathway ends attach). A span with a floating end is rejected, and so is a span whose two ends belong to the same structure.
• It is always a straight line. The path is exactly two vertices; intermediate vertices are dropped on save. The map editor hides the add-vertex handles and blocks vertex removal for aerial spans.
• A pole pins its end. On a point structure the end sits exactly on the structure, whatever coordinate was submitted.
• A building offers a landing. On a polygon structure (a building footprint, typically the structure linked from a Site Geometry) the end lands on the footprint's outline. Drag the end along the outline to choose where the span lands; the nearest outline point is kept. Without a drawn path the end lands on the wall facing the other support.

Direct Buried¶

A cable path buried directly in the ground without a conduit.

Innerduct¶

A smaller duct installed inside a parent conduit to subdivide capacity.

Color is picked from NetBox's standard palette, the same widget used for rack roles and cables, and renders as a swatch in innerduct tables and on the parent conduit's detail page. CSV import also accepts a color name (Blue) or a bare hex code (2196f3); slate and violet from the telecom 12-color code map onto the nearest palette entries.

Innerducts inherit start and end endpoints (structures or locations) from their parent conduit if not explicitly set.

The Innerducts panel on a conduit's detail page has an Add button that opens the innerduct create form with the parent conduit and its endpoints pre-filled. Innerducts never need their own path geometry -- the parent conduit owns the route. Lifecycle fields (installer, dates) are not inherited: innerducts are usually installed separately. An innerduct without a tenant shows the parent chain's tenant marked with * in tables.

Endpoints¶

Every pathway has a start endpoint and an end endpoint. These can be:

• Structure — An outdoor structure (pole, manhole, etc.)
• Location — An indoor NetBox location (room, floor)
• Junction — A conduit junction (conduits only)

You can mix endpoint types. For example, a conduit starting at a manhole (structure) and ending at an equipment room (location) models a building entrance path.

Indoor pathways¶

When both endpoints are locations, the pathway is indoor and the geographic path is optional -- NetBox locations carry no coordinates, so there is nothing to draw. Simply pick the two locations and save; the pathway is created without geometry and does not appear on the interactive map or in the GeoJSON API layers. A path is still required whenever either endpoint is geographic (a structure or a junction).

Creating a Pathway¶

1. Navigate to the appropriate pathway list (e.g., Plugins > Pathways > Conduits)
2. Click Add
3. Set the name, endpoints, and type-specific fields
4. Draw the path on the map widget or enter geometry manually
5. Save

Pathway on the Map¶

On the interactive map, pathways render as colored lines:

Clicking a pathway line opens the sidebar with details including endpoints, length, type-specific attributes, and routed cables.

Length: drawn vs as-built¶

Every pathway carries two length values:

The two values are intentionally separate -- they usually disagree, and that disagreement is information (slack, vertical drops, recently re-drawn geometry that has not been re-measured in the field, etc.).

geo_length is exposed:

• on the detail panel next to Length (m, as-built),
• as a sortable "Geo length (m)" column on each pathway list (off by default; toggle from the "Configure" menu),
• on the REST API and GeoJSON endpoints (read-only),
• as range filter parameters ?geo_length__gte=... and ?geo_length__lte=... on every Pathway list / API endpoint.

Lifecycle¶

Every pathway carries the following lifecycle fields, in addition to the type-specific fields above:

Filtering¶

Pathway lists support filtering by:

• Status -- Filter by lifecycle state
• Pathway Type -- Conduit, Aerial, Direct Buried, etc.
• Start/End Structure -- Filter by connected structures
• Site -- Filter by associated site
• Material -- Conduit material (conduits only)
• Tenant -- Filter by owning tenant (served customer)
• Installed By -- Filter by installer/contractor tenant
• Installation Date / Commissioned Date -- Filter by date
• Has Path -- Filter pathways with/without geometry
• Geo length range -- ?geo_length__gte=<m> and ?geo_length__lte=<m> filter pathways by their drawn length. Filtering runs as a PostGIS ST_Length(path) predicate, so it scales with database indexes rather than Python iteration.

Intermediate Locations¶

Pathways can pass through intermediate locations (sites or rooms) along their route. Use Pathway Locations to record these waypoints with sequence numbers for ordering. This is useful for documenting that a conduit passes through multiple manholes along its route.

Cloning¶

Every pathway detail view has a Clone button. Cloning pre-fills the create form with the source object's status, endpoints, installer, dates, and type-specific attributes (faces and bank for conduits, span attributes for aerial spans, burial attributes for direct-buried runs, parent conduit, size, and color for innerducts). The route geometry, label, and per-parent positions are never copied, so you can document parallel runs quickly and then draw each path.

Keeping pathway ends attached to structures¶

Pathway ends follow the structures they are attached to. When a structure's geometry is edited -- in the UI, through the REST API, by CSV import or by bulk edit -- every pathway end belonging to it (directly, or through a location it encloses -- see How pathway ends attach) moves with it, in the same transaction:

• Conduits, direct-buried runs and other pathways keep their interior vertices; only the end vertex moves.
• Aerial spans are rebuilt as the straight line between their supports.
• An end on a moved or reshaped building keeps its relative position on the outline, so a landing on the east wall stays on the east wall.
• Conduits branching off a moved conduit at a junction follow the junction's new position.

Each rewritten pathway gets its own change-log entry.

Writes that bypass a structure's save -- queryset update(), bulk_update, raw SQL, a restored database dump -- leave pathway ends behind. The reanchor_pathways management command finds and repairs them:

python manage.py reanchor_pathways                       # report only
python manage.py reanchor_pathways --structure 17 23     # pathways on these structures
python manage.py reanchor_pathways --type aerial --apply # repair aerial spans

It reports every pathway end farther than the endpoint tolerance (1.0 SRID unit) from its structure or junction, and every aerial span that is bent (more than two vertices) or detached. --apply repairs everything found in one transaction: ends land on their structure (the nearest outline point for a building, since the geometry before the bulk write is unknown), aerial spans are straightened, and junction branches follow. Detached aerial spans are reported but left alone -- there is no structure to land them on; attach them in the UI. As with split_pathway, --user <username> runs the repair inside NetBox's event pipeline so it is recorded in the change log.

Splitting an imported pathway at structures¶

Geometry imported from KMZ files or other OSP tools often arrives as one long polyline that physically passes many structures (a pole line, for example) but is stored as a single pathway. In the pathways data model a span is the hop between two structures, so the mid-span structures are not connected to the pathway at all: nothing can branch or be routed at them, and per-hop attributes cannot be recorded.

The split_pathway management command replaces such a pathway with consecutive per-hop pathways of the same type:

python manage.py split_pathway 42                     # preview candidates
python manage.py split_pathway 42 --exclude 17 --apply

The default run is a dry-run preview: it detects structures within --tolerance (SRID units, default 1.0) of the pathway's line, excluding its endpoints, and prints them ordered by chainage together with each structure's offset from the line and the resulting hop layout. Nothing is written until you re-run with --apply.

• --exclude ID ... drops false positives from the detected candidates (a parallel pole line caught by the tolerance, for example).
• --structures ID ... bypasses detection and splits at exactly the given structures.

On apply, in one transaction:

• The pathway is replaced by one child per hop, with vertices preserved and the cut vertices snapped onto the structure points. Shared attributes, tags, and custom fields are copied; per-side attributes (faces, attachment heights) stay on the first and last child; labels get an (i/total) suffix.
• A conduit bank's conduits and their innerducts are cascaded into per-hop copies attached to the corresponding hop.
• Cable segments routed through the pathway are replaced by per-hop segments in path order, preserving sequence order and lashing.
• The original pathway is deleted.

The command refuses indoor pathways (no geometry), innerducts and bank-contained conduits (split the container instead), and conduits with junctions (their positions along the trunk would be invalidated). Planned routes referencing the pathway are reported so they can be re-planned; waypoints cannot be repositioned and are deleted with the original.

By default split_pathway operates outside NetBox's request pipeline: the deletion and creations do not produce change-log entries, webhooks, or event-rule triggers, and the dry-run preview is the review step. Pass --user <username> to run the apply inside the event pipeline instead -- the change log then records the split attributed to that user (grouped under a single request id), and webhooks and event rules fire as they would for a UI edit.