Branch Versioning—What is it and How Does it Work?

You may have heard some chatter about Branch Versioning (especially if you have any involvement with Esri’s Utility Network solution where it’s a requirement). Branch Versioning is the future for supporting multiuser editing scenarios, so getting familiar with its tools and functionality is crucial.


Below, you’ll find a refresher of what you might already know about Branch Versioning, what you probably didn’t know before, and insight into how it all works.

What You Might Already Know
About Branch Versioning

Registering as Versioned

There are a couple of required prerequisites for registering as versioned:

  1. The Editor Tracking must be enabled (dates stored as UTC)
  2. A GlobalID field

When you’re, ready to register, the process is the same as it’s always been. Even so, it’s important to take time to double-check that your database connection file is set to Branch Versioning! When manually creating your connection file, it will default to Traditional Versioning.

Accidentally register with Tradition Versioning? Be sure to Unregister as Versioned before switching the database connection to Branch Versioning and trying again.

Editor Experience

When it comes to Editor Experience, the Create, Reconcile, Post operations function the same way Traditional Versioning does. The most notable change is that conflicts are persistent from session to session.
Here’s a helpful reminder—with ArcGIS Pro, you’re always editing so long as the layer is editable. This is convenient when you have a map sourced to a mix of Traditional Versioned and Branch Versioned data. Comparatively, with ArcMap, you could only edit one data source at a time.

Maintenance

As far as maintenance goes, nightly compress operations are no longer needed. Additionally, Version Management processing has now moved from the database to the ArcGIS Server site hosting the service.

What You Might Not Know About Branch Versioning

Version Changes

Version Changes with side-by-side maps is now available with ArcGIS Pro 2.4 and ArcGIS Server 10.7. This isn’t new from Traditional Versioning, but it is new to early adopters of Branch Versioning.

In the example below, you can see an existing polygon has its shape changed in the current ‘DrawPolygons’ version.

Add Archive

The Add Archive tool gives you the ability to access to the edit history of a record. In the following figure, we can see that this record was created on 3/15/2019 and subsequently updated multiple times through 7/2/2019.

Below we can see a record that was created, updated, and then ultimately deleted. Note that these rows are only captured and Default version. This means that the edits must be posted to Default or applied directly to Default.

It’s important to note that a direct connection to the database is required for utilizing this functionality. This is worth keeping in mind if you’re planning to take advantage of the REST architecture to separate your users from the database.

Historical Moments

Historical Moments allow you to go back in time to see a different state of your data. This is different from the Archive functionality in two ways:

  1. It doesn’t require a direct connection
  2. You only get one version of the record at a time. Using the Archive view of the table, we can highlight which record is being displayed when the date is changed.


Current Moment view of the data would only display the record in green. By using History Pane, we can set the date to 5/14/2019 3:00 PM, the map would then display the record in yellow. If we change the date to 5/14/2019 2:35 PM we would see the record in orange.

With our deleted record, Current Moment view of the data would result in no record being displayed. Looking at the row in red we can see that the most current GDB_FROM_DATE indicates that the record has been deleted (GDB_IS_DELETE = 1).

By using the History Pane, we can set the date to 11/26/2018 4:00 PM, the map would then display the record in yellow the map. If we then change the date to 5/14/2019 2:35 PM, we’d see the original record shown in orange.


Keep these things in mind as you use Historical Moments:

  1. For Default Version, the oldest date is the date the data was Registered as Versioned.
  2. For all other Versions, the oldest date is the date the version was created.
  3. Choosing older dates is not prevented and does not result in an error—your map simply looks like the database did at that time. For example, choosing a date older than when data was registered as versioned results in a blank map.

So How Does Branch Versioning Work?

Good news—if you have a grasp on what we just covered in Historical Moments, you understand how Branch Versioning works! Here are the two magical components you need to know:

  1. Registering as Versioned. It all starts here. Instead of the Adds/Deletes tables that Traditional Versioning creates for every feature class you register, Branch Versioning simply adds a few fields to each feature class. These can be identified by the GDB_ prefix.
  2. Embedded Query. When adding data to your map via the feature service, you’re seeing the result of embedded queries. These are utilizing those GDB_ attributes to present you with the most recent version of the record. This might sound like an expensive query, but it’s actually more performant than queries being executed with Traditional Versioning.
    • Attributes of Particular note are GDB_FROM_DATE, GDB_IS_DELETE (value of 0 means the record will be displayed, value of 1 means the record won’t be displayed) and GDB_BRANCH_ID (value of 0 is Default version, other values correspond to a user’s version)

Three Things You May Not Have Noticed
About Branch Versioning

  1. Edit operations must be made through the feature service. This includes mass updates and append operations. These can be accomplished with the Append geoprocessing tool, but a great alternative is Safe Software’s FME application. Using the Append tool sourced to feature class with and direct database connection will fail.
  2. OBJECTID and GlobalID values are no longer unique. This isn’t obvious to ArcGIS Pro users, but it’s very apparent when looking at tables with your preferred DBMS software. When registered as Branch Versioned, GDB_ARCHIVE_OID becomes the unique value on the table.
  3. The table just grows. It’s important to remember that a new row is added to the table to record every change, not just when new features are created. Remember how we mentioned you no longer need to execute the nightly compresses? Because of that, the replacement is of higher importance on your DBA maintaining those indexes. This doesn’t add much overhead if you’re only concerned with day-to-day editing, but what about those mass update moments? Every time you execute a mass field calculation on 100,000 records, you add 100,000 records to the table.

We know, it’s a bit of shock to realize we’re adding so many rows for a simple attribute update. Just remember how helpful Historical Moments and the Archive View are.

Keep this in mind for those other applications you may have connected to your database and remember they aren’t operating with the embedded queries. This could be your opportunity to transition them utilizing ArcGIS RES API. That, however, would be a topic for another day.