Configure Business Locations (Site-Based Location Mapping)

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

The Location Mapping determines business location name of a device based on the device's site name. Depending on a type of the device, the name for mapping its business location can be taken from the organizational Active Directory and/or from subnet ranges file. Active Directory applies to Windows physical devices and virtual app server sessions (like Citrix XenApp), whereas MAC, mobile devices and RDP sessions use the subnet ranges (Subnet to Site file).

By default, business location mapping is set to use Active Directory; so, you do not need to change anything in the Location Mapping screen. The Site field is automatically obtained from your Active Directory with zero configuration to automatically map business locations for you.

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

  • When your device sites are not properly set in Active Directory and you want to use subnet instead (subnet_to_site.csv file).

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

Configure business locations

There are two methods of site mapping: using Microsoft Active Directory and/or using subnet ranges via Subnet to Site option. See what you can do using Location Mapping screen and when to apply each method.

If you select the first method and use both Active Directory (AD) and the Subnet_to_Site.csv file, the location data in the CSV file takes precedence over AD because it overwrites the wrong data in AD.

The changes take effect when Agent connects and reports for the end user device next time after you uploaded the updated files. 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, for example.

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

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.

Note

If you select the first method and use both Active Directory (AD) and the Subnet_to_Site.csv file, the location data in the CSV file takes precedence over AD because it overwrites the wrong data in AD.

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.

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
Note

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

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

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

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

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

Note

If you used 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.

Note

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

Important

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.

Aternity reports the location as Off-site when the device is not connected to the Microsoft Active Directory or if Aternity cannot determine the location name.

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 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 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.

  • To use the subnet of a device for mapping, ensure you have Subnet to Site CSV file. Ask you IT team to provide the file with all subnet mask ranges and their respective locations as Site Name.

    Get Subnet_To_Site CSV file
  • Existing customers who used the Legacy Location Mapping, ensure to modify your old subnet_to_location.csv file to a new subnet_to_site.csv. All Site Names in both files must be identical. Ensure to copy them from an old used file to the new subnet_to_site.csv file. You can download the Subnet_to_Site.csv file from a new Location Mapping screen and use it as a template.

  • To use Active Directory (AD) for mapping, ensure the organization uses Microsoft Active Directory with properly defined Site names. Site names from Active Directory are displayed as Business Location names in Aternity dashboards.

    In location mapping, the location's City, State and Country fields 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
    Tip

    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.

Procedure

  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 Select the method for site mapping.
    • Use Active Directory – This option determines the location name for a Windows physical device and virtual app server sessions (like Citrix XenApp) as the Site name from your Microsoft Active Directory. Whereas MAC, mobile devices and RDP sessions will use subnets from your organization subnet range. Therefore, you must upload the Subnet to Site file.

    • Use Subnet to Site - This option applies to all devices and all devices will use the Site from the Subnet to Site file. You must upload the Subnet to Site file.

    Download the existing mapping file
  4. Step 4 To map mobile and MAC devices, and remote sessions, or to map all devices using the subnet range, upload the Subnet to Site file.

    Add to the file all subnet ranges and all site names.

    While editing the Subnet to Site file, add a new mapping entry on a new line. For example, enter each subnet range on a separate line. One location can contain many subnets, but a subnet can only belong to a single location.

    Tip

    You can obtain a list of subnets for monitored devices (physical only) reporting to Aternity using the Analyze > Device Inventory dashboard. Select Break by > Subnets. Alternatively, contact Aternity SaaS Administration for a CSV file containing the list of subnets which Aternity detected in your organization.

    Enter a range of IP addresses (IP v4 or v6) as a subnet mask, showing the start of the range, then a slash ('/'), then the number of bits in the address which acts as the mask.

    For example, for IP v4 addresses which are 32-bits (4 x 8 bits), specify a subnet mask for the first 24 bits of the address to cover everything except the last (8 bit) number. Hence for a range from 110.1.0.0 to 255, in the file specify the first 24 bits as 110.1.0.0/24.

    Enter a subnet range in a plain text mapping file (csv)

    In Excel, enter the subnet mask format in the first column and save as CSV.

    Enter the subnet ranges in Excel

    In a plain text editor, enter:

    110.99.1.0/24
    252.1.0.0/16
    253.1.0.0/16
    272.1.0.0/16
    110.99.0.0/16

    In the next column, enter the location name as you want it to appear in the dashboards. In Excel, enter the site name in the second column and save as CSV.

    Add a site name to each subnet range

    Alternatively, in a plain text file, add a tab or a comma (,) with no space before or after, and then the name of the site.

    For example, to assign subnet 110.99.1.0 to 255 to a site called Sydney Building, in a plain text editor insert a tab (or comma) then add the site name:

    110.99.1.0/24    Sydney Building
  5. Step 5 Upload Site to Location file to set geographic business location per site.

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

    Tip

    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
    Note

    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.

    Important

    Do not edit this field.

    Location

    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).

    Country

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

    State

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

    City

    (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.

    Tip

    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.

    Tip

    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.

    Region

    (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.

  6. Step 6 Save your configuration.
    Note

    Customers who previously used the Legacy Location Mapping, please note that clicking Save overwrites all legacy location mapping settings.

    Ensure you save the files 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.

    Note

    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.

  7. Step 7 (Optional) Update the Subnet to Site file, if necessary (for example, when adding new sites to the account).
    1. a Select Include unmapped values to ensure that the file you are going to download for further editing includes all the subnets reported by devices running the Agent for End User Devices, including those not yet mapped to a site name.
      Tip

      All unmapped values are included by default in the first download.

    2. b Select Download to download and save the existing Subnet to Site file which Aternity currently uses to assign subnets to site names.
    3. c Open the downloaded csv file in Microsoft Excel or in a plain text editor.
    4. d Update the entries.
    5. e Click in the field Select a file to upload, browse for the subnet_to_site.csv file you edited and upload it into Aternity.

    Once uploaded, the dashboards display new information with this location information.

  8. Step 8 (Optional) Update the Site to Location file, if necessary.
    1. a Download the existing Site to Location file which contains the geographical location for each location name and which Aternity uses to assign geographical locations.
    2. b Open the downloaded csv file in Microsoft Excel or in a plain text editor.
    3. c Update the entries.
    4. d Click in the field Select a file to upload, browse for the site_mapping.csv file you edited and upload it into Aternity.

      Once uploaded, the dashboards display new information with this location information.

      Note

      You may have warnings that there are unmapped sites. You can continue working, but the warnings will show as long as you have sites in the file that are not assigned to any business location. Even if you want to keep it that way, you can avoid having warnings by creating a dummy location for all unmapped sites. It is recommended to download the file and to enter all missing values in all rows and then reload the file to Aternity again.

      There are two types of warnings. In the Site to location area, the warning will show the number of sites without Country, city, state. Whereas, In the Subnet to Site area, the warning will show the number of unmapped subnets. You can include all unmapped values in the downloaded file by selecting the checkbox, so you can then fix the file.