Configure Business Locations (Site-Based Location Mapping)

Location mapping determines the location name (site, office or campus) of a monitored device as it is displayed in the dashboards with minimum or even zero configuration from your Active Directory, including finding its city, state, country, and map coordinates.

Zero configuration location mapping is available only for devices running Aternity Agent v9.x.

By default, the dashboard's Location name is the Site name from your Microsoft Active Directory.

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

The location's City, State and Country fields are also automatically taken from the Active Directory (AD), if you set up 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

The system 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 the system recognizes these names, it automatically assigns geolocation coordinates, so it can display the location on a dashboard map.

You can manually configure locations in the Location Mapping screen. Download the mapping file to change the location name to be different from the AD's Site name, or manually assign a city, state, country, region, or coordinates for each location.

For example, use the Location Mapping screen to customize a Location name to be different from the AD's Site name.

Use the Location Mapping screen to download and edit the mapping file to:

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

To manually assign a location for a mobile device running a monitored app

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

  • First it checks if the developer of the monitored app manually assigned the site name using the Aternity Mobile SDK. If so, the system would use the same method to map the AD's Site name with its Location name, City, State and Country, and geolocation coordinates. For details, see Set the Location's Site Name with the Aternity iOS Mobile SDK (setSite and setOffSite) and Set the Location's Site Name with the Aternity Android SDK (setSite).

  • If the monitored app does not manually set the site name, the system checks if the app is connected to your corporate wireless network (wi-fi), and if so, it would use the subnet of that connection to assign a location name, using the legacy location mapping functionality. For more information, see Configure Business Locations with a Device Attribute (Legacy Location Mapping).

  • If neither of these approaches was successful, the system reports the device's Location name as Off-Site. It then tries two more methods to ascertain location:

    • If the developer enabled location reporting in the Aternity Mobile SDK, and if the user allowed location reporting for this device, it uses the device's coordinates to determine the City, State and Country.

      Depending on the device settings, this may or may not include GPS coordinates.

    • If the app or user disabled location reporting, the system would resort to resolving the location of the external IP (via HTTP) of the device to report its State and Country only.

Tip

A desktop or laptop's location is Off Site when it is not connected to your Microsoft Active Directory.

If someone connects to the office via VPN, the system displays the location name as the office's name and adds (VPN) in parentheses as an indication that this is a remote connection.

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 Aternity Agent version 9.x on those devices.

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

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

Procedure

  1. Step 1 Open a browser and log 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

    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 the system'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, the system automatically adds the values from there.

    Furthermore, if those fields are recognized by the system, 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, the system 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 MaxMind country database. 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, the system 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, the system 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.

    If you do not add this data, the region appears in dashboards as Not Mapped.

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

    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.

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