Custom Map Widget

Note: (Sept 18, 2017) Added support for filtering on shapes.

Introduction

This article explains how to embed custom map visualizations in Sisense.

Purpose/Benefits

Sisense has some native mapping functionality, but does not allow for importing custom maps. This plugin allows you to view data in whatever map you like. See the references for more information on GeoJSON, Leaflet, and Mapbox.

Custom shapes (Counties) overlayed on a base map:

Custom shapes (Chinese Provinces) with no base map:

Steps

The following steps will walk through the process of adding the new chart type and creating a sample map.

Step 1 - Add the Plugin

Download the customMapWidget.zip attachment and unzip the contents into your C:\Program Files\Sisense\PrismWeb\plugins\ folder. If you are using version 7.2 and higher unzip the contents into your C:\Program Files\Sisense\app\plugins\ folder. If the plugins folder doesn't exist, just create it. After those files have been unzipped there, you may also have to restart the web server. Now, when you create a new widget the Custom Map widget should show up in the list of options

Step 2 - Prepare GeoJSON for your Custom Map

This plugin uses GeoJSON files to overlay data as shapes on a map. More information on GeoJSON can be found here, but the general concept is that each file defines a JavaScript object that has a type of FeatureCollection and a list of features. There are different types of features, but the most common type is a polygon. Each feature represents a shape to display on the map and contains properties and geometry. Properties describe the attributes of the entire shape, while geometry is a list of points. Each point is a latitude/longitude combination, and the mapping function displays all points of the shape on the map and then draws a line to connect them. Below is an example of the format for a GeoJSON file.

{
    "type": "FeatureCollection",
    "features": [
    	{
            "type": "Feature",
    	     "properties": {
                "ID": "1",
                "Name": "MyShape1"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [-86.411172, 32.409937],
                        [-86.496774, 32.344437]
                    ]
                ]
            }
        }
    ]
}

This plugin comes with 3 GeoJSON files included, but you can add in more if you want to show a different set of shapes. Some government agencies provide geo data for free use, and there are several 3rd party sites that provide free geo data as well. If you want to add in your own geo data, copy the file to customMapWidget/geojson/ folder.

Step 3 - Configure the plugin

Open the config.js file and update the setting object's properties.

urlTemplate - When using mapbox as the tiling server, you will need to provide a tile url
mapboxKey - When using mapbox as the tiling server, you will need to provide an api key
mapboxId - When using mapbox as the tiling server, you will need to provide a map type to use
shapeSeparatorColor - color used for the outlines of the shapes
shapeHighlightColor - color used to differentiate the highlighted shape

Next update the list of Map options. This is a list of all the map types that are allowed by the widget, so if you are adding a custom GeoJSON file make sure to add it to the list and set the properties accordingly

label - Name that appears in the widget editor, for selecting a map type
url - Path to the GeoJSON file
showBaseMap - should be true or false, based on whether you want to overlay your data on a map
keyAttributes - a list of attribute names to use as the key, these get concatenated together using the separator below
keySeparator - character to use as a separator for the attribute key

prism.customMap = {
	settings: {
		mapboxKey: 'myMapboxApiKey',
		urlTemplate: window.location.protocol + '//api.tiles.mapbox.com/v3/sangil.i6ch70f8/{z}/{x}/{y}.png',
		mapboxId: 'mapbox.light',
		shapeSeparatorColor: 'white',
		shapeHighlightColor: 'black'
	},
	maps: [
		{
			label: 'Canada',
			url: '/plugins/customMapWidget/geojson/canada-GeoJSON.js',
			showBaseMap: true,
			keyAttributes:['NAME'],
			keySeparator:',',
		},
		{
			label: 'US Counties',
			url: '/plugins/customMapWidget/geojson/USCounties-GeoJSON.js',
			showBaseMap: true,
			keyAttributes:['STATE','COUNTY'],
			keySeparator:'',
		},
		{
			label: 'China Provinces',
			url: '/plugins/customMapWidget/geojson/china-provinces.js',
			showBaseMap: false,
			keyAttributes:['name'],
			keySeparator:'',
		},	
	],
	widgets: {}
};

Step 4 - Create the Chart

On your dashboard, click the Create Widget button and select Advanced Configuration. Next, select the Custom Map Chart from the chart types menu. Pick a map type from the menu on the right. This selection determines which shape file to load, so you can use this plugin to make several map types available. Next, pick a dimension to use for the Geography dimension. The values from this field need to match the attribute key defined in the map's keyAttributes field.

For example, this plugin comes with a GeoJSON file that provides the shape information for all counties in the US. If you open this file, each shape is has properties for STATE and COUNTY that uniquely identify each shape. The included Elasticube combines the STATE and COUNTY codes into a single field named GeoKey. In order to match up data from the Elasticube to the GeoJSON file, the config file specifies that the key is comprised of STATE and COUNTY.

The Label dimension (optional) identifies which field to use when displaying the tooltip. The US Counties example uses FIPS codes to identify each county, but you may want to show tooltips with the county names instead.

The Value measure is the number to embed into each shape. You can use the standard options to format the number, and the color selections get passed along to each shape.

References/Notes

Mapbox API - More information about the Mapbox API. This plugin uses mapbox in order to render the maps, so it does require a Mapbox API Key in order to render shape overlays on top of maps. More information on Mapbox API pricing can be found here.
LeafletJS - The Mapbox project is an extension of the Open Source LeafletJS JavaScript library. If you're looking to modify the plugin, this can be a useful reference.
Natural Earth - This site provides free geo data for download, so if you don't have the geo data already you can likely get it from this site.
MyGeoData - This plugin requires a lat/long coordinate system (WGS 84) in order to display overlays on top of maps. If you're custom geo data comes in a different format, this site can likely help convert it to WGS 84 format. Upload your geo files, and convert/export it to a geojson file using the WGS 84 coordinate system. Also, you may need to change the file extension from geojson to js in order for your web server to know how to handle this file type.
Data included in the Sample Elasticube came from Natural Earth and this site
UPDATED 2016-04-04: The US county map was failing when loaded in Internet Explorer because IE could not handle accented characters in JSON. The GeoJSON file was updated to remove these special characters, and some code (including the Latinize library) was added to help handle special characters in general
UPDATED 2016-07-05: This plugin was updated to work with code changed in v6.4
UPDATED 2018-28-06: Certain States Not Showing(CA,CO,AZ)

SampleElasticube.zip

Jason Sweezey August 08, 2016 16:38

I managed to get my map loaded with a series of neighborhood boundaries across major cities in the U.S. People can perform searches in our system using a neighborhood as a reference. We'll aggregate the number of searches per neighborhood daily. What we'd like to show is how many searches were performed by neighborhood for a given time frame. I've got that part working so that neighborhoods are highlighted and the tooltip shows the search count.

But it only shows the neighborhoods that have transactions. What I'd prefer is to show all neighborhoods then color-code those with transactions (kind of like the example above where all of the counties in New England are in blue but a couple of counties are highlighted in green). Is there a way to do that without creating a record for each neighborhood in my Elasticube?

Thanks,

Jason

Takashi Binns August 09, 2016 14:38

Hi Jason,

It sounds like this is more of a data modelling exercise than anything else. Can you try modeling your Elasticube to include a LEFT JOIN between your neighborhoods table and transactions table? This will ensure all neighborhoods will be shown, regardless of whether or not there is a transaction. Then you can add conditional coloring in the widget, to differentiate visually.

Jason Sweezey August 10, 2016 19:56

Thanks Takashi. Right now I have a table of transactions, with each transaction containing a date, a neighborhood and an ID. I then use the chart to summarize the number of transactions by neighborhood. I'm not quite sure where I would insert the LEFT JOIN. Could you provide a bit more color on what you had in mind?

Takashi Binns November 01, 2016 14:07

Lets assume your Elasticube has a table [Transactions] and [Neighborhoods], and they are linked off a [neighborhoodId]. You can create a Custom SQL Expression in your Elasticube that looks like this

SELECT *, COALESCE(t.transactionId,1,0) as [Transaction Count]

FROM [Neighborhoods] n

LEFT JOIN [Transactions] t ON t.neighborhoodId = n.Id

This will create a new result set that has all transactions, but also lists neighborhoods with no transactions. The new [TransactionCount] column will have a value of 1 for every transaction and 0 when there is no transaction, so your dashboard can just SUM this field.

Hope this helps!

-Takashi

James Matthiesen April 19, 2017 15:49 (Edited April 19, 2017 15:50)

Hello!

I'm a relatively new user working with the custom map plugin for the first time. Is there any way allow a viewer to dynamically change the value displayed on the map, ex. to switch from "total population" to "average income", in a way similar to the Measure Changer plugin?

Currently I am using the Measure Changer plugin in other dashboards and I think it adds critical functionality to my dashboards.

It would be really nice to be able to do the same thing with the map widget. In my experience with map visualizations, particularly exploratory analysis, users are often interested in multiple values, but displaying/creating a map for each value (perhaps through the Tabber) becomes cumbersome as the number of values increase. Does anyone know how to solve this bottleneck?

Yoni Lerner May 03, 2017 19:03

Hi James,

There is no option within the plugin, what I will suggest is to create two different widget and "combine" them into one widget using the TABBER widget

Luke Evans June 29, 2017 23:53

I'm having a problem converting custom shape files (we have ESRI GIS tools) into geoJSON files for this widget. Does anyone have a reference guide on how to properly export it for Sisense consumption.

Ramon Lopez June 30, 2017 15:29

Hi Luke:

I've used various internet converters to make this transformation succesfully. The one thing to look for is ensure that there is only one feature in the file (one layer). I had some scenarios where i manually cleaned up the file to have one feature.

Also make sure that you add the file location to the config and define the Key attribute.

Let me know if this helps.

Thanks

Brian Wilson August 04, 2017 19:23 (Edited August 15, 2018 16:58)

This is a really awesome widget. I've successfully got a 5Digit ZipCode shapefile working!

It looks like there are a ton of plugins for Leaflet -- Is there any way to get those working? Specifically, I was hoping to insert some pins showing store locations on top of my zip code map or select a different basemap.

Sisense License November 08, 2017 12:12

I can't get a base map to load for some reason. I am using the public key available from Mapbox API. Here's the configuration file preview:

prism.customMap = {
settings: {
mapboxKey: 'pk.eyJ1Ijoic2FpbWFtb2hzaW4iLCJhIjoiY2o5cXZjNWdrNXpzdTJxbGdlNXp1MTA0NiJ9.QCstTOTyOECsdZ6Sny-jeA',
urlTemplate: 'https://api.mapbox.com/v4/mapbox.streets/1/0/0@2x.png',
mapboxId: 'mapbox.streets',
shapeSeparatorColor: 'white',
shapeHighlightColor: '#C0C0C0'
},

Vania Charles November 20, 2017 23:49

Hello,

Thank you for this widget. I'm new in Sisense and I want to use this pluggin to create a map. I already create my GeoJSON file and right now I have to modify the config.js. But Where can I find this file?

Any help will be greatly appreciated.

Thanks.

Oxana Noa Umansky November 21, 2017 20:44

Hi Vania, you can find the file here: C:\Program Files\Sisense\PrismWeb\plugins\customMapWidget\config.js

Sam Ovenshine November 21, 2017 20:46

@Sisense License

Were you able to get the default base map for the plugin to load (before making any changes to config.js)?

nagdev Amruthnath December 12, 2017 17:03

This is a great widget. I was wondering if anyone tried this plugin with floor plans or layout plans? I have posted this question in community.

https://support.sisense.com/hc/en-us/community/posts/115008356687-Floor-plans-as-custom-map-for-KPI-visualization

Trevis Thomas August 15, 2018 16:57

Has anyone found a way to customize the zoom level or positioning of this widget? I have a basic knowledge of JavaScript but I've been unsuccessful so far, and everything I've found on the internet is in relation to the Scatter Map widget. Any help would be fantastic. Thanks!

Todd Nash November 28, 2018 16:11

This is a great plugin. We are however experiencing an issue when filtering on the Canadian Map via the widget. "No Results" are displayed when selecting a territory because our data is in Upper Case and the widget seems to only recognize lower case. We tested this by changing our source fields to lowercase and were successful under those conditions but would prefer to remain in uppercase if possible. Is there an easy fix for that by chance? Thanks in advance for any assistance with this.

Andy Son December 17, 2018 18:26

Hi all,

Here's a geojson file you can use for any 3-digit Canadian postal code.

You can download it here: https://github.com/andyson23/Custom-Map-Widget.git

Cheers