Configure Business Locations (Site-Based Location Mapping)

Use the Location Mapping screen to manually configure location names to be different from its Site name in Microsoft Active Directory, or to manually assign a city, state, country, region, or coordinates for each location. In most cases, you do not need this screen for devices running Agent for End User Devices v9.x, as this data is automatically obtained from your Active Directory with zero configuration.

Define location names in Aternity

There are two modes of location mapping: either site-based (default) or legacy (never both). Use the legacy mode if you did not configure your Active Directory with Site names and their locations.

To... Do this...

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

Download and edit the mapping file which already contains the AD's Site in the Site Name column, and add your 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

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

Download and edit the 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

To (optionally) 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 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

To (optionally) assign a region to a location

Download and edit the 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

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 (or other configured attribute) to assign a location name, using the legacy location mapping functionality. For details, see legacy location mapping.

  • If neither approach worked, 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.

On virtual deployments (virtual applications like Citrix XenApp and virtual desktops like Citrix XenDesktop), Aternity always tries to report the location of the end user's front-end device by detecting its subnet.

If Aternity uses site-based location mapping, it reports the location as Off-site when the device is not connected to the Microsoft Active Directory. For legacy location mapping, if it cannot determine the location name, it reports it as Not Mapped. 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 someone 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 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.

Before you begin

Before configuring the site-based location mapping, verify the following:

  • Ensure you have one or more devices reporting data to Aternity, by downloading and installing the Agent for End User Devices version 9.x or later on those devices.

  • Ensure the organization uses Microsoft Active Directory, containing properly defined Site names.

    Automatic location mapping displays AD's Site name in the dashboards

    In site-based location mapping, the location's City, State and Country fields also come from the Active Directory (AD), if you added this information correctly in the Site's Properties > Location field.

    Location Mapping automatically retrieves the city, state and country fields from Site > Properties > Location

    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.

  • 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 Aternity
  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

    This CSV file, typically edited in Excel, contains the site name and other information gathered from the AD from monitored devices in your organization.


    Download and use Aternity's existing mapping file as the basis for your edits, to ensure the file format and column names are correct. The file is formatted in Unicode, so you can add non-English characters if needed.

    Example mapping file with locations mapped according to their site names in Microsoft Active Directory

    If you already defined a site's city, state and country in the AD's Site > Properties window, Aternity automatically adds the values from there.

    Furthermore, if Aternity recognizes those fields, it also automatically assigns geolocation coordinates.

    Field Description
    Site Name

    This column displays the name of the business location exactly as it appears in your Microsoft Active Directory under the Sites folder.


    Do not edit this field.


    Enter the name of the location as it should be displayed in the dashboards.

    By default, Aternity automatically adds (and displays) the AD Description field for this site, if it is defined, or alternatively it adds the AD's site name (the name under the Sites folder).


    (Mandatory if empty) Enter the country name for this site which matches exactly the format used in the MaxMind country database. This information is then used to display data per country in the dashboards.


    (Mandatory if empty) Enter the name of the state for this site, used for displaying data per state in the dashboards.


    (Mandatory if empty) Enter the name of the city for this site, used for displaying data per city in the dashboards.

    Location Latitude

    (Optional) Enter the latitude coordinate of this site in degrees North, between -90 and 90, for accurate placement on the dashboards' geographic maps. For example 51.377802.


    Use an online map to pinpoint a site's coordinates. If your spelling of the Country, State and City is recognized, Aternity automatically adds the city's geolocation coordinates.

    Location Longitude

    (Optional) Enter the longitude in degrees East, between -180 and 180, for accurate placement on the dashboards' geographic maps. For example -71.616.


    Use an online map to pinpoint a site's coordinates. If your spelling of the Country, State and City is recognized, Aternity automatically adds its geolocation coordinates.


    (Optional) Enter a label which groups together locations in the way you see fit. For example, a region can be as broad as APAC or as specific as NW England.

  4. Step 4 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. Aternity can support UTF-8 and UTF-16 formats, and you can separate the columns as either tab-separated or comma-separated format.

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

  5. Step 5 Upload the file to Aternity by selecting Upload New Location Mapping in the top bar.

    Navigate to the mapping file and upload. Aternity checks the file and integrates it.

    Upload and integrate the edited mapping file to Aternity
  6. Step 6 To verify the successful upload, go to any dashboard which details locations and verify that any new data is displayed with your new 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.