Skip to main content
waffle.svg
Domo Knowledge Base

Flex Map Implementation Guide

Version 7

 

Flex Map 

Welcome to the Flex Map app! This guide will help you prepare and connect your data to the app. The Flex Map app is designed to help users map locations and territories to get geographical insights into their data, and discover relations between locations and important metrics. Follow the steps below to prepare your data for the app.

Data

This app requires a handful of datasets to be prepared to power four main parts of its functionality: mapping locations, displaying heatmap data, displaying data powered shapes on the map, and uploading custom KML or .shp files to display.

The datasets for each part of the app is broken up as such:

Locations Data (2 datasets)

  • Main locations dataset: rows of locations data mapped by latitude and longitude
  • Locations Search and Display: a configuration dataset for the locations

Heatmap Data (2 datasets)

  • Main Heatmap dataset: rows of data by region to display as numerical or categorical heatmaps
  • Heatmap Metric Mapping: a configuration dataset to map which columns from the heatmap data to use as metrics 

File Mapping Data (1 dataset)

  • File Mapping Metadata: a dataset with file names and ids of files that have been uploaded to the Domo Files API to use with the Flex Map

Data-powered shapes (2 datasets)

  • Flattened GeoJson Data: a dataset extracted from a GeoJson file that has been flattened so that each latitude/longitude coordinate pair from the file is represented on its own row in the dataset
  • GeoJson Metric mapping: a configuration dataset used to choose which fields from the GeoJson properties will be displayed when hovering over the shapes on the map

Follow the instructions below to prepare each of these datasets.

 

Location Data

The app requires the following fields for the locations dataset. 

The required fields are case sensitive, so make sure you add these columns to your data with the exact names.
 
 
Location ID Latitude Longitude Location Name Address SearchCache Any additional columns
  • Location ID: is a unique number/letter combination for a location.

  • Latitude: the latitude of a location.

  • Longitude: the longitude of a location.

  • Location Name: name of the location, should contain a one-to-one relation with the Location ID. You can have multiple rows for a single location and the app will group the data for the location together by the id and name.

  • Address: the address of the location.

  • SearchCache: a comma separated list of terms that you want to use. The app uses this to be able to find the location when searching using the main search bar in the app.

  • Additional Columns: add any additional columns for data and metrics for the locations you want to display with your mapped pins. Examples would be things like Region, any other address data, certain metrics, etc.

Location Search and Display Preferences

The following schema is required for the configuration dataset (the column headers for this configuration dataset are displayed below):

ColumnName SearchInclude DisplayInclude DisplayOrder Description TooltipInclude TooltipOrder DisplayType
  • ColumnName: the name of the column from your locations data that you'd like to display in either the search or display details portion for a given location.

  • SearchInclude: enter a 1 in the column if you'd like to include this column in the search options, leave blank otherwise.

  • DisplayInclude: enter a 1 in this column if you'd like to include this column in the display details for a location pin, leave blank otherwise.

  • DisplayOrder: enter sequential numbers in this column with the order you'd like to display in the columns in the location pin details portion. Ex. put a number 1 in the first column you'd like to see, then 2 for the second, etc.

  • Description: a description of the column. This column needs to have at least one value in order for the app to function.

  • TooltipInclude: enter a 1 in this column on any row if you'd like to include the data from that column in the tooltip when clicking on a mapped location.

  • TooltipOrder: enter sequential numbers in this column on any row where you have set TooltipInclude to 1 with the order you'd like to use for the fields to be displayed in the tooltip. 

  • DisplayType: this setting is applied to both the tooltip and the display panel. Enter the world 'image' if the field represented on that row contains image URLs. Enter 'URL' if the field represented on that row contains links to external sites; otherwise, leave this field blank. 

Heatmap Data

This data is used to map metrics to regions for the heatmaps in the Flex Map app. The most important columns from this data are the RegionCode and RegionType columns. The app uses statistical regions to create the heatmaps, so you'll need to map your metric data to the region types that the app requires. For example, if you are in the USA and you have metric-based data based on zipcodes, you'll need to map your zipcodes to CBSA codes for the map to use your data. You can easily find the required data to map your data to these codes online. The app supports the following regions codes/types: CBSA for the USA, CMA for Canada, SA3 for Australia, and NUTS 2 for Europe. Reach out to your Domo Admin if you need regions beyond what is currently available. 

Here is the schema for the heatmap data. The three required fields are case sensitive, so make sure you add them to your data exactly as seen below:

RegionCode RegionName RegionType Your metric columns... Addt'l. metadata columns...
  • RegionCode: this is the code for the area that matches what you have listed in the RegionType column. For example, your region code on a row might be 30030, then your region type would be 'CBSA'. 
  • RegionName: the name of the region, if applicable. This column is optional.
  • RegionType: contains one of the following values: CBSA, CMA, NUTS 2, or SA3. It should match the region code type you are using in the RegionCode column.
  • Your metric columns: any columns with the metrics that you'd like to use to build your heatmaps. You may add as many of these metrics as you would like, but you will need at least one in order to use the heatmaps.
  • Additional metadata columns: Any columns with metadata on the regions that you'd like to map, to be used as Domo page filters to filter down the data in the app. These columns are optional. 

Heatmap Metric Mapping

This dataset is used to choose the columns from your heatmap dataset that you'd like to use in the app and rename the columns for the app display, if needed.

Here is the schema for the mapping dataset: 

ColumnName Label
  • ColumnName: list the names of the metric column from your heatmap dataset that you'd like to use as a heatmap metric in the app.
  • Label: enter what you would like the metric's display name to be in this column. For example, if your column name is 'populationAverage' then you might display it as 'Population Average'. 

Dataset-Powered Shapes dataset:

This dataset is a flattened import of a GeoJSON file. The data must be flattened so that each latitude/longitude coordinate pair from the file for each shape is represented on its own row in the dataset. See the bottom of this section for the suggested method of importing a GeoJSON file into Domo.

The purpose of this feature is to bring in a GeoJSON file from a Domo dataset, that may be frequently updated, so that the map always shows the latest shapes and related data on the map; these are updated in real time. This functionality is also optional. If you do not wish to use this feature, prepare the two datasets below with just the column headers and leave the rest of the dataset blank.

The required schema for this dataset is as follows. The required fields are case sensitive, so make sure you add these columns to your data with the exact names as seen below:

Geo Id Geo Name Latitude Longitude Type Geometry Type (Any addt'l. properties you want to use from GeoJSON)
  • Geo Id: an Id of the shape. Must be distinct to the shape, can be created in a dataflow or pulled from one of the properties in the GeoJSON. 
  • Geo Name: a name for the shape. Must be distinct to the shape, can be created in a dataflow or pulled from one of the properties in the GeoJSON.
  • Latitude: the latitude from a coordinate pair on the shape. Pulled from the geometry -> coordinates property of the GeoJSON feature. 
  • Longitude: The longitude from a coordinate pair on the shape. Pulled from the geometry -> coordinates property of the GeoJSON feature. 
  • Type: from the type property, likely the value will be 'Feature'. 
  • Geometry Type: from the geometry -> type property in your GeoJSON. Two values are compatible here, either 'Polygon' or 'LineString' for drawing polygons or lines on the maps respectively. 
  • Additional properties: include any additional columns that you'd like to use to display information or metrics when hovering over these shapes on the map. 

Note on preparing your GeoJSON data: There is a connector available that can be used to import and flatten your GeoJSON data. GeoJSON can be imported using an HTTP request, from an SFTP connection or locally from your computer. Look for the 'JSON no code' beta connector when creating a new dataset in the Domo data center and follow these steps:

1. The connector asks for a username and password if using SFTP or basic connection. Enter these or leave them blank if you are doing a local upload and then click 'Connect'. 

2. Under 'Data Selection' choose your connection type and enter the required information, including the URL to your file if using SFTP or HTTP request. If choosing local upload, choose the file you'd like to upload.

3. For the 'Parsing' section, after it finishes loading, click the dropdown arrow on the right to open the parsing interface:

  • Click your features column, then select the 'Unnest column as root' option at the top.
  • Click your properties column and select 'Flatten Objects as columns'.
  • Click your geometry column and select 'Flatten Objects as columns'.
  • Find your geometry_coordinates column. If your shapes are polygons, you will need to select this column then 'Expand array as columns/', then select the click column and select 'Expand array as rows'. If your shapes are lines, you will only need to select 'Expand array as rows'.
  • Scroll to the bottom and click 'Next'.

4. Set whatever schedule frequency you'd like in the 'schedule' section, then name and save your dataset.

5. Dataflow this resulting dataset to get it into the schema as explain above for this dataset and it should now be ready to use. 

GeoJSON Metric Mapping

This dataset indicates which columns from the previous dataset will be used to populate the tooltip that appears when one of the shapes is hovered-over in the app.

The schema is as follows:

ColumnName Label Aggregation
  • ColumnName: the name of the column from the previous dataset that you'd like to use to display in the shape's hover tooltip.
  • Label: enter the value you'd like to use as the label for the column that was entered under ColumnName
  • Aggregation: this can either be blank, 'sum', or 'average'. Use this if you need to aggregate the column of a numerical column you are using in your data. Because of the nature of importing GeoJSON files, in most cases you will likely leave these fields blank. 

File Mapping Dataset:

The final dataset that needs to be prepared is the file mapping dataset. The purpose of this dataset is to point the app to KML or .shp files that have been uploaded to the Domo Files API so that the app can bring in and use these as custom territories.

The required fields are as follows, only File Name and File Id need values for this feature to work:

File Name File Id Folder Name Folder Type Last Run Domo Data File Id
  • File Name: the name of the file
  • File Id: the Domo Files API id indicating if the location of the file that has been uploaded
  • Folder Name: (optional, can be left blank) if uploaded using the Automated File Upload utility app, the folder name.
  • Folder Type: (optional, can be left blank) if uploaded using the Automated File Upload utility app, the folder type.
  • Last Run: (optional, can be left blank) the dateTime the file was last uploaded. 
  • Domo Data File Id: (optional, can be left blank) if uploaded using the Automated File Upload utility app, the Domo data file id.
A free utility app is available if the custom file functionality is going to be used called the Automated File Upload app. This app can be used to automatically upload files from either AWS or Google Drive to the Domo Files API on a recurring and automated basis, and then produce the exact dataset that the Flex Map app can then use. Reach out to your Domo contact if you need access to the app.
 
 

As soon as these seven datasets are prepared, you should be ready to connect your data to the app.

Admin and View-only Users:

This app supports different user levels including admin, standard, and view-only users. Have an admin in your Domo instance navigate to the admin portal within Domo and create two new Domo groups. Name the first group '_FlexMap_Admins' and name the second group '_FlexMap_ViewOnly'. Users that are added to the admin group will be able to share items that they've created in the app with members of the Domo group, and use buttons at the bottom of the app to set a default map and a default center. Standard users are those that aren't added to either of these groups; they will get the standard funcitionality in the app, be able to create their own items, be able to see things that the Admin users share with them, but won't be able to share items or set defaults. View-only users cannot create anything in the app, they can only view items that admin users have shared with them.

Wiring Your Data to the App:

After the data is ready for the app, you can now deploy the app from the Appstore and connect your data. If you have access to the app asset, deploy the asset from the Asset Library to the desired page in Domo. If the app has been deployed for you with sample data, navigate to the app, click on the wrench icon in the top right corner of the app, and select 'Edit Card'. 

On the 'Edit Card' screen, that you will get to from one of the two methods explained above, you can re-name the app at the top of the screen. Scroll down below the app and you should see a series of tabs that represent each of the datasets the app needs to run. The first tab will say SCHEMA, click this tab and select the dataset you prepared as the search and display preferences. Check the column dropdowns you see after selecting the dataset and re-map any columns the the correct columns, if needed. Next, click the LOCATIONS tab and choose your location dataset. Next, click the HEATMAP tab and select the heatmap dataset that you prepared. Last, click the METRICLABELS tab and choose the heatmap metric mapping dataset that you've prepared. Click GEOJSON and upload the GeoJSON dataset, then click GEOJSONMAPPING and upload the GeoJSON metric mapping dataset you've prepared, making sure that the columns are mapped correctly. Finally, click the FILEMAPPING tab and upload the file mapping dataset you've prepared, making sure to map to the correct columns. Click 'save and finish' at the top of the page and your app should now be ready to go!

Using the App

Uset the button at the top left corner of the app to open up the app's menu. In this menu, you can choose from a handful of options to map our your data. Searches allows you to search for a subset of your locations data to map as pins on your map. Territories allows you to use predefined options to create territories on the map, as well as freehand- draw new custom territories to display. Here, admin users are also able to find the custom territories button where you can configure which of your mapped files you'd like to use in the app.

When you have any combination of pins and territories displayed on the map, you can click the 'Save Map' button from the bottom right of the app to save your view as a saved map. You can navigate back to your saved maps by using the Saved Maps tab in the app menu. You can also favorite saved maps that will appear in the 'Favorites' tab in the app as well. Using the heatmap tab will allow you to choose a heatmap metric to display on the map. Clicking on dynamic shapes will allow you to see the GeoJSON shapes you've uploaded to the app. 

Enjoy experiencing new geographical insights from your data!