KB486879: How to Add a Custom Map Layer to the Out-of-Box ESRI Map on MSTR Web/ Library

Introduction:

To meet analytical demands, sometimes users need to add a custom map layer to the built-in ESRI map in dashboards on Strategy Web and/ or Library. The below screenshot is an example of Wire Center boundary map layer (source: https://sgsi.com/telecommunications-maps-and-data/).  This document provides step-by-step instructions to integrate the custom map layer with dashboards.

Step-by-Step guide

1. To configure the out-of-box ESRI map work on Strategy Web or Library a map key is needed in the following configuration file assuming Tomcat is the web server.

./tomcat/webapps/MicroStrategy/plugins/ConnectorForMap/WEB-INF/xml/config/mapConfig.xml
./tomcat/webapps/StrategyLibrary/plugins/ConnectorForMap/WEB-INF/xml/config/mapConfig.xml
A dummy key is shown in the following example.
<apps clientToken="true">
<key> <![CDATA[000000000123455677788888xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx]]> </key>
</apps>
By default, the map server is https://services.arcgisonline.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer

1. Add the following information regarding the custom map layer to the <layers> node in the forementioned mapConfig.xml file. The layer id can be any integer that is unique among all the layers. The value for ml is the URL where the custom map is hosted. Replace the highlighted values with the ones needed.

<!—The layer id can be any unique integer -->
                  <layer id="7"
                  title="WireCenters"       ml="https://gis.arcgis.xxxx.xxxx.ca/arcgis/rest/services/WC_Boundary/FeatureServer/0"/>
                 

1. Make sure there is a roleId equal to “Other” as shown below in mapConfig.xml.

<!-- The following values identify the geo-role of the primary (roleId) and secondary (sfr) geo attributes in the <shape> node -->
        roleId 1 = "City"
        roleId 2 = "State"
        roleId 3 = "Country"
        roleId 4 = "Location"
        roleId 5 = "Latitude"
        roleId 6 = "Longitude"
 roleId 7 = "Other"
        roleId 8 = "ZipCode"
        roleId 9 = "County"     
 

1. Add the following information regarding the shape to the <shapes> node in mapConfig.xml. The shape id can be any integer value that is unique among all the shapes. The role ID corresponds to “Other” mentioned in Step 3. The layerId of the shape needs to match the right layer specified in Step 2. In the qf field, we can specify which data is fetched from the server where the custom map layer is published. The ea field specifies which attribute in the map layer is used to filter the data from the map server. This will be explained in detail at the end of the document. In this example, “wc_clli” stands for Wire Center ID.

        <shape id="700"
         desc="Wire Center Boundaries"
         roleId="7"
         type="Polygon"
         descWeb="mstrweb.9229"
         descFlash="mstr.1622"
         descDesktop="26973"
         qf="['wc_clli','cc_name','layer_id']"
         ea="wc_clli"
         layerId="7" />
                   
A complete example mapConfig.xml file is attached.
 

1. For the changes in mapConfig.xml to take effect, reload Strategy app on Tomcat server or restart Tomcat.
2. The following example dataset is used to display the custom map layer in a dashboard

“Wc Clli” represents Wire Center ID and DSA means Distribution Service Area ID. They are the identifier for a distribution service area and are in m:m parent-child relationship.
 

• If adding a dataset by doing data import, we can define geography in the following editor. In this example, we choose “Wc Clli” and select Define Geography -> Custom.
  

• Add a new visualization in the dashboard and choose ESRI map as the type.
  

• If we don’t define geographic type for an attribute when doing data import or the dataset is a schema-based cube, we can do the geography definition in the dashboard. In this example, right mouse click “wc clli” and select Custom as its geographic type, as shown below.   
  

• Add “wc clli” to Geo Attribute section in the Editor. To display more information on the map, we can add attributes and metrics to Tooltip and they will show up in a pop-up info window when we mouse over an area.

• Go to Format. Select Area as Type, Wire Center Boundaries as Boundaries and customize the threshold colors as needed by clicking the color band.
  

Then the map layer will be displayed on top of the built-in ESRI Map.
MSTR Web/ Library sends a request similar to the following one to the feature server (https://gis.arcgis. xxxx.xxxx.ca/arcgis/rest/services/WC_Boundaries/FeatureServer/0 in this example) to get the map layer data and then display the wire centre areas. The attribute in the where clause is defined according to the ea value in the shape node in mapConfig.xml and the list of wire centre IDs is obtained from the Geo Attribute element list in the dataset, that is, “Wc Clli”.
https://gis.arcgis. xxxx.xxxx.ca/arcgis/rest/services/WC_Boundaries/FeatureServer/0/query?f=json&outFields=WC_CLLI%2CBND_NAME%2CLAYER_ID&outSR=4326&spatialRel=esriSpatialRelIntersects&where=(wc_clli%20in%20(XXXXXX))%20AND%20(1%3D1)
 

An Example of mapConfig.xml

The following configuration file has been tested and confirmed working as expected. For security purpose, the highlighted map key is hidden.
The parts in the yellow background is related to the custom Wire Center Boundaries map layer used as the example.
 

<mc>
	<!-- ESRI map configuration -->
	<ec>
		<bms>
		</bms>
		<pjs>
		</pjs>
		<!-- End of nodes used for on-premises map integration -->

		<!-- The following nodes are used for cloud-based map integration, including out-of-the-box map integration -->
		<apps clientToken="true">
			<key> <![CDATA[00000000017383xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx]]> </key>
		</apps>

		<webmaps>
		</webmaps>
		
		<layers>
			<layer id="1"
			title="US-States"
			ml="http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0"/>
			<layer id="2"
			title="US-ZipCodes"
			ml="http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_ZIP_Codes/FeatureServer/0"/>
			<layer id="3"
			title="US-Counties"
			ml="http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Counties_Generalized/FeatureServer/0"/>
			<layer id="4"
			title="World-Countries Detailed"
			ml="http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Countries/FeatureServer/0" />
			<layer id="5"
			title="World-Countries Generalized"
			ml="http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Countries_(Generalized)/FeatureServer/0" />
			<layer id="6"
			title="World-Admin-Divisions"
			ml="http://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Administrative_Divisions/FeatureServer/0"/>
			<layer id="7"
			title="WireCentres"
			ml="https://gis.arcgis.xxxx.xxxx.ca/arcgis/rest/services/WC_Boundaries/FeatureServer/0"/>
		</layers>
		
		<!-- The following values identify the geo-role of the primary (roleId) and secondary (sfr) geo attributes in the <shape> node 
        roleId 1 = "City"
        roleId 2 = "State"
        roleId 3 = "Country"
        roleId 4 = "Location"
        roleId 5 = "Latitude"
        roleId 6 = "Longitude"
        roleId 7 = "Other"
        roleId 8 = "ZipCode"
        roleId 9 = "County"
		-->
   
		<!-- End of values that identify geo-role of the primary (roleId) and secondary (sfr) geo attributes -->
		<shapes>
			<shape id="100"
			default="true"
			desc="US State Names"
			roleId="2"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['STATE_NAME']"
			ea="state_name"
			layerId="1" />
			<shape id="200"
			desc="US State Abbreviations"
			roleId="2"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['state_abbr']"
			ea="state_abbr"
			layerId="1" />
			<shape id="300"
			desc="US Zip Codes"
			roleId="8"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['ZIP']"
			ea="ZIP"
			layerId="2"/>
			<shape id="400"
			desc="Countries of World"
			roleId="3"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['ISO','Country']"
			ea="Country"
			layerId="5" />
			<shape id="500"
			desc="World Admin Divisions"
			roleId="2"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['NAME']"
			ea="NAME"
			layerId="6" />
			<shape id="600"
			desc="US Counties"
			roleId="9"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['NAME']"
			sf="STATE_NAME"
			sfr="2"
			pk="FID"
			ea="NAME"
			layerId="3" /> 
			<shape id="700"
			desc="Wire Center Boundaries"
			roleId="7"
			type="Polygon"
			descWeb="mstrweb.9229"
			descFlash="mstr.1622"
			descDesktop="26973"
			qf="['WC_CLLI','BND_NAME','LAYER_ID']"
			ea="wc_clli"
			layerId="7" />
		</shapes>

		<urlPrefixes>
			<urlPrefix id="1">www.arcgis.com</urlPrefix>
			<urlPrefix id="2">services.arcgis.com</urlPrefix>
			<urlPrefix id="3">js.arcgis.com</urlPrefix>
			<urlPrefix id="4">static.arcgis.com</urlPrefix>
			<urlPrefix id="5">geocode.arcgis.com</urlPrefix>
			<urlPrefix id="6">services.arcgisonline.com</urlPrefix>
			<urlPrefix id="7">cdn.arcgis.com</urlPrefix>
			<urlPrefix id="8">basemaps.arcgis.com</urlPrefix>
			<urlPrefix id="9">basemaps-api.arcgis.com</urlPrefix>
			<urlPrefix id="10">server.arcgisonline.com</urlPrefix>
			<urlPrefix id="11">sampleserver1.arcgisonline.com</urlPrefix>
			<urlPrefix id="12">sampleserver2.arcgisonline.com</urlPrefix>
			<urlPrefix id="13">msfvzm4ehacvflca.maps.arcgis.com</urlPrefix>
		</urlPrefixes>
	</ec>
	
	<!-- Google map configuration -->
		<!-- <gc></gc> -->
		<!-- MapBox configuration -->
</mc>