Building Your Own Custom Map
The MicroStrategy Area Mashup widget is a handy (and free!) Widget for adding a simple map to your Report or Dashboard. This serves as a nice alternative to using full fledged Google Maps or ESRI. The widget itself has undergone a lot of changes in each version, and the 9.2.1 release removed (and added) many hoops we had to jump through to use this widget in previous versions. The widget is pretty straight forward to use with any of the out of the box maps, but did you know that you can easily build your own custom map and deploy it using this widget? Today I’ll show you how.
First, if you’ve used this widget in the past, a lot has changed. There were several bugs in the pre-9.2 version that I fixed myself in my own custom copy including metric formatting issues, limitations on metric naming support, issues with the color picker, issues with blank regions and maybe even some more. (fun fact: I wrote up a pretty lengthy post detailing how you could fix those yourself, but right before I published it, I discovered they were all fixed in the 9.2 release, so I scrapped it). But perhaps most perplexing was that you had to provide a link to the coordinates file to support your map. There were about a dozen provided out of the box, but this setup wasn’t very user friendly. Fortunately, MicroStrategy scrapped that UI and replaced it with a simple Widget Properties option where you can pick the out of the box maps from a drop down list. (for more details on configuring this, check out this tech note). Unfortunately, this means if you want to customize your own coordinates file, it now becomes a little more difficult. That’s where this post comes in!
What the Area Mashup really is
Shortly after it’s debut in 9.0.1 Jump Start, the widget was renamed from Map Widget to Area Mashup. The reason is because it’s not a map in the geographical sense, but a map in the image sense. It basically is a widget that will load an image and draw polygon regions on your image that will react in both color and tooltip to your underlying report data. The most common implementation is as a geographical map, but you could use it for anything. The SDK contains a sample for using this widget to build a heatmap on top of a retail store layout. To illustrate that you can really use this for more than just geographical maps, my sample today is going to use my name!
Step 1 – Make your image
You can use any image you want. For me, I just made a simple image made up of my name. Use any program you want and save it in pretty much any format. I chose PNG and saved the file as Bryan.png:
Step 2 – Build your image map
This part is tricky. What we have to do is build a file that will tell MicroStrategy where to draw the regions. In my example, I want the regions to be each letter of my name. You could build this yourself (honestly writing your own tool in .NET or Java to capture your mouse position as you trace the letters is only a few dozen lines of code), but MicroStrategy does provide a nice utility to do this for you. Unfortunately, you need to own an SDK license to get this tool.
If you do own it, and have the SDK installed, navigate to C:Program FilesMicroStrategySDKtoolsImageMapCoordinatesUtility. There you’ll find a .air file that you can run and install the tool.
Once installed, run it from under your Windows Programs, click Select Images, browse for the picture you created in Step 1, and click Load Image.
Now, you just have to click on a region. In this example, I clicked on the B, and a text box pops up. What you put in this text box will need to match (case sensitive) to the Attribute Element you get from your report. In my case, I’m going to build a custom attribute that will return values for each letter of my name, so I’m going to attach this to the letter B. Hit enter after you place your text.
Step 3 – Enable Custom Visualizations
If you want to use your map as a widget in a Document, you don’t have to do this step. But, you can also use your widget as a stand alone Report. To do that, you’ll need to enable this option.
As the administrator, navigate to your project’s Preferences page in Web. Go to Project Defaults -> General:
Step 4 – Add your custom map
To deploy your custom coordinates file, you should copy your image and html file (for this example, Bryan.png and Bryan.html) to your Web server to the location Web ASPxVisFrameworkmap. You’ll find the other out of the box options in this folder too.
Next, edit the imageMap.properties file, which can be located in Web ASPxWEB-INFclassesresources. Add your coordinates file to the list:
The syntax is the path to your coordinates file and then the display name for the drop down box. You may notice that the other out of the box options have names like mstrWeb.8173. This is to support internationalization and the lookup values for these can be found in the MessageBundle*.properties files located in this same directory. It’s optional if you want to use them, but if you want to support different languages, then you can follow the same syntax and add your names to the appropriate Message Bundles.
You’ll need to restart your Web Server for these changes to take effect.
TIP: If you don’t want to edit this file directly (upgrades will blow your changes away), you may want to go the proper route and make this a plugin. If you’re using the Web Customization Editor, then you can find this file under MicroStrategy Web Configuration -> Property Files -> WEB-INF -> classes -> resources. The Property Files folder isn’t visible by default, so to enable it go to Window -> Preferences -> MicroStrategy -> Show Advanced Options from within Eclipse.
Step 5 – Build your grid
Now, you need to build your grid. The requirements are that the Attribute has to be in the Row and the elements have to match the elements you defined in Step 2. The first metric on the grid will handle the coloring, and additional metrics will show up in the tooltips.
I tried to build this example with a Consolidation, and I received errors from the widget. I think it only supports Attributes, so I created my sample by making an Attribute using ApplySimples and Case statements. My grid looks like this:
My Attribute Elements match the region names I defined in Step 2. The blank element will be dropped from the widget since it doesn’t map to anything.
Step 6 – Apply the Area Mashup
If you’re applying this to a Report, now you can click the Tools drop down and choose Custom Visualizations.
Remember that in order to see the Custom Visualizations option, you’ll need to have completed Step 3. If you’re applying this as a widget on a Document, you don’t need to do this step. Instead, simply right click on the Grid object on the Document, choose Properties, and choose Widget. You’ll get to the same next screen.
Check the box to enable the visualization and scroll down and choose the Area Mashup widget.
TIP: Even though this is a Flash Widget, it’s only available under the DHTML section of a Document Widget list. If you want to enable it for Flash mode, simply add this line to your WebASPx/WEB-INF/xml/config/widgets.xml file:
<widget id="AreaMashup" isIVE="false" isApp="false" scope="52" rslPath="../swf/MapVisualization.swf" title="Area Mashup"/>
Restart your Web Server, and you’ll now be able to use it in Flash mode.
Next, click the Visualization Properties button to configure the widget.
You should see your custom map in the drop down after completing Step 4 (make sure you restarted your Web Server if you don’t see it). Select it, and click OK.
It’s a masterpiece! Each region is filled in and colored based on the slider in the widget. You can hover over a region to get a tooltip with all of the metrics from the underlying grid.
If you did this as a grid, you will see a new view mode button in the toolbar that represents your Flash visualization.
When you save it with this as the default view option, the Report will get a little F icon that indicates that it’s a Flash report.