-----------------------------------

Acquista i software ArcGIS tramite Studio A&T srl, rivenditore autorizzato dei prodotti Esri.

I migliori software GIS, il miglior supporto tecnico!

I migliori software GIS, il miglior supporto tecnico!
Azienda operante nel settore GIS dal 2001, specializzata nell’utilizzo della tecnologia ArcGIS e aderente ai programmi Esri Italia Business Network ed Esri Partner Network

-----------------------------------



Visualizzazione post con etichetta Network Topology. Mostra tutti i post
Visualizzazione post con etichetta Network Topology. Mostra tutti i post

mercoledì 4 novembre 2026

ArcGIS Utility Network — Network Topology, Dirty Areas & Validation Engine

NicoGIS Tech Weekly · Utility Network Engineering Series · Capitolo 2

ArcGIS Utility Network — Network Topology, Dirty Areas & Validation Engine

Dall'editing delle feature all'indice topologico: come ArcGIS Utility Network mantiene la coerenza del grafo, perché nascono le dirty areas, come funziona la validazione e quali invarianti deve garantire un'architettura enterprise.

4 novembre 2026 · Livello: Senior GIS Engineer / Software Architect · ArcGIS Pro, ArcGIS Enterprise, ArcPy, REST, C#

Continuità con il Capitolo 1. Dopo aver introdotto domain network, tiers, asset groups/types, terminal configurations, associations e branch versioning, passiamo al cuore operativo: la network topology. Non è la geometria delle feature e non è una semplice tabella di adiacenza: è la rappresentazione di connettività utilizzata dal motore per le analisi di rete.

1. Due rappresentazioni dello stesso mondo: feature space e topology space

Una Utility Network mantiene una distinzione essenziale fra feature space (feature, attributi, geometrie, associazioni) e network topology space (indice topologico usato per la connettività e il tracing). Le modifiche alle feature non implicano che ogni parte dell'indice venga immediatamente ricostruita. Questo disaccoppiamento rende possibile l'editing operativo, ma introduce una finestra di incoerenza controllata.

          EDITING / FEATURE SPACE                   TOPOLOGY SPACE
    +--------------------------------+       +---------------------------+
    | Devices / Junctions / Lines    |       | Connectivity index        |
    | Junction & Edge Objects        |       | Terminal connectivity     |
    | Associations / attributes      | ----> | Traversable relationships |
    +--------------------------------+       +---------------------------+
                  |                                      ^
                  v                                      |
          Dirty-area markers -------------------- Validate
          (delta / possible errors)             (evaluate & update)
Schema concettuale: non rappresenta il formato fisico interno proprietario dell'indice Esri.

Una linea che tocca geometricamente un device non è automaticamente attraversabile. Contano anche le regole di connessione, il gruppo/tipo di asset, i terminali, la presenza di associazioni esplicite e gli attributi che controllano la traversabilità. Una geometria apparentemente corretta può quindi produrre un errore di topologia.

2. Network topology: enable, disable e lifecycle

La topologia deve essere abilitata per poter eseguire correttamente le operazioni che dipendono dall'indice. L'operazione iniziale di Enable Network Topology costruisce la rappresentazione topologica e valuta gli elementi della rete; nelle successive sessioni di editing, la sincronizzazione avviene mediante validazione delle aree modificate.

OperazioneSignificatoUso corretto
Enable Network TopologyAbilita/costruisce la topologia e verifica la reteAttivazione dopo configurazione e caricamento
Disable Network TopologyDisabilita l'indice per operazioni di configurazione che lo richiedonoManutenzione amministrativa pianificata
Validate Network TopologyRivaluta gli elementi marcati come dirty nell'area richiestaFlusso operativo ordinario dopo modifiche
Rebuild Network TopologyRicostruzione/repair dell'indice nell'ambito supportatoRecupero da inconsistenze o failure, non routine

Una regola pratica: Validate non equivale a Rebuild. La validazione incrementale è progettata per il lavoro ordinario; il rebuild è una misura di riparazione, potenzialmente più onerosa. In geodatabase enterprise, i requisiti di versione e servizio vanno verificati prima di usare i comandi amministrativi.

3. Dirty areas: invalidazione incrementale dell'indice

Una dirty area indica che una porzione della topologia potrebbe non rappresentare più lo stato corrente delle feature. Può essere generata da editing geometrico, variazioni di attributi rilevanti per la rete o modifiche alle associazioni. Non è sinonimo di errore: dirty significa «da rivalutare», mentre error significa «violazione rilevata».

Si consideri un sezionatore elettrico spostato o riconfigurato. L'editing aggiorna la feature; l'indice topologico può ancora rappresentare lo stato precedente. La dirty area delimita la regione che necessita di validazione prima di affidarsi ai risultati del tracing.

Implicazione per outage management. Una traccia che attraversa un'area dirty può fallire oppure non riflettere gli ultimi edit. In un sistema operativo critico non si dovrebbe disabilitare silenziosamente la verifica di consistenza soltanto per ottenere una risposta.

3.1 Dirty non significa necessariamente errore

  1. L'operatore modifica un attributo di connettività.
  2. La modifica viene salvata nella versione di lavoro.
  3. La rete marca la regione interessata come dirty.
  4. La validazione valuta regole, geometria, terminali e relazioni.
  5. Se l'elemento è valido, l'indice viene aggiornato e la dirty area può essere eliminata; se è invalido, rimane un errore da correggere.

3.2 Errori persistenti e correzione

Le violazioni possono derivare da asset type incompatibili, connessioni non ammesse, terminali non corretti, geometrie non valide o associazioni incoerenti. La correzione richiede un intervento sui dati oppure, quando il modello di rete è sbagliato, sulla configurazione e sulle regole. Ripetere Validate senza correggere la causa non risolve un errore strutturale.

4. Il motore di validazione: modello concettuale e confini documentati

Esri espone la validazione attraverso ArcGIS Pro, geoprocessing e REST. Il dettaglio degli algoritmi e del formato fisico dell'indice topologico non è un contratto pubblico da cui dedurre strutture interne. È invece possibile descrivere il comportamento osservabile:

Requested validation extent
          |
          v
Identify intersecting dirty areas
          |
          v
Read affected network features / associations
          |
          v
Evaluate connectivity constraints and rules
          |
          +---- Invalid ----> Error feature / persistent dirty condition
          |
          +---- Valid ------> Update topology index / clear resolved dirty
          |
          v
Return status + discovered dirty subnetworks (where applicable)

La validazione può interessare soltanto un sottoinsieme delle dirty areas presenti nella rete. Il risultato di una chiamata non deve quindi essere interpretato come certificazione della consistenza dell'intera utility network. Inoltre, l'operazione REST può restituire discoveredSubnetworks: subnetworks marcate come dirty durante la validazione, da gestire nel successivo workflow di manutenzione delle subnetworks.

5. Validazione sincrona e asincrona

ArcGIS Pro distingue il comando Validate sulla ribbon, che usa elaborazione sincrona, dal geoprocessing tool Validate Network Topology, che in un'enterprise geodatabase utilizza elaborazione asincrona attraverso il servizio UtilityNetworkTools nella cartella System. Il servizio dedicato dispone di timeout appropriati per operazioni più lunghe.

ScenarioApproccioMotivo
Piccola area dopo editValidate su current extentFeedback immediato all'operatore
Molte dirty areasGeoprocessing asincronoDurata maggiore e gestione job
Riparazione indiceRebuild supportato e pianificatoNon confondere repair con validazione incrementale
Automazione serverREST + job tracking / orchestrazioneRetry controllati e audit

La dimensione geografica dell'extent non è un buon proxy universale del costo: una piccola area densamente connessa può contenere più elementi e associazioni di un'area molto grande. Il costo dipende dalla densità di feature, dal numero di dirty areas, dalle associazioni e dalla complessità della rete.

6. Workflow enterprise con branch versioning

In un'enterprise geodatabase branch-versioned, ogni workflow deve esplicitare quale versione viene modificata e validata. Non è sufficiente conoscere l'URL del feature service: le operazioni devono mantenere coerenti il contesto di versione, la sessione di editing e il successivo processo di reconcile/post.

DEFAULT
   |
   +--> Create named branch version
                |
                v
           Edit features
                |
                v
           Dirty areas
                |
                v
         Validate topology
                |
        +-------+-------+
        |               |
      Errors         No errors
        |               |
   Correct edits         v
        +----------> Reconcile / resolve conflicts
                            |
                            v
                           Post
                            |
                            v
                     Validate/verify target state
                     and subnetwork maintenance
Workflow logico: reconcile, post e validazione hanno prerequisiti e comportamenti dipendenti dalla versione e dal modello di servizio.

Una validazione effettuata in una named version non sostituisce automaticamente la verifica dello stato di DEFAULT dopo il post. Inoltre, la coerenza della network topology e lo stato aggiornato delle subnetworks sono due concetti distinti: un indice valido non implica necessariamente che tutte le subnetworks siano già state aggiornate.

7. REST API: validateNetworkTopology

La Utility Network Server REST API espone l'operazione POST /UtilityNetworkServer/validateNetworkTopology. Richiede i privilegi e le licenze appropriati (fra cui l'estensione ArcGIS Advanced Editing secondo la documentazione corrente), una topologia abilitata e un contesto di versione coerente. Sono supportate modalità sincrona e asincrona.

POST https://gis.example.org/server/rest/services/Utilities/Electric/FeatureServer/UtilityNetworkServer/validateNetworkTopology
Content-Type: application/x-www-form-urlencoded

f=json&token=REDACTED&gdbVersion=USER.QA_VERSION&validateArea={...}

Esempio schematico: i parametri obbligatori e la serializzazione della geometria dipendono dalla versione REST e dall'operazione scelta. Prima dell'esecuzione consultare lo schema ufficiale, inclusi sessionId, async e gli eventuali parametri di esecuzione richiesti. Non inserire token in log, query string o repository.

7.1 Contratto applicativo robusto

Un client di automazione dovrebbe registrare correlationId, versione, extent, orario, stato del job, errori e subnetworks scoperte. In caso di timeout di rete non è sicuro assumere che l'operazione server sia fallita: prima di ripetere un comando occorre recuperare lo stato del job, se disponibile.

8. Laboratorio ArcPy — ispezione e validazione di un'area

Il seguente esempio illustra il pattern di validazione in ArcGIS Pro con un Utility Network layer già configurato. La sintassi del geoprocessing tool va verificata contro la versione ArcGIS Pro in uso; l'esempio è intenzionalmente minimale per non introdurre parametri opzionali dipendenti dal rilascio.

import arcpy
from datetime import datetime, timezone

# Percorso di un layer Utility Network nel progetto ArcGIS Pro.
# In enterprise, utilizzare una connessione/servizio supportato.
un_layer = r"C:\GIS\Project\ElectricUtilityNetwork"

started = datetime.now(timezone.utc)
try:
    # L'extent può essere specificato tramite il parametro dedicato
    # del tool, a seconda della release e del contesto di esecuzione.
    result = arcpy.un.ValidateNetworkTopology(un_layer)
    print(result.getMessages())
except arcpy.ExecuteError:
    print(arcpy.GetMessages(2))
    raise
finally:
    elapsed = (datetime.now(timezone.utc) - started).total_seconds()
    print(f"Elapsed seconds: {elapsed:.2f}")

In laboratorio, eseguire prima una modifica controllata su una named version e verificare che compaia una dirty area. Validare, quindi osservare separatamente la scomparsa della dirty area e l'eventuale comparsa di errori. Per un test di errore, introdurre una connessione non consentita dalle regole della rete e ripetere la validazione.

Prerequisito importante. Il codice non crea un'utility network di prova e non bypassa licenze, servizi o privilegi. Il percorso del layer e i parametri vanno adattati alla propria installazione. Usare un dataset di test, non DEFAULT di produzione.

9. Laboratorio C# — ArcGIS Maps SDK for .NET: stato, dirty areas e validazione

Per applicazioni desktop .NET, Esri documenta un sample completo che carica la UtilityNetwork, crea una branch version, mostra il DirtyAreaTable, modifica feature, applica gli edit e avvia un job di validazione. Il pattern centrale è il seguente:

using Esri.ArcGISRuntime.Geometry;
using Esri.ArcGISRuntime.UtilityNetworks;

// utilityNetwork deve essere già caricato e associato
// a un servizio che supporta le capability richieste.
var state = await utilityNetwork.GetStateAsync();

Console.WriteLine($"Topology enabled: {state.IsNetworkTopologyEnabled}");
Console.WriteLine($"Dirty areas: {state.HasDirtyAreas}");
Console.WriteLine($"Errors: {state.HasErrors}");

if (!state.IsNetworkTopologyEnabled)
    throw new InvalidOperationException("Topology not enabled");

if (!utilityNetwork.Definition.Capabilities.SupportsValidateNetworkTopology)
    throw new NotSupportedException("Validation not supported");

Envelope extent = currentMapExtent; // Extent ricavato dalla vista
var job = utilityNetwork.ValidateNetworkTopology(extent);
var result = await job.GetResultAsync();

Console.WriteLine($"Remaining dirty areas: {result.HasDirtyAreas}");
Console.WriteLine($"New errors: {result.HasErrors}");

Il codice è un frammento integrabile, non un'applicazione standalone: utilityNetwork e currentMapExtent devono essere inizializzati dall'app. Inoltre, result.HasErrors descrive gli errori segnalati dal risultato della validazione, mentre GetStateAsync() fornisce lo stato della rete. Le due informazioni non sono intercambiabili.

10. Trace consistency: correttezza prima della disponibilità

Esri documenta che i trace dipendono dall'indice topologico e possono produrre errori o risultati non aggiornati quando attraversano aree dirty. Le API consentono di controllare la verifica della consistenza tramite la configurazione del trace. La decisione deve dipendere dal rischio applicativo:

ApplicazionePolitica suggeritaRischio accettabile
Outage management / manovre reteRichiedere consistenza e validazioneMolto basso
Analisi di impatto su infrastrutture criticheBloccare o segnalare dirty areaBasso
Ispezione e inventario non operativoPossibile tolleranza, con avviso esplicitoDipende dal caso d'uso
Analisi esplorativaConsentire risultati provvisori etichettatiPiù alto, se dichiarato

Disabilitare la validazione di consistenza può essere una scelta applicativa legittima per alcune attività, ma non corregge l'indice e non elimina l'incertezza del risultato.

11. Performance engineering: cosa misurare davvero

Un benchmark di validazione dovrebbe controllare almeno quattro dimensioni: densità delle feature, quantità di dirty areas, tipo di edit e versione della geodatabase. Il semplice tempo medio di esecuzione non è sufficiente.

MetricaDefinizioneInterpretazione
Validation duration P50/P95/P99Durata per jobDistribuzione della latenza operativa
Dirty area backlogAree non validate per versioneAccumulo di debito topologico
Validation error rateJob con errori / job totaliQualità dati e configurazione
Dirty-to-clean lead timeTempo fra edit e topologia aggiornataFreshness del grafo
Trace rejection rateTrace rifiutati per inconsistenzaImpatto sull'operatività
Discovered subnetworksSubnetworks marcate dirtyCarico della manutenzione successiva

11.1 Il problema del batch size

Un extent molto ampio riduce il numero di richieste ma può aumentare la durata e la contesa; extent piccoli producono job più gestibili, ma possono aumentare overhead e frammentazione del lavoro. Non esiste una dimensione ottimale universale. La scelta va misurata su dataset reali, distinguendo i tempi server dai tempi di rete e di attesa del job.

11.2 SQL Server e branch versioning

In un deployment enterprise, le prestazioni dipendono anche da statistiche, indici, dimensioni delle tabelle, I/O, concorrenza e query generate dal geodatabase. È però scorretto dedurre che ogni rallentamento della validazione sia causato da SQL Server: il costo può risiedere nella valutazione topologica, nella complessità delle associazioni o nei servizi GIS. Utilizzare osservabilità coordinata fra ArcGIS Server e database.

12. Error taxonomy e troubleshooting

Gli errori di utility network non dovrebbero essere gestiti come una singola categoria. Conviene classificarli per causa:

  • Geometry: posizionamenti e intersezioni non coerenti con la connettività prevista.
  • Asset classification: asset group/type incompatibili con le regole.
  • Terminals: assegnazioni e percorsi terminali non consentiti.
  • Associations: connectivity, containment o structural attachment incoerenti.
  • Configuration: regole o definizioni di rete incomplete rispetto ai dati.
  • Operational: versioni, sessioni, privilegi, servizi e job non corretti.

Gli ID ufficiali degli errori devono essere recuperati dalla documentazione Esri relativa alla propria utility network version. Non usare una tabella di ID copiata da un'altra release come contratto universale.

13. Runbook di validazione per un ambiente enterprise

  1. Verificare la versione ArcGIS Pro/Enterprise, la utility network version, le licenze e la presenza dei servizi richiesti.
  2. Individuare la named version e acquisire l'extent effettivo dell'operazione.
  3. Registrare numero e distribuzione delle dirty areas prima dell'intervento.
  4. Eseguire validazione sincrona su area piccola o job asincrono per workload estesi.
  5. Distinguere failure del job da errori topologici rilevati correttamente dal job.
  6. Classificare e correggere gli errori persistenti; non ripetere indiscriminatamente il job.
  7. Verificare la riduzione del backlog dirty e lo stato delle subnetworks interessate.
  8. Eseguire reconcile/post secondo il workflow di versioning adottato, quindi controllare lo stato di destinazione.
  9. Registrare durata, versione, extent, operatore e risultato per audit e capacity planning.

14. Failure modes e anti-pattern

Anti-patternConseguenzaAlternativa
Validare sempre l'intera rete dopo ogni editCarico e latenza non necessariValidazione incrementale per area e workflow
Ignorare dirty areas nei trace criticiRisultati non affidabiliConsistency check e blocco controllato
Usare Rebuild come routineOperazioni più costose e rischio operativoRebuild soltanto per repair documentato
Trattare gli errori come semplici dirty areasBacklog che non si risolveRoot cause su dati e regole
Non registrare la branch versionDiagnostica non riproducibileCorrelation ID + versione + extent
Confondere topology clean e subnetwork updatedStato analitico incompletoWorkflow esplicito per le subnetworks

15. Esperimento riproducibile: protocollo di benchmark

Per confrontare due configurazioni senza produrre conclusioni fuorvianti, utilizzare un dataset di test ripristinabile e ripetere almeno tre classi di editing:

  1. Attribute-only: modificare attributi rilevanti per la connettività di un campione di device.
  2. Geometry edits: spostare punti e modificare segmenti entro un'area controllata.
  3. Association edits: modificare associazioni consentite e, separatamente, introdurre casi di errore previsti.

Per ogni classe, misurare numero di feature modificate, dirty areas prodotte, durata P50/P95, errori, discovered subnetworks e latenza del trace successivo. Ripristinare lo stesso stato iniziale prima di ogni serie; evitare di confrontare run eseguiti su versioni con backlog diverso.

16. Decisioni architetturali

Il progetto di una Utility Network enterprise deve formalizzare almeno quattro decisioni:

  • Freshness SLA: entro quanto tempo un edit deve essere riflesso nell'indice topologico?
  • Trace policy: quali applicazioni possono tollerare dirty areas e con quale messaggio all'utente?
  • Validation ownership: operatore GIS, processo schedulato o workflow transazionale applicativo?
  • Error remediation: chi corregge i dati, chi modifica le regole e come viene verificata la risoluzione?

Queste decisioni non sono dettagli implementativi: determinano la correttezza dei risultati di analisi, la qualità del servizio e la possibilità di eseguire audit.

17. Conclusioni

La network topology è il confine fra il mondo modificabile delle feature e il mondo analitico della connettività. Le dirty areas rendono esplicita la possibile incoerenza; la validazione è il processo controllato che riallinea i due mondi. Gli errori persistenti rappresentano invece violazioni del modello e richiedono correzioni reali.

Una Utility Network affidabile non è semplicemente una rete senza errori visibili sulla mappa. È un sistema nel quale editing, validazione, versioning, tracing e manutenzione delle subnetworks hanno contratti operativi verificabili e metriche osservabili.

Fonti primarie e documentazione

  1. Esri ArcGIS Pro — Validate a network topology
  2. Esri ArcGIS Pro — Validate Network Topology (geoprocessing)
  3. Esri ArcGIS Pro — Errors in a utility network
  4. Esri REST — validateNetworkTopology
  5. Esri Maps SDK for .NET — Validate utility network topology sample
  6. Esri Maps SDK for .NET — Trace configuration and dirty areas

Nota metodologica: i diagrammi del motore sono modelli concettuali e non descrizioni del formato interno proprietario Esri. I frammenti di codice mostrano pattern da integrare in un ambiente ArcGIS correttamente configurato. Prima dell'esecuzione in produzione verificare firme API, permessi e compatibilità della release effettivamente installata.

Utility NetworkArcGIS EnterpriseTopology ValidationBranch VersioningC# / ArcPy

giovedì 29 ottobre 2026

ArcGIS Utility Network — Part 1: Architecture, Data Model, Network Versions & Enterprise Engineering

NicoGIS Tech Weekly · Engineering Deep Dive · 29 ottobre 2026 · Serie ArcGIS Utility Network, parte 1 di 8

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.

Geodatabase / Feature Dataset │ ├── Utility Network [controller dataset] │ ├── Structure Network [condivisa] │ │ ├── Structure Junction / Line / Boundary │ │ └── Structure Junction Object / Edge Object │ ├── Domain Network A [es. Electric] │ │ ├── Device / Junction / Line / Assembly / SubnetLine │ │ └── Junction Object / Edge Object │ ├── Domain Network B [es. Telecom] │ ├── Network Rules / Attributes / Terminal Configurations │ ├── Associations [system maintained] │ └── Network Topology [indice e stato di validazione] └── Service Territory [limite geografico operativo]

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 è:

Edit features / associations ↓ Dirty areas created ↓ Validate network topology ↓ Rules / connectivity checks ↙ ↘ Errors Validated index ↓ Trace / Diagram / Subnetwork

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.

AssociationSemanticaEsempioConseguenza
ConnectivityConnessione funzionale non necessariamente coincidentePorta di apparato ↔ fibraPuò influenzare il grafo attraversabile
ContainmentUn oggetto è contenuto in un altroGiunzione ↔ armadioGerarchia di contenimento e rappresentazione
Structural attachmentUn asset è sostenuto da una strutturaCavo ↔ paloRelazione 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à

ArcGIS Pro / Web Client / API Consumer │ ArcGIS Enterprise │ ┌────────────┼───────────────┐ │ │ │ Feature Utility Network Diagram Service Network Service │ Service │ └────────────┼───────────────┘ │ Version Management (when enabled) │ Enterprise Geodatabase (branch versioned) │ Utility Network Controller Dataset

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 VersionArcGIS Pro minimoArcGIS Enterprise minimoNota
42.610.8.1Compatibilità storica
52.710.9Schema successivo
63.011.0Aggiornamenti interni per Pro 3.0 e diagrammi
73.311.3Supporto 64-bit Object IDs e nuove capacità
8Verificare la matrice ufficiale della release corrente prima del deploymentPrerequisito 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.

IndicatorePerché contaMetodo di misura
Trace P50/P95/P99Rileva code e outlierTelemetry lato client + log ArcGIS Server
Validazione per areaMisura costo incrementale della topologiaDurata e dirty areas prima/dopo
Associazioni per assetIndividua hotspot di cardinalitàInventario semantico e query supportate
Reconcile/postQuantifica costo della collaborazioneDurata, conflitti e dimensione change set
Timeout e saturazione serviziIndividua colli di bottiglia operativiMetriche 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

  1. Part 1 — Architecture, Data Model, Network Versions & Enterprise Engineering (questa puntata).
  2. Part 2 — Network Topology: Dirty Areas, Validation, Error Engine & Performance.
  3. Part 3 — Network Rules, Associations & Terminal Engineering.
  4. Part 4 — Subnetworks, Controllers, Update Pipelines & Propagation.
  5. Part 5 — Trace Engine: Upstream, Downstream, Isolation & Named Configurations.
  6. Part 6 — Branch Versioning: Reconcile/Post, Conflict Resolution & Multiuser Editing.
  7. Part 7 — ArcGIS Pro SDK C#, ArcPy & REST: Advanced Developer Laboratory.
  8. Part 8 — Enterprise Architecture: Migration, Operations, Tuning & Automation.

18. Riferimenti ufficiali e approfondimenti

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.