ArcGIS Utility Network — Part 1: Architecture, Data Model, Network Versions & Enterprise Engineering
Dal modello topologico al controller dataset, dai terminal alle associazioni non spaziali, dal branch versioning alle reti telecom: una lettura ingegneristica dell'Utility Network come piattaforma per sistemi infrastrutturali complessi.
1. Perché Utility Network è un cambio di paradigma
Una rete tecnica non coincide con un insieme di geometrie. Due conduttori possono intersecarsi in planimetria senza essere elettricamente connessi; due oggetti possono essere collegati senza condividere coordinate; un dispositivo può avere terminal multipli e consentire il passaggio della risorsa solo lungo determinati percorsi interni. Per rappresentare queste condizioni occorre distinguere almeno tre livelli: geometria, connettività e traversabilità.
ArcGIS Utility Network (UN) è un geodatabase controller dataset che coordina feature class, tabelle di oggetti non spaziali, associazioni, regole, attributi di rete e un indice topologico. La rete viene interrogata tramite strumenti di tracing e servizi che applicano una semantica più ricca del semplice test di intersezione geometrica.
Il grafo astratto può essere espresso come G = (V, E, A, T, R), dove V sono junction e device, E sono linee e edge object, A sono associazioni, T sono terminal e percorsi interni e R rappresenta regole e vincoli. Questa è una formalizzazione concettuale dell'autore, non lo schema fisico interno pubblicato da Esri.
La conseguenza architetturale è importante: un modello UN deve essere progettato partendo dalla semantica del sistema fisico e dalle operazioni richieste, non semplicemente convertendo shapefile e relationship class.
2. Structure Network e Domain Networks
2.1 Structure Network: il supporto fisico
Ogni Utility Network contiene una Structure Network condivisa. Rappresenta le strutture che sostengono, ospitano o proteggono le risorse: pali, cavidotti, pozzetti, armadi e strutture equivalenti. Non bisogna confondere l'appartenenza a una struttura con il passaggio effettivo di una risorsa: un cavo contenuto in un condotto e un apparato fissato a un palo sono relazioni diverse dalla connettività funzionale.
2.2 Traditional Domain Network
Le domain network tradizionali rappresentano la distribuzione di una risorsa: energia, acqua, gas o sistemi analoghi. Sono organizzate in tiers e subnetworks, con controller di tipo source o sink. La definizione di tier può essere partitioned o hierarchical, in funzione del modo in cui vengono organizzate le subnetworks.
2.3 Telecom Domain Network: perché non è soltanto una nuova feature class
La documentazione ArcGIS Pro 3.6 distingue le traditional domain networks dalle telecom domain networks. Queste ultime affrontano la cardinalità elevata tipica delle reti telecom e introducono un modello più adatto a raggruppamenti, codifiche cromatiche e circuit modeling. Il supporto richiede Utility Network Version 8 o successiva: l'errore documentato 003946 è esplicito su questo prerequisito.
La differenza concettuale è profonda. Nelle telecom occorre distinguere risorse fisiche (fibra, cavo, connettore), connettività logica, assegnazioni e circuiti. Una singola tratta fisica può ospitare molti elementi con identità e cicli di vita diversi. Una progettazione basata solo su feature lineari rischia di esplodere in cardinalità e produrre query e manutenzioni ingestibili.
3. Asset Group, Asset Type e regole di rete
Le classi della domain network definiscono famiglie strutturali di oggetti. La classificazione funzionale viene ulteriormente specializzata mediante Asset Group (implementato come subtype) e Asset Type (codificato tramite domini di valori). Per esempio, la classe Device può contenere gruppi di trasformatori, interruttori e regolatori; ciascun gruppo può avere tipologie specifiche.
Questa classificazione guida configurazioni dei terminal, attributi, regole e comportamenti di tracing. Non è soltanto una tassonomia descrittiva. La scelta della granularità ha costi: troppi asset type aumentano la complessità di governance; troppo pochi impediscono di rappresentare correttamente vincoli reali.
Una buona regola di progettazione è introdurre una distinzione di asset type quando cambia almeno una delle seguenti dimensioni: connettività ammessa, configurazione dei terminal, semantica di rete, attributi tecnici obbligatori o comportamento operativo.
4. Il modello topologico: geometry ≠ connectivity ≠ traversability
La geometria indica dove si trova un oggetto; la connettività indica con chi è connesso; la traversabilità indica se e in quale direzione un'analisi può attraversarlo. Un dispositivo con terminal multipli può essere geometricamente coincidente con una linea e tuttavia non consentire un percorso di attraversamento per lo stato operativo corrente.
La Network Topology è un indice gestito dal sistema che supporta tracing e network diagrams. Dopo modifiche rilevanti, le dirty areas indicano porzioni per cui l'indice non è allineato ai dati modificati. La validazione ricostruisce le informazioni interessate e può individuare errori di rete. Dirty area non significa automaticamente dato errato: significa che la topologia deve essere rivalidata.
Per un ambiente enterprise il ciclo operativo è:
La seconda puntata della serie approfondirà le categorie di errori, la validazione incrementale, le strategie di partizionamento geografico e l'interazione con il branch versioning.
5. Associations: connettività senza coincidenza spaziale
Le associazioni sono relazioni native della Utility Network, conservate in strutture interne mantenute dal sistema. Non sono equivalenti a una relationship class generica e non vanno manipolate direttamente mediante SQL.
| Association | Semantica | Esempio | Conseguenza |
|---|---|---|---|
| Connectivity | Connessione funzionale non necessariamente coincidente | Porta di apparato ↔ fibra | Può influenzare il grafo attraversabile |
| Containment | Un oggetto è contenuto in un altro | Giunzione ↔ armadio | Gerarchia di contenimento e rappresentazione |
| Structural attachment | Un asset è sostenuto da una struttura | Cavo ↔ palo | Relazione strutturale, non passaggio della risorsa |
Le associazioni sono soggette a regole. Prima di creare containment o structural attachment occorre definire i ruoli appropriati. In un progetto reale la matrice delle associazioni ammesse è un deliverable architetturale da versionare e sottoporre a review, non una configurazione improvvisata durante il data loading.
6. Terminal e percorsi interni dei device
I terminal consentono di rappresentare device nei quali il flusso attraversa punti di ingresso e uscita differenti. Una terminal configuration definisce terminal e percorsi interni consentiti. Per esempio, un apparato a tre terminal non deve essere modellato automaticamente come una junction in cui ogni ingresso è connesso a ogni uscita.
La traversabilità dipende dalla combinazione di connettività, configurazione dei terminal, stato operativo, network attributes e parametri di trace. La correttezza dei risultati di tracing richiede che queste componenti siano coerenti: non basta disegnare correttamente la geometria.
7. Tiers, subnetworks e controllers
Una tier definisce una classe di subnetworks che condividono proprietà e vincoli. Una subnetwork è una porzione topologicamente definita della rete, associata a uno o più controller. I controller identificano punti di origine o destinazione coerenti con il modello source-based o sink-based.
Nella distribuzione elettrica, per esempio, la separazione fra livelli di tensione può corrispondere a tier distinte. Nelle reti idriche si possono modellare zone e livelli gerarchici. Non esiste una mappatura universale fra tier e categoria cartografica: la progettazione deve partire dalle operazioni di tracing, dalla gestione delle subnetworks e dalle regole del dominio.
La gestione delle subnetworks introduce processi specifici di update e validazione. È un errore considerare il nome della subnetwork come un semplice campo descrittivo aggiornabile senza conseguenze.
8. Network attributes: pesi, condizioni e filtri
I network attributes forniscono informazioni utilizzabili dal tracing, come stati, valori e proprietà aggregate o confrontabili. Possono derivare da attributi delle feature attraverso assegnazioni configurate. Il tracing può utilizzare condizioni e barriere basate su questi valori, consentendo analisi che riflettono lo stato operativo della rete.
È utile distinguere attributi di business (inventario, proprietà, codici gestionali) da attributi che partecipano direttamente al comportamento della rete. Non ogni colonna della feature class deve diventare un network attribute: il costo della configurazione e della manutenzione deve essere giustificato dal caso d'uso.
9. Enterprise architecture: servizi, geodatabase e responsabilità
Le capability non sono intercambiabili. Il Feature Service espone query e modifiche alle feature; il Utility Network Service fornisce operazioni come trace, validazione e gestione delle subnetworks; il Network Diagram Service gestisce diagrammi; il Version Management Service supporta i workflow di branch versioning quando abilitato.
La pubblicazione richiede dati registrati, prerequisiti di ownership e configurazione coerente del servizio. È consigliabile assegnare ID stabili ai layer prima della pubblicazione: un overwrite che modifica gli ID può rompere i client che li referenziano direttamente.
Licenze: i requisiti sono cambiati nel tempo. La documentazione Enterprise 11.4 indica l'estensione ArcGIS Advanced Editing per creazione, pubblicazione ed editing, mentre la consultazione e il tracing hanno requisiti differenti. Verificare sempre la release effettivamente installata e il modello di licensing applicabile.
10. Branch versioning: isolamento delle modifiche e consistenza
Nel deployment enterprise basato su servizi, il feature dataset della Utility Network deve essere registrato come branch versioned prima della pubblicazione. L'editing può avvenire sulla default version oppure su named versions quando la capability Version Management è disponibile e configurata.
Il branch versioning non è un sostituto della topologia: risolve un problema diverso, quello dell'isolamento e dell'integrazione delle modifiche concorrenti. Reconcile/post, conflitti e validazione topologica devono essere trattati come fasi distinte della pipeline di qualità. Un edit che non produce un conflitto di versione può comunque violare una regola di rete.
La progettazione delle versioni dovrebbe considerare confini dei cantieri, durata delle sessioni, dimensione dei change set e responsabilità di approvazione. Le versioni a vita indefinita aumentano il rischio operativo di divergenza.
11. Versioning: tre numeri da non confondere
ArcGIS Pro version indica la release del client e dell'SDK. ArcGIS Enterprise version indica la release della piattaforma server. Utility Network Version indica la versione dello schema del dataset. Un upgrade di ArcGIS Pro non implica automaticamente un upgrade dello schema Utility Network.
| Utility Network Version | ArcGIS Pro minimo | ArcGIS Enterprise minimo | Nota |
|---|---|---|---|
| 4 | 2.6 | 10.8.1 | Compatibilità storica |
| 5 | 2.7 | 10.9 | Schema successivo |
| 6 | 3.0 | 11.0 | Aggiornamenti interni per Pro 3.0 e diagrammi |
| 7 | 3.3 | 11.3 | Supporto 64-bit Object IDs e nuove capacità |
| 8 | Verificare la matrice ufficiale della release corrente prima del deployment | Prerequisito per Telecom Domain Network | |
La tabella 4–7 è tratta dalla matrice ufficiale ArcGIS Pro 3.5; la presenza di UN 8 è documentata nelle guide ArcGIS Pro 3.6. La combinazione esatta di client e server per creare, aggiornare e consumare UN 8 va verificata sulla matrice aggiornata della versione effettivamente distribuita. Non va inferita dalla sola presenza della funzione nell'interfaccia.
L'upgrade del dataset è un'operazione amministrativa distinta dall'aggiornamento software. Può richiedere prerequisiti di geodatabase, esclusività di accesso, gestione della topologia e operazioni successive all'upgrade. Occorrono backup, ambiente di prova, inventario dei client e test di regressione.
12. SDK C#: introspezione del modello, non accesso diretto alle tabelle di sistema
L'ArcGIS Pro SDK espone ArcGIS.Core.Data.UtilityNetwork. L'API è orientata alle operazioni sui dati e all'ispezione del modello; la modifica dello schema (domain networks, regole e configurazioni) deve essere eseguita mediante geoprocessing. Molte operazioni SDK devono essere chiamate sul Main CIM Thread attraverso QueuedTask.Run. Gli oggetti geodatabase vanno rilasciati con Dispose/using.
Il seguente frammento è uno scheletro di ispezione per un add-in ArcGIS Pro con riferimenti SDK correttamente configurati; il nome del dataset deve essere recuperato dalla connessione utilizzata, perché può differire fra workspace enterprise e feature service.
using ArcGIS.Core.Data;
using ArcGIS.Core.Data.UtilityNetwork;
using ArcGIS.Desktop.Framework.Threading.Tasks;
// 'geodatabase' è un oggetto Geodatabase già aperto.
// Il nome va risolto nel workspace effettivamente utilizzato.
await QueuedTask.Run(() =>
{
using UtilityNetwork un =
geodatabase.OpenDataset<UtilityNetwork>(
"NomeUtilityNetwork");
UtilityNetworkDefinition definition = un.GetDefinition();
string schemaVersion = definition.GetSchemaVersion();
foreach (DomainNetwork domain in definition.GetDomainNetworks())
{
System.Diagnostics.Debug.WriteLine(
$"{domain.Name} - structure: {domain.IsStructureNetwork}");
}
System.Diagnostics.Debug.WriteLine(
$"Utility Network schema: {schemaVersion}");
});Nota di verifica: le firme e le proprietà devono essere ricontrollate contro l'API Reference della specifica versione dell'SDK usata per compilare; questo snippet illustra il percorso di accesso a UtilityNetworkDefinition e non costituisce un progetto add-in completo. In produzione conviene trattare la configurazione letta come uno snapshot di metadati e non come una fonte modificabile direttamente.
13. Laboratorio ArcPy: inventario della rete senza alterare il dataset
Un primo laboratorio sicuro consiste nell'estrarre le proprietà di una Utility Network e produrre un inventario confrontabile fra ambienti. Il codice seguente usa arcpy.Describe e arcpy.ListDatasets come base esplorativa; i campi disponibili sull'oggetto Describe dipendono dalla release e dal tipo di workspace.
import arcpy
import json
from datetime import datetime, timezone
workspace = r"C:\GIS\Connections\production.sde"
arcpy.env.workspace = workspace
inventory = {
"collected_utc": datetime.now(timezone.utc).isoformat(),
"workspace": "enterprise-geodatabase",
"datasets": []
}
for dataset_name in arcpy.ListDatasets() or []:
desc = arcpy.Describe(dataset_name)
inventory["datasets"].append({
"name": dataset_name,
"dataType": getattr(desc, "dataType", None),
"datasetType": getattr(desc, "datasetType", None)
})
with open("un_inventory.json", "w", encoding="utf-8") as stream:
json.dump(inventory, stream, indent=2, ensure_ascii=False)
print("Inventario salvato:", len(inventory["datasets"]))Questo script è volutamente read-only e non promette di identificare automaticamente ogni proprietà interna della Utility Network. La fase successiva consiste nell'usare gli strumenti e le API specifiche della release per esportare regole, domain networks, tier e configurazioni e confrontare gli ambienti con un diff strutturale.
14. Performance engineering: cosa misurare prima di scalare
Una rete con milioni di feature non si ottimizza contando soltanto le righe del database. Occorre misurare cardinalità delle associazioni, numero di oggetti non spaziali, estensione delle dirty areas, dimensione dei trace, costo della validazione, profondità delle gerarchie di containment, carico dei servizi e frequenza delle operazioni concorrenti.
| Indicatore | Perché conta | Metodo di misura |
|---|---|---|
| Trace P50/P95/P99 | Rileva code e outlier | Telemetry lato client + log ArcGIS Server |
| Validazione per area | Misura costo incrementale della topologia | Durata e dirty areas prima/dopo |
| Associazioni per asset | Individua hotspot di cardinalità | Inventario semantico e query supportate |
| Reconcile/post | Quantifica costo della collaborazione | Durata, conflitti e dimensione change set |
| Timeout e saturazione servizi | Individua colli di bottiglia operativi | Metriche server e richieste concorrenti |
Le API REST sincrone possono essere esposte a timeout per operazioni lunghe. Alcuni endpoint offrono modalità asincrone che delegano il lavoro al geoprocessing server: non è automaticamente più veloce, ma è più adatto ai job prolungati. Un benchmark corretto separa latenza di rete, tempo di esecuzione server, serializzazione e rendering.
15. Threat model e governance
La Utility Network è un sistema informativo operativo: un risultato di trace errato può influenzare decisioni su interruzioni, isolamento o manutenzione. La sicurezza deve comprendere autenticazione, autorizzazione alle operazioni di editing, protezione delle credenziali del geodatabase, audit, gestione dei privilegi del portal account e controlli sulle modifiche di schema.
Le regole di rete proteggono la coerenza del modello ma non sostituiscono autorizzazioni, revisione delle modifiche e controlli organizzativi. Un utente autorizzato a modificare una feature può comunque introdurre uno stato fisicamente plausibile ma operativamente scorretto. Per i processi critici servono validazione, revisione e tracciabilità della provenienza delle modifiche.
16. Decision record: come scegliere il modello corretto
Prima di implementare una Utility Network, un Architecture Decision Record dovrebbe rispondere a queste domande: quali trace devono essere supportati? Quali asset richiedono terminal? Quali relazioni sono connectivity, containment o attachment? Quali oggetti sono non spaziali? Quali livelli operativi diventano tiers? Qual è la versione minima compatibile con client e server? Come verranno gestite le modifiche concorrenti? Come verranno misurate validazione e performance?
La qualità di queste decisioni pesa più della velocità di importazione iniziale. Una rete modellata in modo improprio può richiedere costose trasformazioni successive di regole, associazioni e dati.
17. Roadmap tecnica della serie
- Part 1 — Architecture, Data Model, Network Versions & Enterprise Engineering (questa puntata).
- Part 2 — Network Topology: Dirty Areas, Validation, Error Engine & Performance.
- Part 3 — Network Rules, Associations & Terminal Engineering.
- Part 4 — Subnetworks, Controllers, Update Pipelines & Propagation.
- Part 5 — Trace Engine: Upstream, Downstream, Isolation & Named Configurations.
- Part 6 — Branch Versioning: Reconcile/Post, Conflict Resolution & Multiuser Editing.
- Part 7 — ArcGIS Pro SDK C#, ArcPy & REST: Advanced Developer Laboratory.
- Part 8 — Enterprise Architecture: Migration, Operations, Tuning & Automation.
18. Riferimenti ufficiali e approfondimenti
- Esri — Domain networks (ArcGIS Pro 3.6)
- Esri — ProConcepts Utility Network, SDK 3.6
- Esri — Utility Network compatibility (Pro 3.5)
- Esri — Error 003946: Telecom Domain Network requires UN 8+
- Esri — Associations
- Esri — Network topology
- Esri — Publish and consume Utility Network services
- Esri — Utility Network services and licensing
- Esri — Utility Network upgrade history
Conclusione. Utility Network è un modello semantico e topologico governato, non una semplice rappresentazione GIS. La sua progettazione richiede la stessa disciplina utilizzata per sistemi transazionali e piattaforme distribuite: contratti di schema, compatibilità, controllo della consistenza, osservabilità, sicurezza e test riproducibili. Nella prossima puntata analizzeremo il motore topologico e la validazione delle dirty areas fino ai failure mode operativi.
Nessun commento:
Posta un commento