14 min read3,180 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.

Generating the Rule Matrix From an Engineering Catalogue

A rule set authored by hand in a schema designer has two properties that eventually cause trouble: nobody can review it as a whole, and it drifts from the engineering standards it is supposed to encode. Generating it from the catalogue fixes both.

The catalogue already exists in every utility, usually as a spreadsheet: approved materials and their pressure or voltage classes, the fittings that may join each pair, the device classes and their terminal counts, the standard details that show what may connect to what. That document is the source of truth engineering already maintains, and a rule matrix generated from it is correct by construction rather than by transcription.

The generator is not complicated — it expands each catalogue row into the rules it implies, applies the terminal configuration for the device class, and emits a definition file. What makes it valuable is what becomes possible once the rules are generated rather than typed. The rule set can be diffed between releases, so a schema change is reviewable. It can be regenerated for a second jurisdiction with a different standard by swapping the catalogue rather than re-authoring hundreds of rules. It can be validated before it touches a geodatabase, because the definition file is data. And when an engineer asks why a particular connection is forbidden, the answer is a row in the catalogue rather than an archaeological expedition through the schema.

Two cautions. Generation makes it cheap to create rules, and a matrix that permits everything is no constraint at all — the catalogue must be pruned to what is genuinely approved, not expanded to what is physically possible. And the generated set needs the same review gate as hand-authored rules: a regenerated matrix that silently adds a permission because someone widened a catalogue cell is exactly the over-permissive rule this section warns about, arriving through a new door.

Phase, Pressure and the Rules That Encode Them

Connectivity is necessary but not sufficient. Two features may be legally connectable and still must not be connected in a particular instance, because the commodity states on each side are incompatible. Encoding that is what separates a rule set that models a network from one that models a drawing.

In electric distribution the property is phase. A connectivity rule that permits a conductor to join a device says nothing about whether the A, B, C and neutral mappings line up across the join. Where they do not, a trace will happily propagate through a splice that in reality re-energises the wrong phase, and the model will report a circuit that cannot exist. Phase continuity therefore belongs in the rule layer as a constraint on the association, checked at splices, taps and transformer terminals rather than assumed from geometry.

In water and gas the equivalent property is pressure class. A high-pressure main and a distribution main are both pipes, and a rule set that only asks “may a pipe connect to a pipe?” will permit a direct join between them. The physical network prevents this with a regulator; the model must prevent it with a rule that requires a pressure-reducing device between classes, or the isolation and pressure-zone analyses built on the graph will be quietly wrong in the most consequential place.

Both cases share a shape: an attribute on each side, a compatibility relation between them, and a device class that legitimately bridges the incompatibility. Model all three explicitly. A rule set that encodes only the first — the attributes — pushes the compatibility judgement onto whoever reads the map next.

Retiring a Rule Without Breaking History

Rules change: a material is withdrawn, a device class is superseded, a standard detail is replaced. Deleting the rule that permitted the old combination is the obvious move and the wrong one, because the features it permitted are still in the ground and still need to validate.

Retire instead of delete. Keep the rule, mark it superseded in the version-controlled definition, and add the replacement alongside it. New connections are authored against the current rule; existing ones continue to validate against the retired one. Where the intent is genuinely to force remediation, keep the rule and add a finding rather than removing it, so the affected features appear in a queue instead of failing validation en masse the morning after a schema publish.

In this section