Enabling regional aggregation for geographical views

You can group locations into cities, group cities into states, and group states into countries. This grouping is called regional aggregation.

About this task

Regional aggregation has the following advantages:

The number of markers that are placed on the geographical maps is reduced.
You can view large geographical areas, for example, connectivity from data center to data center or from country to country.

The geographical view can be scoped by a network view, a defined set of geographic bounds, a specific set of devices, specific domains, or all devices across all domains. Events for devices and locations are also aggregated. The region displays the highest status level of any of the subregions.

Links between regions represent the aggregate links from region to region, region to location, or region to device.

You can configure the icons used for different levels of regional aggregation.

To enable regional aggregation for geographical views, complete the following steps.

Procedure

Ensure that the following fields in the ACMEGeoLocation (or equivalent) database table are correctly populated for all devices that you want to include in geographical views:
```
IP,ADDRESS,CITY,STATE,COUNTRY,LATITUDE,LONGITUDE
```
Restriction:
Ensure that each level in a hierarchy is unique. The following examples are incorrect because the city and state values are the same:
```
IP, ADDRESS, CITY, STATE, COUNTRY, LATITUDE, LONGITUDE
192.168.0.1,"113620 Redwood Gulch Rd, Cupertino, CA 95014, USA",PLAL,PLAL,US,37.15458,-122.05561
192.168.0.2,"113620 Redwood Gulch Rd, Cupertino, CA 95014, USA",CA,CA,US,37.15458,-122.05561
```
The following example is incorrect because the city and country values are the same.
```
IP, ADDRESS, CITY, STATE, COUNTRY, LATITUDE, LONGITUDE
Redwood Gulch Rd, Cupertino, CA 95014, USA",US,CA,US,37.15458,-122.05561
```
The following example is incorrect because the PLAL value was used previously as a city and is used here as a state. CA was used as a state and is used here as a country.
```
IP, ADDRESS, CITY, STATE, COUNTRY, LATITUDE, LONGITUDE
192.168.0.3,"113620 Redwood Gulch Rd, Cupertino, CA 95014, USA",Redwood,PLAL,CA,37.15458,-122.05561
```
The following example is correct, because the geographical hierarchy is properly ordered and contained.
```
IP, ADDRESS, CITY, STATE, COUNTRY, LATITUDE, LONGITUDE
192.168.0.1,"113620 Redwood Gulch Rd, Cupertino, CA 95014, USA",PLAL,CA,US,37.15458,-122.05561
```
Incorrect hierarchies are not included in the geographical views. The PopulateDNCIM_CustomGeography stitcher removes incorrect hierarchies from the topology and logs each occurrence in the ncp_disco logs with an error similar to the following:
```
Cyclic collection detected : Entity with entityId 123 should not be collected with collectingEntityId 8912
```
The default regional aggregation is address -> city -> state -> country. This logic is defined in the following stitcher: $NCHOME/precision/disco/stitchers/DNCIM/PopulateDNCIM_CustomGeography.stch

The character sequence -> is reserved for regional aggregation. Device and location names must not contain this sequence.
Open the GIS Device Map and click the Topology Rendering tab. Enable the Aggregate Locations to Regions option.

You can also enable or disable regional aggregation by using the URL parameters for geographical maps.
To configure the icons used for different levels of regional aggregation, edit the following properties in the $JazzSM_HOME/profile/installedApps/JazzSMNode01Cell/isc.ear/ncp_gis.war/resources/config.json file.
aggIconBasedOnLevel

Set this property to "true" to enable customization of icons per aggregation level. The default value of "false" disables this feature.

aggIconsForLevelType
Change the names of the icons in the list of levels. In the following example, levels 3 and 4 use the icon for a region, and levels 1 and 2 use the icon for a location.
```
        "aggIconsForLevelType": {
            "level1": "geolocation.png",
            "level2": "geolocation.png",
            "level3": "georegion.png",
            "level4": "georegion.png",
```

Results

Devices and locations can be grouped automatically to the highest regional hierarchy available in the geographical view. Double-click a region to drill into that region and show the next logical level of the hierarchy. Users can enable regional aggregation for their session by selecting Aggregate Locations to Regions > Enable on the Topology Rendering tab in the Map Configuration window.