Understanding How Location Mapping Works

Location Mapping determines business location name of a monitored device based on the device's site name. Depending on device type, the name for mapping its business location comes from the organizational Active Directory or from the subnet ranges file.

By default, business location mapping is set to use Active Directory (AD); so, you do not need to change anything in the Location Mapping screen. Aternity automatically adds (and displays) the AD's site name (the name under the Sites folder) with zero configuration from your side.

View the flow of business location values assignment:
Flowchart to understand the logic behind business location names (values)

To check if the Active Directory is properly configured, open Windows PowerShell and run [System.DirectoryServices.ActiveDirectory.ActiveDirectorySite]::GetComputerSite().Name.

The Location Mapping screen presents two methods of site mapping: using Microsoft Active Directory and/or using subnet ranges from the Subnet to Site file.

Use Site-based Location Mapping configuration screen in the following cases:
  • When you assign business location names to mobile devices, MAC devices and RDP sessions.

  • When the devices are not properly set in Active Directory and you want to use subnet ranges (Subnet_to_Site.csv file) for setting site names.

  • When you want to fix site names or to update geographic locations (country, city, state, region) as displayed in the dashboard (Site to Location mapping file (site_mapping.csv)).

With Site to Location file, you can configure site names to be different from those saved in the Active Directory, or manually assign a city, state, country, region, or coordinates for each location. With Subnet to Site file, you can configure site names using the subnet of the device.

Active Directory applies to Windows physical devices, virtual app server sessions (like Citrix XenApp), and Virtual Desktops; whereas MAC, mobile devices and RDP sessions use the subnet ranges (Subnet to Site file). MAC, mobile, and RDP sessions retrieve their Business Location names always only from the Subnet to Site CSV file and not from the Active Directory, regardless of the method you use.

Use Location Mapping configuration screen to edit site names and their geographical locations, in order to display business locations properly in the dashboards.

The changes take effect once you upload the new files and Agent starts reporting. In case you updated the names, but the Agent was not reporting that day, dashboards will still show the old names. Once Agent reports new data, you will see new names in the Devices Details dashboard.

Note that in the Advanced dashboards you might see both business location names. The old one as reported and saved in the database before you moved to the new Location Mapping strategy, and the new one as reported recently. Aternity does not override the old database.

In What Use Cases to Deploy Location Mapping

To... Do this...

To assign Business Locations name in the dashboards from a device subnet

Select the desired method. When opening the new Location Mapping screen for the first time, download the Subnet_to_Site.csv file and use it as a template. All unmapped values are included by default in the first download. Fill in the site names and upload the file. Learn more.

To show geographical locations in the dashboards while mapping the site from the subnet range
If using the subnet range for assigning site names (subnet_to_site.csv) and not Active Directory (site_mapping.csv), to assign geographical data (city, state, country, region and coordinates) to each location name, follow the below instructions:
  1. Download the Site to Location mapping file (site_mapping.csv).
  2. Open the downloaded file which contains the geographical location for each location name.
  3. Filter Country, City, and State fields to see all blank fields and fill in the missing values.
  4. Save the file and ensure that all sites and all necessary geographical location values are properly added to the file.
  5. Upload the Site to Location mapping file (site_mapping.csv) into Aternity using the Location Mapping screen.
Aternity retrieves the location name from ONE of the following sources and queries these sources in the order they are listed here:
  1. From the Active Directory if the device is connected to the Microsoft Active Directory (on site)
  2. From the Subnet_to_Site.csv file if the subnet is mapped to a valid location in this file and if the Subnet_to_Site.csv file IS used to get the Site name
  3. From the MaxMind Geolocation IP tool if the device is off site and the Subnet_to_Site.csv file is NOT used to get the Site name for the device

In case of error, see the troubleshooting step in the end of the article.

To customize a Location name in the dashboards to be different from the AD's Site name

Download and edit the Site to Location mapping file which already contains the AD's Site in the Site Name column, and add your business location name in the Location column.

For example, change UK1 to a proper display name like UK Sales.

Customize the display name of a location mapped from the AD's Site field

If location names are missing in the Location column, then Business Locations in the dashboards will present data from Site Description.

In case of error, see the troubleshooting guide.

To manually assign a Location's City, State and Country

Download and edit the Site to Location mapping file, and add or edit the location's City, State and Country in their columns.

You must manually enter the City, State and Country if the AD's Site > Properties > Location field is empty or if the names or its format is not recognized. By default, the format in the AD should be separated by a slash '/' character with no spaces on either side: country/state/city. For example, UK/England/London.

Manually define the city, state and country of a location with the mapping file

In case of error, see the troubleshooting guide.

(Optional) To assign a location's geographic coordinates, if the location is missing or incorrect in the dashboard maps, or if you have more than one location per city

Download and edit the Site to Location mapping file, and (optionally) add or edit the geolocation coordinates of each site in the Location Latitude and Location Longitude columns.

You can optionally add your own coordinates if the site's City, State and Country is either missing or not recognized, or if you have more than one site in the same city.

Customizing the coordinates of a location to display it on dashboard maps

In case of error, see the troubleshooting guide.

(Optional) To assign a region to a location

Download and edit the Site to Location mapping file and add the location's regional designation in the Region column.

By default, regions are undefined and displayed as Not Mapped. Use any regional groupings you see fit, like North America, or US Midwest or SE England, or any other name.

Define locations to display them in dashboards

For the location for a mobile device running a monitored app

Use Subnet_To_Site.csv file.

The system tries several methods in the following order to locate a mobile device running a monitored app:

  • First it checks if the app developer manually assigned the site name in iOS or Android using the Aternity Mobile SDK. If so, it uses the same site-based location mapping from the AD's Site to its Location, City, State, Country, and geolocation coordinates.

  • Next, if the app is connected to the enterprise WiFi, it uses the subnet to assign a location name.

  • If neither approach works, it reports the Location as Off-Site if it is on the mobile network, or Not Mapped if it is on a WiFi network, and then tries two more methods to ascertain location:

    • If the developer enabled location reporting in the Aternity Mobile SDK, and the user also allowed location reporting, it uses the device's coordinates to determine the State. Depending on the device settings, this may or may not include GPS coordinates.

    • If location reporting is disabled, it uses the location of the device's external IP (via HTTP) to report its State and Country only.

In case of error, see the troubleshooting guide.

To move from the Legacy Location Mapping to a new method that uses the subnet range for assigning site names

Learn more

Existing customers who are using the old Legacy Location Mapping and want to take a step forward, follow the below instructions:
  1. Get the old file you used to map your devices (Subnet_to_Location_Mapping.csv).
  2. Go to Location Mapping screen and download the two files: Subnet to Site and Site to Location files. Use them as your template.
  3. Fill in the data in the files that you downloaded at step 2 using your old location files (Note that starting now the new location identifier is Site name and not location name).
  4. Ensure that Site Name data is identical in both files: in Site to Location that uses Active Directory and in Subnet to Site which maps the subnet of the device to business location names.
  5. Upload the edited Subnet to Site and Site to Location files into Aternity using the Location Mapping screen.

Learn more


For location mapping using different device attributes, but not subnet (for example, host name or department), contact Aternity SaaS Administration.

Tips and Notes


The changes take effect when Agent connects and reports for the end user device next time after you uploaded the updated files. The changes in Location Mapping do not take effect retroactively. Business location names as they were reported by Agent before you moved to the new Location Mapping strategy, are kept in the database and will be displayed in dashboards depending on the timeframe view you selected.


If you are using the Legacy Location Mapping, you can continue working with an old configuration, unless you want to update geographical locations or move to the new site mapping method.


Aternity reports the business location as Off-site when the device is not connected to the Microsoft Active Directory.

(Windows only) When Aternity reports the location as Off-site, that will be the business location name in dashboards. This is to prevent false business locations when a user is connected via the same subnet as in the organization, but he/she is out of the office at the moment. A mobile device with no location name reports as Off-site if it is on 3G or 4G/LTE, or Not Mapped if it is on WiFi.


If a user connects to the office via a known VPN utility, Aternity displays the location name as the office's name and adds (VPN) to show it is a remote connection. The Agent queries Windows for a virtual network adapter with an active connection, the VPN suffix, and a common name in its description: AGN, Checkpoint, Cisco AnyConnect, Citrix VPN products, F5 Networks adapters, Juniper Networks, OpenVPN TAP, Palo Alto GlobalProtect, Pulse Secure, PureVPN, SonicWall, and VyprVPN.


Aternity checks the AD's Site > Properties > Location for information separated by a slash ('/'), with no space before or after the slash, using the format: country/state/city.

If Aternity recognizes these names, it automatically assigns geolocation coordinates, so it can display the location on a dashboard map.