Editing Utility Networks | ArcGIS Maps SDK for JavaScript

Editing Features

Editing features is simple and can be done via the FeatureService.applyEdits(). Editing Utility Network features will generate dirty areas. To learn more about editing features using FeatureService.applyEdits(). Please visit the Feature Service guide doc to learn more about editing features.

Introduction to Associations

Editing Associations are performed with the applyEdits () method on the Feature Service class. Editing Associations has been simplified as of 4.29 with the introduction of the generateAddAssociation and generateDeleteAssociations on the UtilityNetwork class.

How to Edit Associations

The example below demonstrates how to edit Associations.

// Instantiating a UtilityNetwork using layerUrl
const utilityNetwork = new UtilityNetwork({
  layerUrl: "https://hostName.com/server/rest/services/Test/FeatureServer/17",
});
await utilityNetwork.load();

const association = new Association({
  globalId: "{88355CB3-B011-4715-BB90-047B8C7ABF48}",
  fromNetworkElement: new NetworkElement({
    globalId: "{09B7A0F9-811D-4CCF-95A9-D1995D44C631}",
    networkSourceId: 8,
    terminalId: 1,
    assetGroupCode: 1,
    assetTypeCode: 1,
  }),
  toNetworkElement: new NetworkElement({
    globalId: "{86DD4700-4D1B-4872-93CD-68783F7996B6}",
    networkSourceId: 10,
    terminalId: 1,
    assetGroupCode: 2,
    assetTypeCode: 2,
  }),
  associationType: "attachment",
});

const canAdd = await utilityNetwork.canAddAssociation(association); // Will check rules table to verify if given associations are valid
const generatedAddAssociation = await utilityNetwork.generateAddAssociations([association]);
const generatedDeleteAssociation = await utilityNetwork.generateDeleteAssociations([association]);

if (association) {
  // Adding new Association
  await featureService.applyEdits([generatedAddAssociation], {
    gdbVersion: "name.demo",
    globalIdUsed: false,
    honorSequenceOfEdits: false,
    usePreviousEditMoment: false,
    returnServiceEditsInSourceSR: false,
  });
}

await featureService.applyEdits([generatedDeleteAssociation], {
  gdbVersion: "name.demo",
  globalIdUsed: true, // Must be true when deleting Associations via generateDeleteAssociations
  honorSequenceOfEdits: false,
  usePreviousEditMoment: false,
  returnServiceEditsInSourceSR: false,
});

Before calling generateAddAssociations the canAddAssociation routine can validate whether the given Associations are valid.

Introduction to Validating Network Topology

Validating the network topology for a utility network maintains consistency between feature editing space and network topology space. Validating a network topology may include all or a subset of the dirty areas present in the network. Validation of network topology is supported synchronously and asynchronously. Validate should be done after edits are made, and before network tracing. In editing workflows for a utility network, the validation of the network topology is also treated as an edit operation. As portions of the network are edited or modified, they become out of date in the network topology and are marked with dirty areas. Dirty areas serve as an indicator that the content you see on the map does not match what is stored in the network topology. It is important to keep the network topology updated for analytic events; this is done by validating the network topology.

When to Validate ?

You should validate network topology regularly to ensure that your network is functioning properly. Whenever an edit is made on a Utility Network a dirty area will form. Validating should be done after editing, and before network tracing to ensure network consistency. A dirty area represents a portion of the network that has been modified or updated but has not yet been synchronized with the rest of the network. Validating a network’s topology will remove dirty areas and update the network topology so that it matches the values in the features. For dirty areas to be visible, the dirty area layer must be added to the map. The URL for this layer can be obtained from UtilityNetwork.networkSystemLayers.dirtyAreasTableUrl.

Validate Network Topology Using the Utility Network Class

Validating Topology using the Utility Network class may be done either synchronously or asynchronously. Synchronous is faster, although it is also subject to timeouts if performed on a very large number of features. The asynchronous option is slower, but it won’t time out. Therefore when validating a large number of features async is advised. For example, validating network topology synchronously:

// Instantiating a UtilityNetwork using layerUrl
const utilityNetwork = new UtilityNetwork({
  layerUrl: "https://hostName.com/server/rest/services/Test/FeatureServer/17",
});
await utilityNetwork.load();
const extent = new Extent({
  xmin: 470789.0888,
  ymin: 3597733.2051,
  xmax: 531454.2759999996,
  ymax: 3639864.802100001,
  spatialReference: { wkid: 26911, latestWkid: 26911 },
});

await utilityNetwork.validateTopology({ validateArea: extent });

For example, validating network topology asynchronously

// Instantiating a UtilityNetwork using layerUrl
const utilityNetwork = new UtilityNetwork({
  layerUrl: "https://hostName.com/server/rest/services/Test/FeatureServer/17",
});
await utilityNetwork.load();

const extent = new Extent({
  xmin: 470789.0888,
  ymin: 3597733.2051,
  xmax: 531454.2759999996,
  ymax: 3639864.802100001,
  spatialReference: { wkid: 26911, latestWkid: 26911 },
});

await utilityNetwork.submitTopologyJob({ validateArea: extent });

Validate Network Topology Using the Validate Network Topology Component

If you want your web app to include a user interface for validating a network topology, the JavaScript API provides a component that can be easily added to your application. Simply configure the component and it’s ready to go. For example:

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>UtilityNetworks Guide: Load a utility network</title>

    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>

    <style>
      html,
      body,
      #viewDiv {
        height: 100%;
        margin: 0;
      }
    </style>
  </head>

  <body>
    <arcgis-map>
      <arcgis-utility-network-validate-topology slot="top-right" />
    </arcgis-map>

    <script type="module">
      const [WebMap, config, FeatureLayer] = await $arcgis.import([
        "@arcgis/core/WebMap.js",
        "@arcgis/core/config.js",
        "@arcgis/core/layers/FeatureLayer.js",
      ]);

      // Set the hostname to the portal instance
      config.portalUrl = "https://myHostName.domain.com/arcgis";

      const webMap = new WebMap({
        portalItem: {
          id: "webMapId",
        },
      });

      const viewElement = document.querySelector("arcgis-map");

      // Load the WebMap
      await webMap.load();
      viewElement.map = webMap;

      // How to use the UtilityNetworkValidateTopology component
      viewElement.addEventListener("arcgisViewReadyChange", async () => {
        const utilityNetwork = viewElement.map.utilityNetworks.getItemAt(0);
        await utilityNetwork.load();

        // This is only required if the webmap does not contain the dirty area layer
        const dirtyArea = new FeatureLayer({
          url: utilityNetwork.networkSystemLayers.dirtyAreasLayerUrl,
        });

        await dirtyArea.load();
        viewElement.map.add(dirtyArea);

        // Initialize the UtilityNetworkValidateTopology component
        const arcgisUtilityNetworkValidateTopology = document.querySelector("arcgis-utility-network-validate-topology");

        arcgisUtilityNetworkValidateTopology.utilityNetwork = utilityNetwork;

        arcgisUtilityNetworkValidateTopology.componentOnReady();

        console.log("arcgis-utility-network-validate-topology is ready to go!");
      });
    </script>
  </body>
</html>