How to install the Visual Crossing Mapping Plug-in for MicroStrategy


This document provides a quick start guide to installing and configuring Visual Crossing 4 for MicroStrategy Web.

Quick steps

  1. Configure working MicroStrategy Web 10 environment.
  2. Add the Visual Crossing plugin to MicroStrategy Web
  3. Restart web servers
  4. Unpack skeleton Visual Crossing metadata
  5. Configure MicroStrategy Web project preferences to point to metadata location
  6. Enable Custom Visualizations in MicroStrategy Web.
  7. Run a report with data that can be mapped
  8. Convert to a map.

Detailed steps


Installing Visual Crossing 4 on MicroStrategy Web requires:

  1. A working MicroStrategy Web 9.4.1 or MicroStrategy 10.2 or higher system. 
  2. Credentials of a MicroStrategy user with MicroStrategy Web project administration privileges.
  3. Full access to the MicroStrategy Web environment to install plugins and restart the application server or web server.
  4. Hard drive space for the Visual Crossing metadata. The size requirements for this depends on the data being used but it typically ranges from 100Mb - 1 GB.


Configure working MicroStrategy Web 10 environment.

To install Visual Crossing 4 you will need a working MicroStrategy 9.4.1 or 10.x installation (we recommend 10.1 or higher when running MicroStrategy 10). You will need full access to the MicroStrategy Web environment and the host application server or web server so that a new plugin can be installed.

In case you are running on an earlier version than MicroStrategy 10 please refer to the FAQ for updating your Java version

Run the Visual Crossing Install File

Upon completion of the installation routine, you should find three folders in your Visual Crossing installation directory: Docs, Metadata, and Web Plug-in.

Within the 'Docs' folder there is a single readme.txt file containing information about your 30-day evaluation license and a link to this guide.

Within 'Metadata' you will find a folder named 'DefaultVisualCrossingMetadata'. This is the metadata root directory folder. This folder will be referenced in the 'Unpack skeleton Visual Crossing Metadata' section below.

Finally, in 'Web Plug-in', you will again find a single folder named 'VisualCrossingWeb'. This is the folder referenced in the 'Add the Visual Crossing plugin to MicroStrategy Web' section directly below.

Add the Visual Crossing plugin to MicroStrategy Web

On the hard drive in the MicroStrategy Web folder you will find this plugins folder. Copy the 'VisualCrossingWeb' plugin from you <VisualCrossingInstallDirectory>/Web Plugin folder into the MicroStrategy Web plugin folder. After you are done, your 'plugins' folder should resemble the following diagram. Note that you may have other plugins installed within the MicroStrategy/plugins folder so the number of directories inside plugins may vary.


If you are using the JSP version of MicroStrategy Web in a servlet container such as Tomcat, JBoss or WebLogic, you may need to repackage the war and redeploy the MicroStrategy Web application. Please consult the MicroStrategy documentation for these steps. In all servlet containers it will be necessary to stop and restart the MicroStrategy Web application for the new plugin to be registered with MicroStrategy Web.

If you are using the ASP version of MicroStrategy Web that runs inside Microsoft’s IIS, it is necessary to restart web server. The most reliable way to do this is issue an iisreset command from the Windows Command shell:

Useful tip:

Don’t leave backups or copies of files inside MicroStrategy plugins – these can confuse MicroStrategy Web! Copy those backups to a separate location outside of your MicroStrategy Web deployment.

Restart web servers

Make sure you restart your web servers as described above otherwise MicroStrategy Web won’t read the new plugin!

Unpack skeleton Visual Crossing metadata

Visual Crossing 4 stores information in a metadata file location. Copy the 'DefaultVisualCrossingMetadata' metadata root directory described in the 'Run the Visual Crossing Install File' section to a file location of your choice. This file location should:

  1. Be accessible from all MicroStrategy Web nodes that need to access the metadata. This may include nodes of a cluster or nodes of different environments levels such as development, test or production.
  2. Allow read and write access from the process running MicroStrategy Web. The Visual Crossing process will read and write information to this location.
  3. NOT BE beneath either the 'Program Files' or 'Program Files (x86)' directories in Window environments.  Special Windows permission issues prevent the metadata from being successfully updated when placed here.

For more information on running in a clustered environment, see our dedicated guide (free support account required).

Useful tip:

In the next step, we will configure the location of this directory in the MicroStrategy project preferences. If your environment will migrate MicroStrategy projects between environments it is very useful for the setting to work in all cases. Therefore if the location of the metadata is D:\VisualCrossingmetadata, ensure that D:\VisualCrossingmetadata will exist in all environments for easy migration.


Configure MicroStrategy Web project preferences to point to metadata location

Visual Crossing finds the above metadata location using a MicroStrategy Web project preference. To configure this preference:

  1. Log in to MicroStrategy Web with a user MicroStrategy Web administration privileges.
  2. Navigate to the project preferences section of MicroStrategy Web
  3. Find the Visual Crossing section
  4. Set the path to the Visual Crossing metadata in the “Metadata location” section.
  5. Press apply to save the selections to MicroStrategy projects.
  6. Verify that the metadata location is found successfully – a message will appear underneath the entry box indicating success or an error condition.

Useful tip:

If you don’t see the Visual Crossing project preferences section then your plugin isn’t installed correctly! Review section “Add the Visual Crossing plugin to MicroStrategy Web” above.

Enable Custom Visualizations

In MicroStrategy Web Project Defaults, navigate to ‘General’ and check that Custom Visualizations is enabled.

Useful tip:

It is not strictly necessary to enable custom visualizations as Visual Crossing maps will still be available in dashboards and documents. Using maps in reports is a useful tool for set up and troubleshooting.


Run a report with data that can be mapped

To test the system, run a simple MicroStrategy report that includes a single geographic attribute (such as US State, Country, zip etc) and a small number of metrics.


Configure the map Visualization for the report

In the MicroStrategy report grid view, navigate to open the Custom Visualization menu in Tools menu->Custom Visualizations.

Useful tip:

If you do not see the Custom Visualizations menu option then ensure the project preference to enable Custom Visualization is correctly set (see above).


Click to ‘Enable this report to use custom Visualization’ and then on the left hand side scroll down to select ‘Visual Crossing’ (do not select Visual Crossing Map at this stage – there are two versions for compatibility with various MicroStrategy Web views).



When you press OK, MicroStrategy will load a default map and present you with options on how to display the data on the map.

Configure geometry display options

When the map first runs the map will prompt to configure the geometry display for the attributes on the dataset.

Most data that will be mapped falls into three categories:

  1. The information needed to show the data on the map is part of the grid. For example a dataset that includes the latitude and longitude of the objects to appear on the map.
  2. The information needed to show the data on the map is joined from a well-known existing geometry set. For example displaying US States or European countries on a map.
  3. The information needed to show the data on the map is aggregated from well-known existing geometry sets. For example a Company’s Sales districts that are made up by grouping zip codes together.

In our first example we will use option #2. We want to display US States on the map. In this case we are going to have Visual Crossing look up the boundary information based on well-known geometries. The following dialog describes the options. The first drop down indicates that we will be joining in geometry information based on data contained in the MicroStrategy grid. The datasource in that case is the State attribute and the unique key column is the ‘State column’ (this is used for selections where it’s necessary to identify the unique geographic entities if they are repeated).


When you press the checkmark to apply your changes the map control will automatically create a map based on the metric data available.



Next steps

Congratulations – you now have a working Visual Crossing 4 environment!

From this point you can explore a plethora of visualizations and analytical techniques to enhance your MicroStrategy environment. Here are a few areas you can explore:

  1. Use maps in reports, documents and dashboards to help users consume big data faster and more accurately.
  2. Add data that include latitude and longitude information on to the map
  3. Create aggregate regions for displaying on your map
  4. Create animations to explore time based changes to the data and watch assets moving on maps
  5. Create affinity and route maps by joining information from two layers.
  6. Create sophisticated color code choropleth maps using Visual Crossing sequencing technologies


Have more questions? Submit a request


  • 0
    Maximiliano Perez Feulien

    Just additional info, in case you get an error that Not enough memory is set for Visual Crossing, you should increase de JVM Heap Size for MSTR Web.

Please sign in to leave a comment.