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.

After you hit enter, the region will turn Green so that you know it’s mapped.  There are various controls on the left for controlling the tolerance of the autofill and changing the colors (which just helps guide you).  Repeat the process for the rest of your regions, in my case, the rest of the letters in my name.

Once complete, click the Create File button on the bottom left and it will create your very own Map Coordinates file.  In my case, that file is called Bryan.html.

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:

And check the box for Enable Custom Visualization Editor

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 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.

Final Output

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.

Using Your Map as a Selector
One more bonus tip, since this is a very common follow up question.  If you want to make your map clickable and act as a selector, it’s very easy!
In Document Design Mode, right click on the attribute column and choose Use as Selector.
The Selector will automatically target other appropriate grids (such as my second grid at the bottom of the picture above).  You can edit that by right clicking the column again and choosing Edit Selector.
Once complete, you can click on a region and it will act as a Selector!  In the above picture, I clicked the B and it targeted the bottom grid with the Selector.

You may also like...

65 Responses

  1. This is a fantastic post. There’s very little documentation out there that actually covers this specific subject, and I’ve been looking for it lately. Thanks.

  2. rkm1911 says:

    How do you get the area mashup to display in flash mode? You mentioned simple customization.

  3. rkm1911 says:

    Thanks that part seemed to work however, I was using the WorldImageMapCoords.htm in DHTML and it worked great but can’t print the map and does get embeded or work w/ send now data and file. Do you know if there is a Flash widget for the world map. Changing the area mashup to flash I get “Failed to load widget swf” error.

    • Bryan says:

      For printing, widgets won’t work at all. You may need to configure the coordinates file again, because this deployment is going to consider it a different widget from it’s DHTML counterpart.

  4. lexus72 says:

    Bryan – This is an excellent post. Do you know if we can control the tooltip size or even disable it for a customized map?


  5. Just great! Thanks Bryan.

  6. Satya says:

    Excellent Post Bryan. Area Mashup seems to be coolest thing to create now!

  7. Kexik says:

    First of all, great blog Bryan – thank you for sharing this. Secondly, I wonder whether it would be possible to increase the number of coloring bands in the mashup widget instead of having just the three?

    • Bryan says:

      Not out of the box. You’d have to customize your own copy using the SDK. I’ve done that myself, so if you go down that path and want some tips, let me know.

  8. Unknown says:

    Hi Bryan do you have any suggestion to get rid of the $ sign on the map?

    • Bryan says:

      The source code for it is included in the SDK. You have to make a minor edit using Flash Builder and overwrite your copy. It’s a pretty common question, so I’ll try to put together some detailed steps and add them.

    • Hi Bryan, could you show us some steps to get rid the sign $ of the Mashup Area? I very need them!
      Thank you very much

  9. cbrisse says:

    Hi Bryan. thanks a lot for this post (and all your blog), it is really useful and clear.
    Do you know what files we should modify to be able to use the widget in ipad?
    I see some process in Microstrategy documentation but they required a mac…

    • Bryan says:

      Right now it requires the SDK (and is not related to anything in this post at all), which for the iPad would require a mac. I do believe that may change in the near future though..

  10. Manoj says:

    Hi Bryan, Thnks for ur great post . Is it possible to increase the number of coloring bands in the mashup widget instead of having those three ?. If Yes then Please share.

    • Bryan says:

      You’ll have to modify the widget itself, using Flash Builder. The source code is included in the SDK samples. It’s a pretty straight forward modification. Check out this post if you want to try setting up the environment to give it a try.

  11. Manoj says:

    Hi Bryan, Thnks for your quick reply. The coloring band i have set for the mashup widget is going perfect when i am viewing my map in web. But whenever i am trying to view this map in my iPad the coloring bands are not showing .Only the default blue color is displaying.To apply these coloring bands into my iPad what i have to do???? Hope You understand what i am trying to say .
    Please help me out.. I am Using Microstrategy version 9.2.1m

    • Bryan says:

      The iPad version is completely different. I haven’t used it before, so I’m not sure what the differences are. I believe the iPad map widget is being updated in the next release, but I don’t know the details or extent of that. Perhaps that will bring it to feature parity with the Web version.

    • Andrew Ray says:

      For the ipad version you use custom threasholds on the metrics themselves. these will apply automaticaly then it is rendered.

  12. Manoj says:

    Hi Bryan,
    using your idea ,i have done a lot of report on different country map in Microstrategy using AREA MASHUP widget. But when ever i am trying the same thing in using MARKER MASHUP widget i am facing problem.The Problem is in Marker Mashup widget the Map is not coming out ,only the Bubbles are showing the respected metrics without map in the background. So please tell me what i have to do so that both the bubbles as well as the map will come out. Thank You

  13. Can i use an image of say African map and place maybe x,y axes coordinates of the country on the image to be targeted by say bubbles for the the individual countries.All this to try and get a map working on Web.

    • Bryan says:

      For that, you’ll want to checkout the Marker Mashup widget, and not the Area Mashup described here. I haven’t used that much because it wasn’t a map style I was interested in, but there are some options for the different markers to use. The rest of this tutorial should still apply for adding the image.

  14. Unknown says:

    I am using the custom map and it works! however there are some needs to view it on ipad..but since this map is using flash player and ipad does not support any flash, do you have some recommendation on how this map will be able to view inside ipad?

    • Bryan says:

      I *think* this widget will render natively on an iPad in 9.3, but don’t quote me on that, I could be mistaken. If not, then your only option is to build it using the Mobile SDK which is not easy.

  15. Hi Bryan, thank you
    for this helpful post. Unfortunately, I am stuck in step 5. I do not know how to create a new attribute using the Apply Simple function. Could you please explain it in more details or suggest some links which might be useful.
    Thank you in advance.

    • Bryan says:

      ApplySimples are unrelated to the map. I just mentioned using them in order to build out the values “B-r-y-a-n” for this example, but in your implementation it can just be whatever attribute has the data you’re trying to map.

      To directly answer your question though, an ApplySimple simply passes SQL through to the database in this syntax:

      ApplySimple(“case when #0 = 1 then #1 else #2 end”, [Attribute One]@ID, [Attribute Two]@ID, [Attribute Three]@ID)

      You pass the snippet of SQL that you want and use 0-based replacement characters to plug in where Attributes will fill. This way, MicroStrategy still knows how this SQL will relate to the rest of the report in the engine, and it can still add the proper table prefixes to the fields.

    • Thank you!
      What I am trying to do is (like you did)to build an attribute from existing one , which would have attribute elements that matches names of my regions (I am trying to build geomap widget with 3 regions in it).I am using evaluation MSTR version so I don’t have my data for map.
      So, as I understood, I have to modify attribute forms of existing attribute (for example Regions attribute) using ApplySimple function?

    • Bryan says:

      If you want to do custom groupings above what your data supports, then yeah, ApplySimple is the way to do it. Here’s a tech note with more details.

    • Just want to create grid with an attribute elements that match names of my regions.

    • bala krishna says:

      Hi Bryan,
      This is really good and helpful post and thanks a lot, but I have a small question. Do we need to have an SDK license in-order to implement the Map Visualization on a flash version of a dashboard. I tried a lot to create this without SDK, but the widget was stuck specifying “Loading Visualization… ”

      Is it mandatory to configure the widget using Widget Deployment for Flash version of Dashboard?

    • Bryan says:

      No SDK required. The SDK is actually just documentation and samples, it doesn’t add any functionality. I’ve included the steps in this article on how to deploy it, but it sounds like you’re actually getting an error that you can’t see. When you get stuck in the “Loading Visualization…” step, press CTRL+ALT+SHIFT+D to bring up some basic debugging info and see if you see an error message in there.

  16. Jerry says:

    Hi, first, i have to say thanks a lot.Nice blog!
    I have a little problem with flesh mode. In this path – rslPath=”../swf/MapVisualization.swf” i have no file with name “MapVisualization.swf”. So i tried find another one, with the same name and found it in MicroStrategyWeb ASPxVisFramework. Then I copied this file to the path slPath=”../swf/MapVisualization.swf” but it doesnt work:(//( Could u please help me?


  17. Andrew Szwec says:

    Hi Bryan,
    Than you very much for your blog entry, I found it very helpful. Now that I have made some reports using this technique how can I get them onto the iPad?
    The Area Mashup says it has been depreciated in Microstrategyy 9.3 and flash does not work on iPad, any ideas?

    Thanks for sharing your knowledge.


  18. Hi Bryan,

    the new widget I think its called Image Layout, that comes with some maps of some contries and maps of the world and USA.

    The thing here is that if I try to see the dashboard in the iPad, it only shows the report grid 🙁

    Has anyone made this work for ipad?

  19. @Javier,
    This will work with the next version of iPad client. Stay tuned and download it from Apple Store when released.

  20. Dario Picco says:

    @Ojciec Pężyrki

    Now it work with the last version of iPad client but the widget only show ” IMAGELAYOUT_HTML_FILE_NOT_FOUND.”

    Know why?

    • Bryan says:

      It still references the layout from an external source. I haven’t tried this widget on mobile, but my guess is that instead of referencing the file with a relative path, you have to reference it with a fully qualified URL that is accessible to your mobile device.

  21. Bryan, thanks for this excellent post.
    I have a problem, can we display the original map as the background of our own custom map? because I think it’s useless to move these 2 files (‘ownCustomMap.html and ownCustomMap.png’), so I just move ‘ownCustomMap.html’..
    Or can you suggest the other method for my problem displaying custom map in front of the original map(maybe another dhtml, flash, or wiget)?

    Thanks 🙂

  22. emax says:

    Hi Bryan, I’m trying to use Area Mashup in Microstrategy 9.0.2 but the image doesn’t show. I think it’s a problem in the path “.VisFrameworkmapProvincia.html”. Do you have any suggestions?



    • Bryan says:

      If that’s the path you’re passing, then it’s not right .. I think you can specify the entire URL, and if not, try a path like /VisFramework/map/Provincia.html

    • emax says:

      Hi Bryan, thanks for your reply. I try also “/VisFramework/map/Provincia.html” and “D:MicrostrategyWeb ASPxVisFrameworkmapProvincia.html” but it didn’t solve…

      A difference with your post is that I couldn’t edit the visualization properties.

  23. Hi Bryan, I am confused whether to use Google Map or ESRI. We have a license for ESRI maps. We want to show map at various layers like State, Territory and ZIP Code. And user should be able to drill down as well. So which option is better and can you refer some document which we can follow.

    • Bryan says:

      I haven’t used either, but Google Maps comes with an additional license cost. Since you already own ESRI, you may as well go with that one.

  24. B says:

    Dear Bryan,

    I have used this post and I have set up my map, which works very good. But, in the map I would also like to display the name of each region, not just by tooltip when hovering the map.

    The file that is generated from ImageMapCoordinatesUtility is html but it doesn’t seem to accept any kind of html coding that I am placing, like background color, or titles for the area tag etc.

    Do you have any suggestion how can I perform these changes?

    Thank you very much.

    • Bryan says:

      You’d have to modify the widget itself, which will require some flex SDK work. The code for it is provided in the MicroStrategy SDK, and I’ve put up some posts on how to configure your environment if you think you want to give it a try. The HTML file you feed to it here is just for sending in coordinates and not for actual formatting.

    • B says:

      Thank you very much for your reply. I assumed I would end up using flex SDK, I was still hoping for a simpler solution though 🙂 I have already localized the files you have put up regarding configuring flex environment. I most probably will give it a try.
      Thank you again.

  25. hi bryan,

    Thanks for your post.

    I’m having a problem with colour bar option. My values are mostly negative and when I open my Dashboard the two marks (separators colors) are on left side and the image only applies the colours when second separator is on value 0. When I have only negative numbers I can’t colour the image.
    Do you know how I can resolve my problem or how I can control the limit values of the colour bar?

    Thank you very much.

    • Bryan says:

      If I recall correctly, the selector bar may be hardcoded to start a 0. That widget has lots of such hardcoding in it, so it’s not really the greatest. Your only real option would be to edit it in Flex and deploy your own custom copy of it. I have other posts on this site that show how to do that, but it’s not for the feint of heart. Alternatively, you could log a bug with MicroStrategy and see if they’ll fix it.

  26. Hi Bryan,

    Did anything change with 9.3.1? I know the deprecated Mashup widget was removed entirely from the Flash/DHTML menu. I followed everything and I dont see my custom map under my DHTML options. I double checked that the coordinates and image files were placed in the correct Visualization folder , I rebooted my web server, I checked the properties file and all was listed correctly following your instructions. Do you have any other gotchas that I can check for to see why this isnt showing up in my menu of widget options? Also, I added the Flash piece for the ImageMap which DOES show up but it throws an Unspecified error when dropped on a dashboard page. Thanks for your help. Respectfully, Laura

    • Bryan says:

      I haven’t upgraded to 9.3.1 yet, but I also haven’t used this widget in a really long time. I think the Unspecified error is when the Flex SDK versions don’t match, which would point to MSTR not updating the widget after the upgrade. You’ll probably have to contact tech support.

    • Nikky says:

      Laura, after we upgraded from 921m to 931, my custom maps are not getting displayed either. In fact, I do not even have a drop down to view any of the maps (even the out of the box ones). I need to look into this in more detail.

  27. Hi Bryan,

    I am using Area Mashup Widget with Custom Image Map. I want to display metrics on hot areas of my image map. how i can do that?

  28. mummstheword says:

    Hi Bryan,

    Great article, thanks for sharing! I was curious if you knew how to make the colors selected in the utility show up in the Web. It looks as if the colors that are selected are getting “lost in translation” between the utility and the Web.


  29. Hello Bryan,

    Thank you for this great blog. Do you know if it possible to insert this custom visualization in a dashboard ? If yes, how ?!

    Thank you for your reply

  30. Guido says:

    Hey bryan,
    Thanks for the information.
    Do you know if it’s possible to add this “map” you have created to a Visual Insight? I mean, if you want to appear “Bryan” on a new map’s visualitazion, how can you do that?

  31. Hi Bryan,

    I have a problem with the coordinates: when I try to add a field, the HTML gets placed under the coordinate where I create it.
    How could I solve this?
    Thanks in advance!

  32. Robert Escalante says:

    Hi Bryan, I’m using mrts 10.1 but I can not see the Area Marhup widget avaiable in the custom visualization box, Does there is any way to add this widget? because I’ve only find for ipad and iphone visualization?

    Best Regards

Leave a Reply

Your email address will not be published. Required fields are marked *