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.
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 them_ExtraInfo->geographicLocation
field in theworkingEntities.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.
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
ncp_disco
logs with an error similar to
the
following:Cyclic collection detected : Entity with entityId 123 should not be collected with collectingEntityId 8912