11 min read2,384 words

Configuring Connectivity Rules for Pipe & Cable

Connectivity rules are the constraint layer that decides which assets are allowed to join, at which terminals, and under what material, pressure, or phase conditions. When they are wrong, the network does not throw a loud error — it produces silent failures: a closed valve that a trace walks straight through, a service lateral that never appears in a downstream result, a three-phase splice that drops a conductor without warning. This guide covers authoring, validating, and deploying connectivity rules for pipe and cable within the broader topology and tracing workflows framework, targeting utility engineers, GIS technicians, Python automation builders, and infrastructure teams who need deterministic, auditable rule sets.

The failure mode this solves

The defining symptom of a misconfigured connectivity matrix is a trace that succeeds while returning the wrong answer. Because the utility network model only permits edits that satisfy published rules, engineers often assume that a clean topology build implies correct topology. It does not. A rule set can be internally consistent and still encode the wrong physical reality — for example, allowing a 200 mm main to bond directly to a 50 mm lateral with no reducer, or treating a fiber strand inside a duct as a topological connection rather than containment.

These defects surface downstream as three recurring patterns. Orphaned terminals occur when an asset type is published with more terminals than any rule references, leaving connection points that no edge can ever occupy. Phantom subnetworks appear when a permissive rule lets unrelated asset groups bond, fusing two pressure zones or electrical phases into one logical network. Premature termination happens when a rule omits a legitimate junction-to-edge pairing, so an upstream and downstream trace stops short of the real network boundary. Each of these compromises isolation reliability, hydraulic and electrical analysis, and field-edit synchronization — and none of them announces itself. The remedy is to treat connectivity rules as executable constraints that are version-controlled, validated against a staging dataset, and re-checked on every change.

Correct terminal-paired reducer rule versus a permissive misconfiguration Two side-by-side reducer junctions. The valid case pins the large-diameter edge to Terminal 1 and the small-diameter lateral to Terminal 2, so an isolation trace resolves cleanly. The misconfigured case lets the large main bond straight to the lateral, leaving Terminal 2 with no edge it can occupy and fusing two pressure zones into one phantom subnetwork. Correct — terminal-paired rule 200 mm main Reducer T1 T2 50 mm lateral Trace walks T1 → T2 deterministically T1 → large edge, T2 → small edge. Pressure zones stay distinct; isolation resolves. Misconfigured — permissive rule 200 mm main Reducer T1 T2 orphaned phantom-subnetwork bridge 50 mm lateral Large main bonds straight to lateral T2 has no edge it can occupy → orphaned. Two pressure zones fuse; trace returns wrong answer.

Prerequisite checklist

Confirm each item before authoring or publishing rules. These are the conditions that most often cause rule deployment to fail or to validate against the wrong baseline.

Core data model: terminals, edges, and the connectivity matrix

The utility network enforces a strict edge–junction and edge–edge model. Linear assets (pipe, cable, conduit) are edges; point assets (valves, fittings, splices, transformers) are junctions that bridge, terminate, or contain connectivity. A connectivity rule is a permission statement: it declares that a specific asset type, at a specific terminal, may connect to another specific asset type or edge. Anything not explicitly permitted is forbidden, which is why omissions cause silent termination rather than visible errors.

Two model properties dominate correct authoring:

Terminal configuration and pairing. Devices that change a network property carry multiple terminals with directional meaning. A pressure-reducing valve station has an inlet and an outlet terminal; a sectionalizing switch has line-side and load-side terminals. Rules must pin pairings to the right terminal — Terminal 1 of a reducer to the larger-diameter edge, Terminal 2 to the smaller-diameter edge — so flow directionality and isolation boundaries resolve deterministically. Mapping terminals correctly is the same discipline that makes valve and isolator barrier logic trustworthy: if a gate valve’s terminals are misaligned with the mainline edge, an isolation trace bypasses the intended shutoff point.

Containment versus connectivity. Structural attachment must stay decoupled from topological flow. A fiber strand housed inside a conduit, or a service wire inside a duct bank, is a containment association, not a connection. Encoding it as connectivity fractures subnetwork tracing logic and produces false isolation boundaries. The network model expresses this through three association types — connectivity, structural attachment, and containment — and the rule set must use the right one for each physical relationship.

For cable, the model adds phase continuity. A three-phase underground cable entering a splice must map to terminal configurations that preserve A, B, C, and neutral continuity across the junction; a single-phase tap must not silently re-energize an unintended phase. Rule authoring therefore follows a deterministic matrix:

  1. Define asset groups and asset types with explicit terminal counts and directional properties.
  2. Construct edge-to-junction compatibility entries that enforce material, pressure, and phase constraints.
  3. Apply terminal pairing so each terminal connects only to compatible edge classes.
  4. Keep containment and structural attachment as separate association types — never as connectivity.
  5. Publish the schema and run a baseline topology validation before enabling subnetwork management.
Connectivity rule matrix with association-type side panel A grid pairing junction asset types against edge asset types, each cell flagged allowed (teal check) or forbidden (amber cross). Alongside, a panel distinguishes the three association types — connectivity, containment, and structural attachment — noting that only connectivity establishes a topological flow path. Edge × junction permission matrix Large main Small main Lateral 3-phase cable Gate valve PRV Splice Transformer allowed (explicit rule) forbidden (no rule = blocked) Association type decides whether the pairing carries flow Connectivity — topological flow path Containment — strand-in-conduit, no flow Structural — physical attach, no flow

Step-by-step implementation

The procedure below authors rules, validates them on staging, and promotes them to production. Each step is automatable; the inline Python uses arcpy so it can run headless in a pipeline.

  1. Author rules in the schema designer. Define each ConnectivityRule with fromAssetType, toAssetType, terminalConfiguration, and associationType. Keep the definitions in version control as JSON so every change is reviewable.
  2. Apply constraint flags. Set isBidirectional, terminalPairing, and phaseCompatibility on each rule so directional and phase semantics are explicit rather than inferred.
  3. Validate the JSON before touching the geodatabase. Reject unknown terminal configurations and association types up front — this is the cheapest place to catch a typo that would otherwise produce an orphaned terminal.
  4. Run topology validation on staging. Apply the rules to the staging geodatabase, validate the network topology, and surface severity-2 errors for orphaned terminals, unconnected edges, and invalid terminal assignments.
  5. Promote to production. Only after staging is clean, publish the validated rules to the enterprise network dataset and trigger a full topology rebuild inside a controlled maintenance window.

The validation gate from steps 3–4, expressed as a single reusable function:

import json
import arcpy


def validate_connectivity_rules(schema_path: str, un_path: str) -> bool:
    """Validate a JSON connectivity-rule schema, then validate UN topology.

    Rejects unknown terminal/association values before touching the
    geodatabase, then runs a topology validation and surfaces errors.
    Returns True on success; raises on the first failure.
    """
    with open(schema_path, "r", encoding="utf-8") as fh:
        rules = json.load(fh)

    valid_configs = {"single", "dual", "triple"}
    valid_assoc = {"connectivity", "containment", "structural_attachment"}

    for rule in rules.get("connectivityRules", []):
        rid = rule.get("id", "<unnamed>")
        tc = rule.get("terminalConfiguration")
        assoc = rule.get("associationType")
        if tc not in valid_configs:
            raise ValueError(
                f"Invalid terminalConfiguration '{tc}' in rule '{rid}'. "
                f"Expected one of: {sorted(valid_configs)}"
            )
        if assoc not in valid_assoc:
            raise ValueError(
                f"Invalid associationType '{assoc}' in rule '{rid}'. "
                f"Containment/attachment must not be encoded as connectivity."
            )

    arcpy.un.ValidateNetworkTopology(un_path)
    errors = arcpy.GetMessages(2)  # severity 2 = errors only
    if errors:
        raise RuntimeError(f"Topology validation errors detected:\n{errors}")

    return True

This pattern aligns with the Esri utility network rules documentation and uses Python’s json parsing for strict type checking. Running it in continuous integration on every schema change is the heart of automating connectivity rule validation in CI pipelines, which extends this gate with the exact pipeline hooks and assertions for enterprise deployment.

Diagnostic protocol

When a trace returns a suspicious result, work this checklist in order — the most common root cause is first.

  1. Confirm the topology is validated and current. A trace run against a dirty topology reflects stale rules. Validate first; many “rule bugs” are simply an un-rebuilt topology.
  2. Check terminal pairings at the suspect junction. Misaligned terminals are the leading cause of bypassed barriers. Verify that each terminal of the device connects only to its intended edge class and direction.
  3. Diff the published rule set against your version-controlled JSON. A rule that exists in the geodatabase but not in source control (or vice versa) signals a manual edit that escaped review.
  4. Look for orphaned terminals. An asset type with more terminals than any rule references will leave connection points no edge can occupy — a classic source of premature termination.
  5. Inspect association types for containment leakage. A strand-in-conduit or wire-in-duct relationship encoded as connectivity creates false bridges; confirm it is containment, not connectivity.
  6. Scan for over-permissive rules. A rule bonding incompatible asset groups fuses pressure zones or phases into a phantom subnetwork. Check that material, pressure, and phase constraints are present on every cross-class rule.
  7. Verify phase continuity for cable. At splices and taps, confirm A/B/C/neutral mappings preserve continuity and do not silently re-energize an unintended phase.
Ordered diagnostic ladder for a trace that returns the wrong result A top-to-bottom ladder of seven diagnostic steps, ordered by how often each is the root cause. Each step box names the check and is tagged on the right with the symptom it explains — stale topology, bypassed barriers, manual edits, premature termination, false bridges, phantom subnetworks, and silent phase re-energization. Trace returns the wrong result 1 Validate topology — is it current? 2 Check terminal pairings at the junction 3 Diff published rules vs version control 4 Look for orphaned terminals 5 Inspect association types for leakage 6 Scan for over-permissive rules 7 Verify phase continuity (cable) stale rules — trace reflects un-rebuilt topology bypassed barrier — trace skips the shutoff manual edit — change escaped review premature termination — trace stops short false bridge — containment read as connection phantom subnetwork — zones/phases fused silent re-energization — wrong phase live Ordered most-common-first: stop at the first check that explains the symptom.

Performance & scale considerations

Connectivity-rule work scales poorly when treated as an interactive, all-at-once operation. A few practices keep large deployments stable:

  • Isolate edits in branch versions. Author and validate rules in a dedicated version, then reconcile and post. This avoids lock contention with field editors and lets you abandon a bad rule set without touching default.
  • Stage topology rebuilds. A full rebuild on an enterprise dataset is expensive and locks the network. Validate incrementally on staging, and reserve full production rebuilds for controlled maintenance windows.
  • Batch matrix generation, not hand entry. Generate ConnectivityRule definitions from engineering asset catalogs (CSV or Excel) so a multi-jurisdiction network’s thousands of pairings are produced deterministically rather than clicked in. This is the same throughput discipline as batch topology processing with Python.
  • Snapshot before promotion. Export the rule set and a topology snapshot before each production publish so rollback is a restore, not a reconstruction.
  • Cap validation scope. When iterating, validate the affected extent rather than the whole network; only validate globally on the final pass before promotion.

Compliance notes

Connectivity-rule deployments feed safety-critical decisions, so their outputs must be auditable. Correctly mapped terminal pairs are what let an isolation trace satisfy the shutoff-traceability expectations of AWWA G400 asset-management practice for water systems, and what let electrical isolation align with NERC CIP critical-infrastructure controls. Required audit metadata includes: the rule-set version and source-control commit, the staging validation report (severity-2 results), the operator and timestamp of each production publish, and the topology rebuild timestamp. Schedule nightly topology reconciliation jobs that re-validate against engineering standards, flag drift introduced by offline field edits, and generate remediation tickets — the same exception-routing pattern used by automated error handling and flagging. Because every rule change is diffable and every publish is logged, the network maintains a defensible chain of custody from engineering specification to deployed constraint.

In this section