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.
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)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.
| Operazione | Significato | Uso corretto |
|---|---|---|
| Enable Network Topology | Abilita/costruisce la topologia e verifica la rete | Attivazione dopo configurazione e caricamento |
| Disable Network Topology | Disabilita l'indice per operazioni di configurazione che lo richiedono | Manutenzione amministrativa pianificata |
| Validate Network Topology | Rivaluta gli elementi marcati come dirty nell'area richiesta | Flusso operativo ordinario dopo modifiche |
| Rebuild Network Topology | Ricostruzione/repair dell'indice nell'ambito supportato | Recupero 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.
3.1 Dirty non significa necessariamente errore
- L'operatore modifica un attributo di connettività.
- La modifica viene salvata nella versione di lavoro.
- La rete marca la regione interessata come dirty.
- La validazione valuta regole, geometria, terminali e relazioni.
- 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.
| Scenario | Approccio | Motivo |
|---|---|---|
| Piccola area dopo edit | Validate su current extent | Feedback immediato all'operatore |
| Molte dirty areas | Geoprocessing asincrono | Durata maggiore e gestione job |
| Riparazione indice | Rebuild supportato e pianificato | Non confondere repair con validazione incrementale |
| Automazione server | REST + job tracking / orchestrazione | Retry 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 maintenanceUna 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.
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:
| Applicazione | Politica suggerita | Rischio accettabile |
|---|---|---|
| Outage management / manovre rete | Richiedere consistenza e validazione | Molto basso |
| Analisi di impatto su infrastrutture critiche | Bloccare o segnalare dirty area | Basso |
| Ispezione e inventario non operativo | Possibile tolleranza, con avviso esplicito | Dipende dal caso d'uso |
| Analisi esplorativa | Consentire risultati provvisori etichettati | Più 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.
| Metrica | Definizione | Interpretazione |
|---|---|---|
| Validation duration P50/P95/P99 | Durata per job | Distribuzione della latenza operativa |
| Dirty area backlog | Aree non validate per versione | Accumulo di debito topologico |
| Validation error rate | Job con errori / job totali | Qualità dati e configurazione |
| Dirty-to-clean lead time | Tempo fra edit e topologia aggiornata | Freshness del grafo |
| Trace rejection rate | Trace rifiutati per inconsistenza | Impatto sull'operatività |
| Discovered subnetworks | Subnetworks marcate dirty | Carico 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
- Verificare la versione ArcGIS Pro/Enterprise, la utility network version, le licenze e la presenza dei servizi richiesti.
- Individuare la named version e acquisire l'extent effettivo dell'operazione.
- Registrare numero e distribuzione delle dirty areas prima dell'intervento.
- Eseguire validazione sincrona su area piccola o job asincrono per workload estesi.
- Distinguere failure del job da errori topologici rilevati correttamente dal job.
- Classificare e correggere gli errori persistenti; non ripetere indiscriminatamente il job.
- Verificare la riduzione del backlog dirty e lo stato delle subnetworks interessate.
- Eseguire reconcile/post secondo il workflow di versioning adottato, quindi controllare lo stato di destinazione.
- Registrare durata, versione, extent, operatore e risultato per audit e capacity planning.
14. Failure modes e anti-pattern
| Anti-pattern | Conseguenza | Alternativa |
|---|---|---|
| Validare sempre l'intera rete dopo ogni edit | Carico e latenza non necessari | Validazione incrementale per area e workflow |
| Ignorare dirty areas nei trace critici | Risultati non affidabili | Consistency check e blocco controllato |
| Usare Rebuild come routine | Operazioni più costose e rischio operativo | Rebuild soltanto per repair documentato |
| Trattare gli errori come semplici dirty areas | Backlog che non si risolve | Root cause su dati e regole |
| Non registrare la branch version | Diagnostica non riproducibile | Correlation ID + versione + extent |
| Confondere topology clean e subnetwork updated | Stato analitico incompleto | Workflow 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:
- Attribute-only: modificare attributi rilevanti per la connettività di un campione di device.
- Geometry edits: spostare punti e modificare segmenti entro un'area controllata.
- 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
- Esri ArcGIS Pro — Validate a network topology
- Esri ArcGIS Pro — Validate Network Topology (geoprocessing)
- Esri ArcGIS Pro — Errors in a utility network
- Esri REST — validateNetworkTopology
- Esri Maps SDK for .NET — Validate utility network topology sample
- 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
Nessun commento:
Posta un commento