Our Insights

New Identify Map Tool for Cityworks Provides a Comprehensive Hierarchical View of Asset Information

November 14, 2018

By Udaya Maddumage, GIS Consultant, POWER Engineers 
Udaya Maddumage, POWER Engineers

POWER has a long history of implementing the Cityworks Asset Management System for numerous utility clients and enhancing the platform with customized plugins and tools. The Cityworks interface is entirely web based and web maps are consumed using the ArcGIS JavaScript API. While the core web map functionality provided by Cityworks is robust, meeting the business requirements of an organization sometimes requires customizing the core solution. An example is an enhanced Identify tool we recently developed for one of our clients.

Although Cityworks has a built-in Identify tool, the results are displayed in a standard attribute table and do not include related records. And, in the case where results are returned from many layers, a new tab in the results view is created for every layer. The exclusion of related records makes it difficult to support some use cases, and the multiple result tabs can lead to a cluttered display which makes it difficult to locate and interpret the results.

In many instances it is useful to show both primary and related records, displayed in a hierarchical view. To support these use cases for one of our clients, POWER developed an enhanced identify tool with the following features:

Figure 1. New POWER Tools Cityworks map toolbar

The enhanced Identify tool was developed against Cityworks 15.2. As part of this effort we designed a new toolbar (see Figure 1) to launch the Identify tool with the tool panel displaying to the right of the map view (see Figure 2). The Identify tool panel is instantiated from a configurable HTML template so it can be easily customized through configuration. When the tool is launched, JavaScript code is executed to create the fully configured instance of the Identify tool panel.

Figure 2. Identify tool panel – Identify results are pending and clicked coordinates are shown at the bottom of the tool panel.

The end user interacts with the tool by selecting one of the identify options and clicking the “identify” button. This changes the cursor to a guiding tooltip and clears any previous identify results. The user then clicks a single location on the map, causing the coordinates of that location to be displayed at the bottom of the identify tool panel and invoking the identify process.

The Identify tool calls the “IdentifyTask” ArcGIS JavaScript API function to invoke the server-side REST API which executes against the published map services. Since typical Cityworks implementations consume more than one map service and “IdentifyTask” can be executed against only a single map service at a time, multiple “IdentifyTask” API calls may be required depending on the identify option selected (i.e. one of top layer, visible layers or all layers). Since it is often desirable to exclude some map services from the identify results, such as base layers, the Identify tool configuration supports the inclusion and exclusion of map services.

Each of the “IdentifyTask” API calls required to support an Identify runs asynchronously and returns with its own identify results which are combined into a single results tree. Since the results only contain the primary feature attribute information, the tool then utilizes relationship information and metadata to query the related records. Note that the relationship metadata is loaded and cached at startup to avoid repetitive overhead. Related records are also requested from the server only when a user expands the node for the identified feature in the results tree view. These two optimizations improve the Identify tool performance to provide a fluid user experience.

Figure 3 shows an expanded results list.

Figure 3. Identify results showing an expanded related record.

Cityworks provides a robust toolbox of functionality that can satisfy the requirements of many organizations. However, where enhanced functionality is required, the Cityworks and Esri APIs can be leveraged to satisfy additional use cases and provide additional value to the business.

In future articles I will show additional ways to leverage the Esri JavaScript APIs to provide business value to your organization.

About the Author:

Udaya is a GIS consultant and a software developer in POWER’s Geospatial and Asset Management group with three years of geospatial experience and over six years of enterprise software development experience. His current focus is Cityworks plugin development, Utility Network web application development and system integration using middleware technologies. Udaya is an expert with ArcGIS APIs, ArcGIS Enterprise, Cityworks APIs and many web-based/cloud-based application development tools and technologies. As a technology enthusiast, he loves solving complex technical challenges with cutting edge technologies and contributing to the online geospatial community. If you have any questions or comments for Udaya, you can contact him at udaya.maddumage@powereng.com.