Understanding Subnetworks: Events
Welcome to the understanding subnetwork management series, where we deep-dive into some of the more advanced topics of subnetwork management. If you’re not familiar with what subnetworks are or how they work I recommend you read the articles and tutorials in the Managing Subnetworks with ArcGIS Utility Network learn series to get started.
Managing subnetworks can often involve making hundreds or thousands of edits to features when a subnetwork is created or reconfigured. Because of this, the system provides several different edit modes that can be used to make these updates.
What is an edit mode?
What is an edit mode? In the ArcGIS Utility Network, the edit mode refers to how the software will manage system fields on features when subnetworks are managed. There are currently two options for edit modes, with events or without events.
What “events” are we referring to when we say that we are managing data with events or without events? When we say events, we are referring specifically to geodatabase events. Geodatabase events are one of the ways that ArcGIS triggers special behaviors when objects in a geodatabase are edited. Common examples of this are behaviors like populating editor tracking fields, firing attribute rules, messaging changes to related objects, and updating feature-linked annotation.
What does this have to do with the subnetworks? One of the tools users commonly run as part of their editing workflow is the update subnetwork tool. This tool is responsible for managing system fields on utility network features that describe the subnetwork that they participate in. As each of these features is edited it triggers different editing events. Data models that include relationships or attribute rules will fire more events during update subnetwork than data models with fewer relationships and attribute rules. All the events, rules, and relationships add additional time to the update subnetwork process. To handle this situation administrators can configure the tiers in their network to use an editing mode that either uses the normal geodatabase events (with events) or bypasses the normal geodatabase event model (without events) when managing subnetworks in that tier. There is a brief discussion of how to evaluate business requirements and best practices for making this decision at the end of this article. But for now, let’s look at some examples of different configurations. In each example, we will be looking at how a set of features responds under certain conditions. Each feature is labeled with 4 fields, and when a value is modified the field/value will appear bolded:
- Asset ID – This is a unique identifier for each feature. It is populated when the feature is created.
- Date Modified – This is the editor tracking field that is maintained by the geodatabase.
- Subnetwork Name – This is the subnetwork name field maintained by the utility network.
- Network Region – This field is maintained by an attribute rule that uses the subnetwork name of the feature to retrieve a 'region' value from a lookup table.
Update without events in default
The first example we’ll look at is something that every project does at least once. Running update subnetwork on the default version in a brand-new database. In this case, all the subnetwork name fields in the database have the value ‘Unknown’ and the rest of the fields have their initial values from the data load. You can see an example of this in the graphic below.
Figure 1 Initial database state
After running update subnetwork on Network A, we can see that the subnetwork name field has been updated on all the features in the subnetwork, but editor tracking and attribute rules were not triggered during these updates. If any of our classes had feature-linked annotation the annotation would not be modified during this event as well.
Figure 2 Update subnetwork in default without events
Next, let’s compare this with how the system would behave if we performed the same action but with the edit mode set to with events.
Update with events in default
When the utility network is configured to update a subnetwork with events this means that all geodatabase behaviors will be triggered when update subnetwork updates the attributes on a feature. If the previous example was run with events, the results would look like the diagram below.
Figure 3 Update subnetwork in default with events
You can see that in addition to populating the subnetwork name field, the Last Modified field was also updated by editor tracking, and the Operating Area field was updated by our attribute rule. In addition to this, if there were feature-linked annotation features that referenced one or more of these fields they would be updated.
However, all these additional triggers and updates come at a performance cost. So, if you have a lot of attribute rules and/or feature-linked annotation classes you should think carefully about the impact this will have on your system.
Update without events in a named version
The most interesting situation is to look at how update subnetwork behaves when run in a named version without events. This is the default behavior of the system because it is the most performant. If you don’t like the behavior you see in these examples, remember that we introduced a new option to overcome these limitations discussed in the next section (Update with events in a named version).
To make sure we fully discuss this issue we will consider two separate examples where running update subnetwork in a version may produce unexpected results. It's worth noting that even though the tool may not produce the expected results in a version under all conditions, it will produce the correct result once the version has been posted to the default version and run update subnetwork in default.
Newly Created Features
Our first example builds on our previous example. Let’s assume we have a database with no subnetwork information populated, and before running update subnetwork in default we decide to create a new named version and add a new service in that version. Here is a graphic of our newly created features in our version before running update subnetwork:
Figure 4 New features created in a named version
After running update subnetwork without events in the named version, you will notice something curious. Only the features that were created in this version get their subnetwork name populated.
Figure 5 Update new features in a named version without events
When update subnetwork runs without events in a named version it can only update features that have been created or edited in the version. This is because if the feature has not yet been modified in the version it would require triggering a geodatabase event to insert the edit into the version.
Existing Features
For our next example, we will look at another practical example of where running update subnetwork without events in a named version may produce unexpected results. For this example, we will be looking at how update subnetwork responds to an edit that results in features changing from one subnetwork to another.
We start with two subnetworks (Network A and Network B) that are separated by a tie device (open switch, closed valve, etc). All the subnetworks have been updated in the default version, so all the attributes are properly populated. Note that because a tie device belongs to multiple subnetworks, the subnetwork name field is delimited with semicolons.
Figure 6 Two subnetworks in default
In this example, we will be changing the tie device between the subnetworks from device 3 to device 1. This happens quite frequently in the real world as circuits, pressure zones, etc. are reconfigured to account for long-term or even seasonal changes in customer demand. To do this we change the status of these two devices to indicate their new open/closed status so that Device 1 is now a tie device and Device 3 no longer acts as a barrier.
Figure 7 Updated tie device
We see these changes reflected in the diagram above because the tie device indicator moved from Device 3 to Device 1, the last modified date is updated, and we’ve updated the coloring on the features to visually indicate which subnetwork they belong to if you were to trace each subnetwork. The subnetwork names are still showing their old values because we haven’t run update subnetwork. Below you will see a diagram that shows all the attribute changes that will occur when update subnetwork is run under these conditions.
Figure 8 updated subnetwork in named version
As expected, we see that the subnetwork name field on both the devices that we edited in this version is updated. However, we also see that all the features that were connected to Network A but are now connected to Network B still have the old subnetwork name and operating area values. Because these features weren’t edited in this version update subnetwork can’t edit them without triggering edit events.
Both these examples highlight the limitations of updating subnetworks in named versions without events. For many customers, these limitations are acceptable because of the performance benefits of this edit mode, and because the data will appear correctly once the data has been posted to default and update subnetwork is run where everyone can see the results. However, other customers were willing to accept update subnetwork taking longer to run in order to meet certain business requirements. Because of this we introduced the ability to update subnetwork to edit with events as we will discuss in the next section.
Update with events in a named version
Let’s re-examine the two scenarios from above but look at how they behave when updating the subnetwork in a named version when the tier is configured to have an edit mode with events.
Newly Created Features
Below we can see the first example, where there is a mixture of existing and new features that need to be updated.
Figure 9 New features in a version
And the following is the result after running update subnetwork with events.
Figure 10 Update subnetwork with events in named version
As you can see all the features have the correct subnetwork name and operating area. The network will take longer to process because it is editing more features and because each feature will trigger additional edits for handling editor tracking, attribute rules, etc.
Existing Features
Next, let’s look at the second example where we reconfigured several subnetworks. Below is the data before running update subnetwork.
Figure 11 Features in a version before updating subnetwork
And below is the status of the features after running update subnetwork in a named version with events.
Figure 12 New features in a version
Once again, you can see that all the attributes on the feature have the correct values. It is worth stating that this will take longer than performing the same operation without events. Still, the amount of time it takes will be directly related to the number/complexity of attribute rules you have configured on your features along with the number of relationships you have with messaging enabled (including feature-linked annotation). It is worth measuring and considering these performance costs with the importance of visual inspection/attribute review of network information during your quality assurance process.
Configuration
Now that you’ve seen how these behaviors work, let’s look at how they are configured in a utility network. These options are configured using the Set Subnetwork Definition tool. Because this tool allows you to modify the configuration for a specific tier in your network this means that you can define different behaviors for each tier (e.g. System and Pressure). While it's nice to have the option to have different behaviors for each tier, most customers prefer to have all their tiers behave the same way to ensure consistent editing workflows for editors.
When setting the edit mode for your subnetwork definition there are two different fields, each with two different options. This means that there are four combinations of values you can configure for your edit modes:
- Without events in default, without events in named versions (default)
- Without events in default, with events in named versions
- With events in default, with events in named versions
- With events in default, without events in named versions
Before you spend too much time worrying about which of these four options you need to select you should know that the utility network foundation data models provided by Esri already have their edit modes configured. Each of these data models has a recommended set of configurations developed by industry subject matter experts, alongside their community, to have a configuration that will appeal to the broadest set of workflows for that industry.
Even though these configurations meet most customers’ needs, it is always a good idea to review these configurations within the context of your business requirements and any configuration/data model changes you’ve made to ensure that the typical configuration is still the most appropriate.
Best Practices
The most common question I get asked is what is the best practice for configuring your edit mode in the utility network? There is no single answer to this question that works for all customers. However, there are several criteria to consider that can help you decide which option is most appropriate for you. These considerations typically fall into three different categories: workflow, annotation, and attribute rules.
The first consideration is your versioned editing workflow. If your editing workflow requires you to perform quality assurance in named versions, and this process includes using tools or layers that rely on the attributes stored on features then you will want to set your edit mode for named versions to “With Events”. This ensures that the subnetwork fields are always populated correctly for all features in your version so they can be used for quality assurance. If your QA process can be performed entirely in default, or your QA process can use tracing instead of relying on feature attributes, then you can set your edit mode for named versions to “Without Events”.
The second consideration is whether you have feature-linked annotation. If you don’t have feature-linked annotation or annotation expressions that don’t include information from the subnetwork (subnetwork name, propagated values, etc), then either edit mode option is appropriate for you. Relationship classes with messaging turned on, like feature-linked annotation classes, do have a performance cost associated with editing that you will need to be careful to monitor. However, more important than that is if your feature-linked annotation includes information about the subnetwork, you have some decisions to make. Storing subnetwork information in annotation classes isn’t considered a best practice because of the static nature of annotation, the dynamic nature of subnetworks, and the performance cost of keeping the two in sync. You should consider replacing these feature-linked annotation features with labels. However, if this is a hard requirement then you will need to set your edit mode to “With Events” for both named versions and default to ensure that text in your annotation is updated when update subnetwork is run but be aware that this will impact the performance of update subnetwork.
The third thing to consider is the attribute rules you have defined on your utility network features. Any attribute rule configured to fire on update will be evaluated whenever that feature is updated, regardless of which field it is assigned to. This means that if you use the edit mode with events that all immediate calculation rules will fire during update subnetwork on any features that are updated. If this is a hard requirement, and you’re willing to accept the performance cost, you should review your attribute rules to ensure they are written to have early exit logic during update subnetwork to minimize this performance cost. If you have attribute rules that rely on responding to changes to subnetwork fields, you should know that this is not considered a best practice. However, if this is a hard requirement then you need to set your edit mode to “With Events” to ensure that the attribute rule is fired during update subnetwork.
With these considerations in mind, let’s review the four options and see where they are most appropriate.
Without events in default and without events in named versions. This option is the default behavior of the system. It gives you the most performance but has limitations around updating features in versions and feature-linked annotation.
Without events in default and with events in named versions. This option strikes a balance between performance and functionality. It gives you the best performance while updating subnetwork in default, and the best quality assurance experience in a named version.
With events in default and with events in named versions. This option provides the most functionality but also has the highest performance cost. If you implement this configuration, you should review any attribute rules configured to run when features are modified to ensure they are configured to provide an early exit during update subnetwork.
With events in default and without events in named versions. This is the least common configuration. It is for customers who have annotation or attribute rules they need to run in default but not in versions.
Conclusion
Now that you’ve read this article you should understand the pros/cons of the different editing modes used for subnetwork management, and you should be able to determine which modes are appropriate for your data model, editing workflows, and business requirements. If you want to learn more about subnetwork management or try out some hands-on tutorials, I recommend you check out the Manage Subnetworks with ArcGIS Utility Network learning series. If you want more details and deep dives on the subnetwork management capabilities of the utility network, I recommend you check out some of the other technical articles on the ArcGIS Utility Network Esri community page.