ArcGIS Utility Network - Network Rules, Terminal Configurations & Associations — Progettare la semantica del grafo

ArcGIS Utility Network — Parte 3

Network Rules, Terminal Configurations & Associations: progettare la semantica del grafo

NicoGIS Tech Weekly · 6 novembre 2026 · Deep Dive / GIS Engineering

Tesi architetturale. La Utility Network non è una rete di linee che si toccano: è un grafo vincolato, in cui regole, terminali e associazioni determinano quali connessioni siano ammissibili e quali percorsi siano attraversabili. Una geometria corretta non implica una topologia corretta; una topologia valida non implica necessariamente un modello elettrico o idraulico fedele alla realtà.

Serie. Parte 1: architettura e modello dati. Parte 2: network topology, dirty areas e validation engine. Questa terza lezione approfondisce il contratto semantico che il motore di validazione applica al grafo. Gli esempi usano una rete elettrica sintetica; i principi sono trasferibili alle reti gas, acqua e telecomunicazioni, con regole e comportamenti specifici per dominio.

1. Tre livelli di verità: geometria, modello e stato operativo

Un cavo può terminare geometricamente su un dispositivo senza che il modello consenta quella connessione. Una struttura può contenere un apparato senza essere attraversabile da un trace. Un interruttore può avere due terminali correttamente collegati ma un percorso interno aperto.

Livello	Rappresenta	Domanda	Errore tipico
Geometria	Coordinate e coincidenze	Dove sono gli asset?	Endpoint disallineati
Schema e regole	Asset group/type, associazioni, terminali	Quali relazioni sono lecite?	Connessione priva di regola
Stato della rete	Terminal paths, attributi, barriere e condizioni	Quale percorso è disponibile ora?	Trace attraversa un dispositivo che dovrebbe bloccare

Distinzione cruciale: le network rules autorizzano tipi di relazione; non sono da sole una simulazione fisica. La disponibilità del percorso dipende anche dalla configurazione dei terminali, dal percorso attivo e dalle impostazioni del trace.

2. Network rules: vincoli dichiarativi sul grafo

Le regole sono definite rispetto a asset group e asset type, non per ogni singola feature. Il motore le valuta durante l'abilitazione/validazione della topologia e, per le associazioni, già durante la creazione o l'importazione. Le regole di rete operano insieme alle feature restrictions imposte dalle classi: una regola non può aggirare una restrizione strutturale.

Le cinque famiglie sono:

1. Junction–edge connectivity: un dispositivo o una junction si collega a un edge.
2. Junction–junction connectivity: due junction sono connesse, anche mediante associazione quando previsto.
3. Edge–junction–edge connectivity: un elemento junction connette due edge.
4. Containment: un asset contiene altri asset.
5. Structural attachment: un asset è sostenuto o fissato a una struttura.

Relazione	Esempio	Conduce una commodity?	Dipende da terminali?
Junction–edge	Cavo → interruttore	Può contribuire alla connettività	Sì, se l'asset dispone di terminali
Junction–junction	Due oggetti di rete collegati	Può contribuire	Può coinvolgere terminali
Edge–junction–edge	Due conduttori tramite junction	Può contribuire	Dipende dal modello
Containment	Quadro → interruttore	Non per il solo contenimento	No
Structural attachment	Palo → trasformatore	Non per il solo attacco	No

Eccezione da conoscere. La documentazione Esri descrive il caso di due edge con stesso asset group e asset type che condividono un endpoint: può essere creata una system junction senza una junction definita dall'utente. Non generalizzare questo comportamento a qualunque coppia di edge.

3. Asset group e asset type non sono etichette decorative

Consideriamo una rete elettrica sintetica:

Feature class	Asset group	Asset type	Funzione
ElectricLine	MediumVoltage	UndergroundCable	Tratta MT
ElectricDevice	Switching	CircuitBreaker	Interruttore
ElectricDevice	Transformation	MVLVTransformer	Trasformatore
StructureJunction	Support	Pole	Sostegno
StructureBoundary	Enclosure	Cabinet	Armadio

Se un cavo MT è autorizzato a connettersi al terminale Source di un interruttore, questo non autorizza automaticamente un cavo BT, né qualunque asset type della stessa classe. Le regole sono parte del modello di dominio e vanno versionate come artefatti architetturali.

Una matrice di regole leggibile dagli specialisti del dominio è spesso più utile di una lunga sequenza di configurazioni manuali.

4. Terminal configurations: il dispositivo non è un punto indivisibile

Un device a singolo terminale può essere modellato come una junction semplice. Quando invece il dispositivo ha ingressi, uscite o percorsi interni distinti, serve una terminal configuration.

Esri supporta configurazioni con da 2 a 8 terminali, con direzionalità directional oppure bidirectional. La configurazione è assegnata all'asset type di un device o di un junction object, secondo le restrizioni della versione. Un asset type può avere una sola terminal configuration assegnata.

Esempio concettuale: interruttore a due terminali

Cavo MT A ─── [ SOURCE | Circuit Breaker | LOAD ] ─── Cavo MT B
                     └── internal path ──┘

La relazione esterna identifica il terminale al quale è connesso ciascun cavo. Il terminal path descrive invece il percorso consentito all'interno del dispositivo. In un modello con percorsi configurabili, il percorso attivo può variare per singolo asset; i dettagli del comportamento dipendono dalla configurazione del dominio e dal trace.

Direzionalità non significa stato ON/OFF

• Directional: distingue terminali di ingresso e uscita in termini di direzione della commodity.
• Bidirectional: non impone quella distinzione direzionale.
• Valid paths: definiscono i percorsi interni ammessi dalla configurazione.
• Active terminal path: rappresenta il percorso selezionato sull'istanza, quando applicabile.

Errore frequente: modellare uno switch semplicemente con due edge geometricamente coincidenti, ignorando i terminali. Il trace può allora risultare semanticamente diverso da quello atteso.

5. Terminal paths: una piccola macchina a stati

Il modello seguente è didattico, non una descrizione del formato interno Esri:

State CLOSED:  SOURCE ───────── LOAD
State OPEN:    SOURCE     X     LOAD

Nella Utility Network reale, i percorsi validi e i terminal paths devono essere modellati con gli strumenti supportati e con le corrette regole di tracing. Non assumere che la modifica di un generico campo status modifichi automaticamente la connettività: va verificata la configurazione effettiva, inclusi attributi di rete e condizioni del trace.

Per dispositivi complessi (es. trasformatori multi-avvolgimento), la configurazione deve rappresentare solo i percorsi fisicamente consentiti. Un errore nella matrice dei percorsi può propagarsi a ogni analisi downstream.

6. Connectivity associations: connessioni senza coincidenza geometrica

Una connectivity association descrive un collegamento fra elementi che non richiedono la stessa posizione geometrica, inclusi oggetti non spaziali. È utile quando una connessione è reale ma la cartografia la rappresenta in modo schematico o aggregato.

[Device A] ── connectivity association ── [Junction Object B]
  POINT                                     NONSPATIAL

Non bisogna confondere la connectivity association con un link generico di un database relazionale: è una relazione disciplinata dalle regole della Utility Network e contribuisce alla connettività del grafo secondo il modello.

7. Containment: la gerarchia fisica non è connettività

Un armadio può contenere più dispositivi e junction objects. Il containment consente di rappresentare questa organizzazione senza creare geometrie separate per ogni componente.

Cabinet (container)
  ├── Breaker A
  ├── Fuse B
  └── Junction Object C

La relazione di containment non equivale a una connessione elettrica fra A, B e C. Per il passaggio della commodity occorrono connessioni appropriate. Il container deve avere il ruolo di associazione previsto prima che sia definita una containment rule.

Implicazione GIS: la visualizzazione del contenuto e la navigazione del grafo sono due problemi differenti. Una feature può essere nascosta sulla mappa pur continuando a partecipare alle analisi.

8. Structural attachment: supporto, non flusso

Il rapporto fra un palo e un apparato montato sul palo è un esempio di structural attachment. Il ruolo strutturale è necessario e la regola specifica quali asset possono essere attaccati alla struttura.

Pole ── structural attachment ── Transformer

L'associazione permette analisi di inventario e dipendenza strutturale, ma non crea di per sé un percorso elettrico. Confondere le due semantiche produce risultati errati in tracciamento e analisi d'impatto.

9. Quando si applicano le regole: editing e validazione

Operazione	Comportamento da aspettarsi
Creazione di una association	La regola è verificata e l'associazione non valida viene rifiutata
Import Associations	Le associazioni prive di regola supportata fanno fallire l'operazione secondo la documentazione
Spostamento di feature coincidenti	Possono generarsi dirty areas; occorre validare
Abilitazione/validazione della topologia	Sono valutate le relazioni e possono emergere errori
Rimozione di una regola già usata	Le relazioni esistenti possono diventare invalide alla validazione

Questa differenza temporale spiega perché una modifica allo schema può introdurre errori senza che l'utente abbia modificato una singola geometria.

10. Governance delle regole in enterprise geodatabase

La modifica di regole e configurazioni non è un'operazione di editing ordinario. In generale, richiede la topologia disabilitata, la connessione del proprietario della Utility Network e, nell'ambiente enterprise, il contesto di proprietà Portal appropriato. La documentazione Esri descrive vincoli ulteriori per le modifiche alla terminal configuration, specialmente dopo la prima abilitazione della topologia.

Sequenza operativa consigliata (da adattare alla versione):

1. Esportare e revisionare configurazioni e regole correnti.
2. Verificare compatibilità ArcGIS Pro / Enterprise / Utility Network version.
3. Pianificare fermo del servizio e finestra di manutenzione.
4. Gestire versioni branch e reconcile secondo le istruzioni Esri.
5. Disabilitare la network topology con l'identità corretta.
6. Applicare la modifica dichiarativa e verificare le proprietà risultanti.
7. Riabilitare la topologia, validare e misurare gli errori.
8. Eseguire test di trace e regressione, poi riaprire i servizi.

Attenzione: non usare la checklist come procedura universale da eseguire alla cieca in produzione. Le operazioni consentite e i prerequisiti cambiano con versione e stato della topologia. Alcune modifiche di terminal configuration sono limitate prima della prima abilitazione: non è sempre possibile tornare al modello precedente disabilitando la topologia.

11. Laboratorio ArcPy A — inventario della Utility Network

Prima di modificare una rete, produrre un inventario ripetibile. Questo esempio è di sola lettura e mostra l'ispezione della descrizione; le proprietà disponibili dipendono dalla versione ArcGIS Pro.

import arcpy
import json

utility_network = r"C:\GIS\Connections\un_owner.sde\ElectricDataset\ElectricUN"

desc = arcpy.Describe(utility_network)
print("Data type:", desc.dataType)

# Esplorazione difensiva: non tutte le versioni espongono
# le stesse proprieta' in Describe.
for name in ("domainNetworks", "networkAttributes", "terminalConfigurations"):
    value = getattr(desc, name, None)
    print(name, "available:", value is not None)

# Per una baseline completa, esportare le regole tramite
# lo strumento ufficiale Export Rules nella versione in uso.

L'inventario di Describe non sostituisce l'export delle network rules. Conservare inoltre hash, versione ArcGIS Pro, versione Enterprise, data e ambiente di provenienza dell'export.

12. Laboratorio ArcPy B — esportare le regole senza modificarle

Esempio orientativo di utilizzo dello strumento di geoprocessing; verificare la firma della versione installata con la guida locale o arcpy.Usage.

import arcpy

un = r"C:\GIS\Connections\un_owner.sde\ElectricDataset\ElectricUN"
output_csv = r"C:\GIS\audit\electric_un_rules.csv"

print(arcpy.Usage("ExportRules_un"))
# Verificare nome tool e parametri per la versione installata
# prima di eseguire una chiamata di export nell'ambiente reale.
# arcpy.un.ExportRules(un, output_csv)

Il codice evita deliberatamente di inventare asset group ID e terminal ID. Tali identificativi devono provenire dalla configurazione effettiva, non da esempi editoriali.

13. Laboratorio C#/.NET — testare una matrice di connettività prima del deployment

Il primo livello di validazione può essere indipendente da ArcGIS: un modello di regole dichiarative e una batteria di test automatici. Questo codice non chiama l'API Utility Network: è un preflight del contratto di dominio, utile per individuare incoerenze prima della configurazione Esri.

using System;
using System.Collections.Generic;
using System.Linq;

public readonly record struct Asset(string Group, string Type);
public readonly record struct AllowedConnection(
    Asset From, string FromTerminal,
    Asset To, string ToTerminal);

public sealed class RuleMatrix
{
    private readonly HashSet<AllowedConnection> _rules = new();

    public void Allow(AllowedConnection rule) => _rules.Add(rule);

    public bool IsAllowed(AllowedConnection candidate) =>
        _rules.Contains(candidate);
}

var cable = new Asset("MediumVoltage", "UndergroundCable");
var breaker = new Asset("Switching", "CircuitBreaker");
var lowVoltage = new Asset("LowVoltage", "UndergroundCable");

var matrix = new RuleMatrix();
matrix.Allow(new AllowedConnection(cable, "End", breaker, "Source"));

Console.WriteLine(matrix.IsAllowed(
    new(cable, "End", breaker, "Source"))); // True
Console.WriteLine(matrix.IsAllowed(
    new(lowVoltage, "End", breaker, "Source"))); // False

Nel modello reale, una regola Junction–Edge non va ridotta meccanicamente a quattro stringhe: orientamento, classe, ruolo, asset group/type, terminal ID e tipo di regola devono essere ricondotti allo schema Esri. Questo esempio serve a formalizzare i requisiti prima della loro traduzione nella configurazione ufficiale.

14. Test di regressione: dalla regola al trace

Un test completo non si ferma a verificare che una regola esista. Deve dimostrare che il comportamento del grafo corrisponde all'intenzione progettuale.

Test	Preparazione	Atteso
Connessione consentita	Cavo MT verso terminale previsto	Nessun errore di regola
Connessione vietata	Cavo BT su terminale solo MT	Rifiuto o errore in validazione, secondo operazione
Containment	Breaker dentro cabinet	Associazione lecita, nessuna connettività implicita
Attachment	Transformer su pole	Relazione strutturale, nessun percorso commodity implicito
Terminal path	Dispositivo con percorso selezionato	Trace coerente con percorso e condizioni
Rimozione regola	Replica di test con regola mancante	Errore rilevabile, mai modificare produzione per il test

Per ciascun test conservare GlobalID, asset type, terminal ID, version, trace configuration, error count e risultato. Il solo screenshot della mappa non è una prova sufficiente.

15. Modello di errore: cinque cause da distinguere

1. Coincidenza geometrica non ammessa: la geometria suggerisce una connessione ma manca una regola valida.
2. Terminale errato: il device è corretto ma la connessione punta al terminale sbagliato.
3. Associazione non consentita: asset type o association role incompatibili.
4. Percorso interno errato: i terminal paths non rappresentano il comportamento richiesto.
5. Topologia non aggiornata: la modifica è lecita, ma le dirty areas non sono ancora state validate.

Diagnostica: prima identificare se il problema è di schema, dati, stato o validazione. Solo dopo intervenire su regole o geometrie. Una regola aggiunta per eliminare rapidamente un errore può autorizzare centinaia di connessioni indesiderate.

16. Versioning e deployment: le regole sono uno schema, non dati transazionali

Nel branch versioning, le modifiche degli operatori avvengono in versioni di lavoro, ma le modifiche allo schema della Utility Network richiedono procedure amministrative distinte. Le versioni esistenti possono richiedere reconcile per riflettere aggiornamenti della configurazione, come documentato da Esri.

Per la governance, usare un repository con:

utility-network-config/
  README.md
  environments/
    test.json
    staging.json
    production.json
  rules/
    connectivity-matrix.csv
    containment-matrix.csv
    attachment-matrix.csv
  terminals/
    device-terminal-contracts.yaml
  tests/
    trace-cases.json
  exports/
    README.md

Questa struttura è una proposta di organizzazione, non un formato di import nativo Esri. L'obiettivo è separare specifiche revisionabili, esportazioni effettive e test di accettazione.

17. Performance: regole permissive vs semantica rigorosa

Il costo principale di una modellazione eccessivamente permissiva non è necessariamente il tempo di validazione, ma il rischio di risultati analitici sbagliati. Un trace veloce che attraversa connessioni non plausibili è peggiore di un trace più lento ma verificabile.

Per misurare le prestazioni in modo riproducibile, registrare numero di asset, numero di associazioni per tipo, numero di dirty areas, tempi di validazione, numero di errori, durata dei trace e percentili P50/P95. Confrontare scenari equivalenti e non attribuire miglioramenti a singole regole senza esperimenti controllati.

18. Checklist per una design review

• Gli asset group/type rappresentano differenze operative reali?
• Le connectivity rules sono sufficientemente specifiche?
• Ogni device multi-terminale ha una terminal configuration coerente?
• I terminal paths sono documentati e verificati da trace?
• Containment e structural attachment sono distinti dalla connettività?
• Esistono casi negativi automatizzati per connessioni vietate?
• La configurazione è esportabile e confrontabile fra ambienti?
• Le modifiche allo schema hanno una procedura di rollback realistica?
• È definita una soglia accettabile di errori topologici prima del rilascio?

19. Conclusione: la Utility Network come contratto verificabile

Il vero valore della Utility Network emerge quando le relazioni fra asset diventano esplicite, limitate e verificabili. Le network rules impediscono combinazioni impossibili; le terminal configurations descrivono il comportamento interno dei dispositivi; le associations permettono di rappresentare relazioni fisiche e logiche che la sola geometria non può esprimere.

Il passaggio successivo è collegare queste fondamenta al comportamento operativo: tiers, subnetworks, subnetwork controllers e tracing. Sarà il tema della Parte 4.

Fonti ufficiali e documentazione

• Esri — Network rules
• Esri — Associations
• Esri — Connectivity and associations
• Esri — Create a terminal configuration
• Esri — Set a terminal configuration
• Esri — Utility network management tasks

Nota editoriale: i nomi degli asset, le matrici di test e i diagrammi sono sintetici. La disponibilità dei tool e le condizioni di configurazione dipendono dalle versioni di ArcGIS Pro, ArcGIS Enterprise e Utility Network.