13 min read2,893 words

Branch Versioning & Conflict Resolution for Utility Networks

Branch versioning is what makes a utility network editable by more than one person at a time, and it is where a surprising share of production incidents originate — not because the mechanism is unreliable, but because its failure modes are procedural rather than technical. A version that is never reconciled drifts until its edits no longer apply. A version reconciled with an automatic conflict rule quietly discards a field crew’s correction. A batch job pointed at the default version during editing hours produces lock contention that the team resolves by not running the job. None of these throw; all of them end with the model disagreeing with the field.

This page treats versioning as an engineering control rather than a storage detail. It covers the lifecycle a version moves through, what a conflict actually is in a network model where features carry associations, how to decide what may be resolved by rule and what must reach a person, and how automation should choose between a version and a snapshot — a decision most batch jobs get wrong in the same direction. It assumes the topology discipline established in topology and tracing workflows and the validation ordering described in batch topology processing with Python.

The life of a branch version, from creation to post A version is created from the default version at a moment in time and inherits everything the default held then. Edits accumulate inside it, invisible to everyone else. Reconcile pulls in everything the default version has gained since that moment and is where conflicts surface. Validation runs against the reconciled state, because validating before reconcile measures a network that is already out of date. Post publishes the edits to the default version, and only then do the trace services and every other consumer see them. CREATE branched from DEFAULT at a moment EDIT isolated changes invisible to others RECONCILE pull in DEFAULT conflicts surface VALIDATE after reconcile never before POST published to DEFAULT consumers see it both edited CONFLICT the same feature changed on both sides a person decides, not the tool Validating before reconcile measures a network that has already moved on.

Prerequisite Checklist

Core Model: What a Version Actually Holds

A branch version is not a copy of the network. It is a set of differences against the default version, evaluated at read time. That single fact explains most of the behaviour that surprises people.

A version has a moment. It was branched from the default version at a specific time, and until it reconciles, it sees the network as it was then plus its own edits. Two editors working in parallel are each looking at a different network, and neither is wrong.

Reconcile is the merge. It pulls everything the default version has gained since the branch moment into the version, and it is the only point at which conflicts can be detected. A version that reconciles daily meets small, comprehensible conflicts; a version that reconciles after three months meets a merge nobody can reason about.

Post is publication. It applies the version’s differences to the default version, where every downstream consumer — trace services, outage management, reporting — reads them. A post is therefore an operational event, not a save.

Associations complicate all of it. In a plain feature class a conflict is about a row. In a utility network, containment, structural attachment and connectivity rows are features too, and they reference other features. Deleting a container on one side while adding a contained asset on the other produces a conflict whose safe resolution is not “take one side” but “keep both and raise it”, because either automatic answer leaves an orphan the asset hierarchy rules forbid.

The conflict classes a utility network produces, and who can resolve each An attribute conflict is two edits to different fields of the same row and is usually mergeable by rule. A geometry conflict is two edits to the same shape and needs a human, because merging geometry silently invents a third position nobody surveyed. A delete-update conflict is one side removing what the other edited, and it is always an engineering question. An association conflict — a containment or connectivity row edited on both sides — is the one most likely to be resolved wrongly by default, because the losing side leaves a feature attached to nothing. Conflict class What happened Safe default Who decides Attribute different fields, same row merge by field ownership rule Geometry same shape moved twice none — hold for review editor Delete vs update one side removed it keep the feature, flag it engineer Association containment or connectivity none — hold for review engineer Only the first class is safely automatable; the rest need a decision.

Step-by-Step Implementation

  1. Create a version per unit of work, not per person. A version named for a work order can be discarded when the work is cancelled; a version named for an editor accumulates unrelated changes that cannot be separated afterwards.
  2. Reconcile early and often. A daily reconcile turns merge into a routine that surfaces conflicts while both editors still remember the change. Automate the reconcile; leave the conflict decisions to people.
  3. Resolve by declared ownership, never by recency. For attribute conflicts, apply the per-field ownership map — the same discipline the CMMS and GIS work-order integration uses across systems. Last-writer-wins is not a policy; it is the absence of one.
  4. Hold geometry, delete-update and association conflicts for review. These are the classes where an automatic answer produces a plausible, wrong network. Route them to an engineer with both versions of the change visible.
  5. Validate after reconcile, before post. Reconciling can introduce dirty areas that neither editor created, because the merge itself changes connectivity. Validation before reconcile measures a state that will not be published.
  6. Post through a separate account and gate it. The post is the control point: no dirty areas, no unresolved conflicts, validation clean, and — for changes that alter connectivity — a confirming trace that proves reachability survived.
  7. Delete the version after the post. A posted version left in place is re-reconciled forever and eventually becomes a source of phantom conflicts.

Diagnostic Protocol

  1. Check the version’s age first. Most conflict pathologies are simply a version that has not reconciled in weeks. The fix is process, not tooling.
  2. Separate real conflicts from reconcile artefacts. A feature that appears conflicted with no edit on either side usually means the row was touched by a topology validation rather than by a person.
  3. Look for association orphans after a resolution. After any delete-update resolution, query for contained features whose parent no longer exists. This is the most common quiet outcome of an automatic resolution.
  4. Confirm the topology was validated after reconcile. A version posted with dirty areas publishes them to the default version, where they become everyone’s problem.
  5. Check for posting to the wrong parent. In a multi-level versioning scheme, posting a child into the wrong parent moves the edits somewhere plausible and wrong; the version tree, not the feature, is where this is visible.
  6. Watch for long-running readers. A read-only job holding a connection against the default version during a post window can block it. If posts are timing out, look at what is reading before looking at what is writing.
Choosing between a named version and a read-only snapshot for a job A job that writes needs a version, because a snapshot cannot receive edits and writing to the default version during working hours is what produces lock contention. A job that only reads should prefer a snapshot: it is immune to concurrent editing, it costs nothing to hold open, and it gives every consumer of the run the same picture. The exception is a read that must see uncommitted work — a validation inside an editor version — which has to run in that version by definition. Does the job write to the network? yes — it edits Named version, always rule Never sde.DEFAULT during editing hours pattern One version per work order, discarded on failure no — read only Must it see uncommitted edits? validation Yes — run inside that editor version analysis No — reconciled snapshot or replica Most batch jobs read; most batch jobs are nonetheless pointed at a version by habit.

Performance & Scale Considerations

Reconcile cost scales with the age of the version, not its size. A version with four edits that has not reconciled for a month still has to evaluate everything the default version gained in that month. Frequent reconciles are cheaper in total than one large one, and they fail more comprehensibly.

Post is a write against the default version and serialises. Two posts cannot proceed at once, so an estate with many concurrent editors needs a post window or a queue rather than an expectation that posts are instant.

Read-only work belongs off the editing path. Analysis, reporting and batch traces should read a reconciled replica or a snapshot. This is the single change that removes most contention, and it is usually available without any new infrastructure.

Version count matters. Hundreds of stale versions slow reconcile for everyone, because the version tree is walked. A lifecycle policy — post or discard within a defined window — is a performance control as much as a housekeeping one.

Compliance Notes

  • Attributable change. Branch versioning provides the audit trail regulators expect: who edited what, in which version, reconciled and posted when. That trail is only as good as the version naming, which is why naming versions for work orders matters beyond convenience.
  • Separation of duties. Where a regulatory framework expects the person performing work not to be the person approving it, the edit and post permissions are the mechanism. Automate the post from a service account gated on validation rather than granting post rights broadly.
  • Reconstruction. Reliability and safety reviews ask what the model held at a given moment. Retain the reconcile and post history, and record the version moment alongside any published figure, so the state that produced it can be rebuilt.
  • Required audit metadata per post: version name, work order, creation and reconcile timestamps, conflicts by class and their resolutions, validation result, and the account that posted.

Versioning Patterns That Work in Practice

Three patterns cover almost every real workflow, and mixing them without naming which one is in play is where estates get into trouble.

The work-order version is created for one job, lives hours or days, and is discarded or posted at the end of it. It is the default pattern and the one every other should be justified against. Its virtue is that its scope is exactly the work: if the job is cancelled, the version goes with it, and nothing has to be unpicked.

The project version carries a capital project through design, as-built capture and commissioning, and may live for months. It needs a reconcile schedule of its own, because a version that old will otherwise meet an unmergeable merge at the end. The workable discipline is a weekly reconcile with conflicts triaged as they appear, plus a rule that the project version never posts partially — a half-commissioned project in the operational model is worse than one that is entirely absent.

The automation version is created and destroyed by a batch job within a single run. It exists so the job’s writes are isolated, and it should never outlive the run. The failure to watch for is the abandoned automation version: a job that crashes after creating its version and before discarding it leaves a version that reconciles forever and slows everyone down.

What these have in common is a stated lifetime. A version with no expected end date is the one that becomes a parallel network, and a parallel network is discovered when somebody notices two maps disagree.

Automating the Reconcile Without Automating the Decision

Reconcile is mechanical and should be automated; conflict resolution is a judgement and mostly should not be. Separating them is what makes automation safe here.

A scheduled job can reconcile every open version nightly, detect conflicts, and stop. What it produces is a queue: for each conflict, the feature, the class of conflict, both sides of the change, and the version and editor each came from. That queue is worked by people, and the volume is manageable precisely because the reconcile is frequent.

The narrow exception is the attribute conflict where field ownership is declared. If the work-management system owns the work status and the geographic system owns the location, then two edits to those two fields on the same row are not a conflict at all — they are two owners writing their own data, and the merge is deterministic. Automating that case removes most of the volume and leaves the queue populated only by the conflicts that genuinely need a decision.

Two guardrails keep this honest. Log every automatic resolution with the rule that made it, so an unexpected outcome can be traced to a policy rather than to a mystery. And cap the automation: if the number of automatic resolutions in one reconcile exceeds a threshold, stop and raise, because a sudden flood of mergeable conflicts usually means a bulk process is fighting an editor.

What Goes Wrong at Scale

Three patterns account for most of the versioning incidents worth writing down.

The version that never posts. A project version accumulates six months of as-built capture, reconciles rarely, and finally attempts to post into a default version that has moved substantially. The merge is too large to reason about, so the post is deferred again. The estate now has two networks, and field crews learn which one to believe. The prevention is the reconcile schedule, not a better merge tool.

The batch job on the default version. A nightly process writes directly to the default version because it was simpler to build that way. It holds locks during the post window, intermittently blocking editors, and the response is to move the editors rather than the job. Pointing the job at its own version costs an afternoon and removes the contention permanently.

The reconcile that ran during a post. An automated reconcile scheduled without regard to the post window meets a default version that is being written to, and the resulting failures look random. Sequencing the two — posts in one window, reconciles in another — removes a class of intermittent errors that otherwise gets attributed to the database.

The automatic resolution nobody reviewed. A reconcile configured to favour the version being edited silently discards a correction made in the default version by a data steward. Nothing fails; the correction simply reappears as a defect the following week. Declaring ownership per field, and holding everything else for review, is the only reliable prevention.

What ties the four together is that each is a policy failure with a technical symptom. The mechanism did exactly what it was configured to do; the configuration encoded an assumption nobody had written down. That is why the artefacts this page asks for — a naming convention, a stated version lifetime, a per-field ownership map, a post gate — are worth more than any tooling improvement. They are the places where the assumptions become visible, and an assumption that is visible is one that can be argued with before it ships rather than discovered during an event by a crew who found the model and the field disagreeing about which main was live.

In this section