Vitara map chart may display the US map and World Countries by default. We can, however, make a map of any other country. Consider the following easy example: generating a map of the countries of the United Kingdom by population. I have the following data file:
The first step is to obtain the shapefile (.geo.json file) that corresponds to our data. Because the data I have is at the nation level, I must find a shapefile of the United Kingdom at the country level (admin-0 level).
The reference web page to download GeoJSON shape-files: http://code.highcharts.com/mapdata/
The geojson file required for our example is shown below.
To download the file, select the GeoJSON file type. We must verify that the downloaded GeoJSON file contains the desired coordinates. Use any online json viewer for this purpose, for example: http://jsonviewer.stack.hu/
Open the downloaded GeoJSON file using any text editor, for example notepad. Copy the entire text and paste in json viewer web page.
Now click on ‘Viewer’ tab beside the ‘Text’ tab.
Now the geojson content will be displayed in json tree structure.
One of the objects in the JSON tree structure is the ‘features’ array. We will have objects for each segment of the chart if we enlarge the ‘features’ array. As there are four partitions in the chart representing each country (England, Scotland, Wales, and Northern Ireland) in our United Kingdom countries example, there are objects named from 0 to 3.
It is now evident that the shape we downloaded is exactly what we need. Our data and the coordinates in the shapefile are identical.
The next step is to locate the ‘dictionary key’. The dictionary key is the parameter that uniquely identifies each partition in the shape file. The United Kingdom map is divided into four sections, which should be defined with some boundary coordination. Each of these border coordinates has its own name. These distinct names are listed in the ‘properties’ column of each GeoJSON file partition. To find the dictionary key, expand any object, such as ‘0’ and extend the ‘properties’ array.
Please note the rounded area in the screenshot below.
There are various fields in this properties array that can be used as dictionary keys. For instance, we can use the ‘hc-a2’ field as a dictionary key. The hc-a2 field value is ‘EN’ for England, ‘WA’ for Wales, ‘SC’ for Scotland, and ‘NI’ for Northern Ireland. You may have noticed that each field is distinct.
The point here is that you can declare any field as a dictionary key, but it must match our data. We have nation names rather than short forms in our data file.
Therefore, exact matching fields in the properties array with our data is the ‘name’ field.
If there is no matching dictionary key field in shapefile with data file, we must generate synonyms. This is covered in the section ‘Dictionary property’ of the document titled ‘Customization of the Map chart’.
After determining the dictionary key, we can create a new map layer for our example. For this, change the’mappinglayers.txt’ file, which is located in the Vitara map chart installation folder at the following path.
C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\MicroStrategy \plugins\VitaraMaps\custom
The following is the screenshot of ‘mappingLayers.txt’ file. There are three predefined mapping layers, world physical, US physical, and US Countries.
The following is the notation to add new map layer: <ns>.<property>
<ns>: NameSpace, this can be any combination of alphabets, but choose a unique value for each new map layer. The map layer should contain the following properties;
<ns>.name =
<ns>.shape =
<ns>.dictionarykey =
In the ‘name’ property we define the name of the map we want to give.
For example, i want to give ‘United Kingdom’ as the name, then ‘name’ property definition will be
kk.name= United Kingdom
In the shape property definition we should give the path where we copied the shape file of our map. For our example, as we copied the shape file into VitaraMaps\custom\shapes folder, the following is the shape property definition.
kk.shape= custom/shapes/uk-countries.geo
All the shape files should be placed in ‘Shapes’ folder in custom folder. This is not compulsory, but in the naming convention point of view it’s better to do.
Dictionary key property definition will be the unique identity field we selected in GeoJSON shapefile.
kk.dictionarykey = name
In the mapping layers text file start a new map definition and define name, shape, dictionary key properties.
(please refer section ‘Mapping layers text file‘ in the document titled ‘Customization of the Map chart’for more information about ‘mapping layers text file)
kk.name= United Kingdom
kk.shape= custom/shapes/uk-countries.geo
kk.dictionarykey= name
Please refer the sections ‘Name’ property, ‘Shape’ property, ‘Dictionary key’ property and Dictionary’ property in the document titled ‘Customization of the Map chart’ to know the procedure how to define these properties. After defining all these properties save ‘Mapping layers’ text file.
The following is the screenshot of mappingLayes.txt file after defining United Kingdom mapping layer.
Now, in MicroStrategy, create a dossier or RS document and insert the Vitara map chart. The ‘World Physical’ map is displayed by default in Vitara Map. Select the’map’ tab after clicking the ‘edit’ button. The ‘Map Layer’ drop down button should be expanded. The updated map definition ‘United Kingdom’ can be found here. Choose this map layer. Please see the screenshot below.
Apply required Map attribute and a metric to the visualization.