Enriching discovery with geographical data

To display geographical maps, you must enrich the network topology with geographical data.

About this task

Enriching the network topology with geographical data requires several steps:

Retrieve the geographical data from an external database or system.
Add the geographic data to the topology.
Create a collection in Network Manager that collects devices to a geographic location.
Optionally, create collections to represent hierarchies of geographical regions.

Note: Customizing discovery is an advanced procedure. You must be familiar with the discovery data flow, general database administration, and the stitcher language.

To retrieve the geographical data, two options are to add it to the SysLocation field in the device record by using a script, or to export it from a database to a .csv file.

To create collections and add geographical data to the topology, you must use the stitcher language. Two example methods are supplied with the product: the AddGeoLocationData and PopulateDNCIM_CustomGeography stitchers.

The PostLayerProcessing stitcher can be updated to call the AddGeoLocationData stitcher. The AddGeoLocationData stitcher extracts the location description, longitude, and latitude from the SysLocation field during a network discovery. The location data populates the m_ExtraInfo->geographicLocation field in the workingEntities.finalEntity database table to build the geographic location collection.
The InferDNCIMObjects stitcher can be updated to call a custom stitcher such as the supplied example stitcher ACMEDeviceLocationEnrich. The ACMEDeviceLocationEnrich stitcher resolves IP addresses to geographical locations to create a hierarchy of Address -> City -> State -> Country, and calls the PopulateDNCIM_CustomGeography stitcher. The PopulateDNCIM_CustomGeography stitcher builds a hierarchy of geographic regions-> geographic locations-> devices, by resolving the geographical data from an external database.

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