Upgrade Location Mapping From Legacy to Site-Based

This article describes how to upgrade to the newer site-based method of location mapping for customers who upgraded their Aternity from an earlier version to 9.x. With legacy Agents (8.x or 7.x), you had to manually map locations to a subnet or other device attribute. But now with the upgraded Agent 9.x, Aternity determines locations automatically from the list of Sites in your Active Directory.

Location mapping determines the location name (site, office or campus) of a monitored device as it is displayed in the dashboards. The system supports two ways to configure location mapping:

  • Site-based method (requires Aternity Agent 9.x)

    Use the site-based method (recommended) with Aternity Agent 9.x or later to automatically map location names from the Site in your Microsoft Active Directory (AD) in a quick one-step mapping. It uses your AD's location names, so if your company changes its structure or topology in the AD, the locations automatically update with it.

    For more information, see the quick one-step mapping.

    Automatic location mapping displays the Active Directory's Site name in the dashboards
  • Legacy attribute-based method (for older Agent versions)

    The legacy method for location mapping assigns a location from a device attribute, like its subnet, which changes whenever the device connects from a different location. This method requires two separate mappings: first from an attribute (like a subnet) to a location name, then a separate mapping from each location name to its city, state, country, region and coordinates.

    For more information, see two separate mappings.


If you performed a fresh install of Aternity 9.x, you do not need to perform this procedure, as Aternity already supports site-based location mapping for devices running Agent 9.x.

But if you upgraded to Aternity 9.x, by default the system continues to use the legacy method of location mapping, until you switch on the new site-based mapping. After the switch, devices running Agent 9.x would use the newer site-based method, while devices with legacy versions of the Agent, continue mapping locations with the previous attribute-based method.

You can upgrade from the legacy to the site-based location mapping in three steps.

Upgrading to site-based location mapping in three easy steps
  1. Open the site-based location mapping file, to see the list of sites.

  2. Fill any gaps in the file. For locations which were already defined in the legacy mapping, copy that location data from the legacy to the site-based mapping file.

  3. Enable site-based location mapping for devices with Agent 9.x.

As you gradually upgrade devices to the newer Agent, the upgraded devices automatically switch to the site-based method.

Before you begin

Before moving from the legacy to the new site-based location mapping:

  • Upgrade at least a one device in each location to Agent 9.x, so the system can automatically discover the exact list of Site names in the AD.

  • Understand that in the new site-based location mapping, each Site in the AD represents a business location in the system, so the locations always reflect your current network topology. This may be different from your legacy mapping, where you could group several subnets from different sites to a single business location.

  • Verify the access rights and privileges for your user includes Edit Configuration privileges.


  1. Step 1 Open a browser and sign in to Aternity.
  2. Step 2 Select the Gear Icon > Location Mapping.
    Define location names in the system
  3. Step 3 Download the mapping file containing existing location information, by selecting Download Current Location Mapping in the top bar of the screen.
    Download the existing mapping file
  4. Step 4 Open the site-based mapping file in a CSV reader, like Microsoft Excel.

    The mapping file is like the legacy location mapping file, but it has an extra column called Site Name which corresponds to the Active Directory's (AD) Site field.

    The file lists the sites where Agent 9.x has reported data. So if Agent 9.x devices are only in one site, it will only list that site.


    We recommend that you start with a complete list of sites, by upgrading at least one device in each location to Agent 9.x. This ensures that the mapping file lists all the sites exactly as written in the AD, with no typos or missing entries.

    Initial mapping file with sites as defined in the AD which have devices running Agent 9.x
  5. Step 5 Edit the mapping file to add the location information for each site.

    For sites which correspond to a legacy location, you can copy the information for each site from the previous legacy mapping file into the new site-based mapping file.

    1. a Select the Gear Icon > Settings > Location > Location Mapping (Legacy).
      Access the legacy location mapping settings
    2. b Download the system's currently used legacy location mapping file, which maps location names to their physical locations (country, state, city, region, coordinates).

      Select Download Mapping to save the existing file locally, to reuse its data.

      Download the existing location mapping file
    3. c Assign the same location names as you had in the legacy file beforehand, to ensure that devices with Agent 9.x report the same location as earlier versions.

      Copy the values in the Location column from the legacy to the new mapping file.

      Consistent location names ensure you have continuous reporting of the same locations for both upgraded and non-upgraded Agents.

      Use the same location names as before to ensure consistency during phased upgrades

      Alternatively, you have an opportunity now to rearrange the locations in Aternity to reflect the current structure of the organization. If so, there would be a discrepancy between the location names while you have older and newer Agents reporting at the same time.

      Also note that in previous versions, you may have had several subnets in a single site. These will now be grouped as a single location in the new site-based mapping system.

    4. d Copy the city, state, country, region, and coordinates from the legacy file to the new site-based mapping file.
      Copy the site information from the legacy location mapping file to the new site-based mapping

      If you are entering new locations, different from the legacy mapping file, see Configure Business Locations (Site-Based Location Mapping) for details on how to fill these fields.

    5. e Save the file with your changes.

      Ensure you save the file in the same format (CSV, Unicode). For example, if you edited the CSV in Microsoft Excel, select Yes to save the file in the same format.

      When saving, maintain the same format (CSV and Unicode)

      We recommend to maintain the same file format for simplicity. The system can support UTF-8 and UTF-16 formats, and the columns can be separated as either tab-separated or comma-separated format.

      The system does not restrict the file extension, but we recommend maintaining the extension filename.csv for easy editing.

    6. f Go back to the site-based mapping page.

      Select the Gear Icon > Location Mapping.

    7. g Upload the file to the system by selecting Upload New Location Mapping in the top bar.

      Navigate to the mapping file and upload. The system checks the file and integrates it into the system.

      Upload and integrate the edited mapping file to the system
  6. Step 6 To enable the new site-based location mapping on Agent 9.x devices:

    Select the Gear Icon > Settings > Location > Location Mapping to view the legacy location mapping screen.

    Select Switch to new site-based location mapping for Agents (9.x) to move any devices running Aternity Agent 9.x to the newer site-based method of location mapping.


    If you see a link for Apply legacy location mapping also to new Agents (9.x), DO NOT click this link unless you need to downgrade back to the legacy method for all Agents. This link indicates the system is already using the new site-based location mapping for new Agents.

    Move all devices running Agent 9.x to the site-based location mapping method
  7. Step 7 Upgrade the Agent running on devices throughout the organization (in phases if you wish).

    Those using Agent 9.x would automatically switch to the newer site-based mapping. Those not yet updated would continue using the legacy location mapping.

  8. Step 8 To verify a successful upgrade, go to a dashboard which shows locations for devices running Agent 9.x, and verify that any new data is displayed with the site-based location names.

    Only new data displays with your new location data. Therefore we recommend reducing the timeframe of the dashboard to view only new data gathered since you made the change, to verify the location names and coordinates are properly displayed.