CMaps Plugin (formerly GMaps Plugin) supports direct connectivity to ESRI Shapefiles (.SHP) which provides instant display of custom territories, polygons, administrative areas, shapes, thematic maps, or routes within CMaps Plugin

What is a Shapefile?

The ESRI Shapefile or simply a shapefile is a popular geo-spatial vector data format for geographic information systems (GIS) software. The standard was developed and regulated by ESRI as an open specification for data interoperability among ESRI and other software products. The benefit of a shapefile is that it is highly compressed and portable, enabling software applications to load large volumes of binary, geographic data.

Shapefiles are made available with many popular GIS solutions. There is a lot of data made available on the web, most commonly from organizations like CDC, or local governments. In many cases, boundary files are freely available on the internet. If your organization currently uses a GIS solution like ESRI or MapInfo, you can consult with your GIS solution expert. If there are specific shapefiles that your organization requires for development, please contact support.

When obtaining your Shapefiles, you will typically get a minimum of 3 files:

  • SHP- The SHP file contains the data required to plot data points that make up the shapes. The .SHP file is linked directly to GMaps Plugin, where it is rendered as a layer.
  • DBF- Database file table contains all of the meta data that describes each individual shape in the .SHP file. The DBF is extremely important because the SHP file does not contain any meta data required for labels in your map.
  • SHX- Index file used to combine SHP and DBF file for GIS solutions. This file is required to maintain the integrity of the files when used with GIS solutions. GMaps Plugin does NOT utilize the SHX, but it is important to keep all 3 files together in case if you need to edit the shape data within a GIS solution.
    Learn more about Shapefiles from the ESRI Shapefile Specification

Shapefile Requirements for use with GMaps Plugin
View Troubleshooting Guide

  • GMaps Plugin only supports the Polygon and Polyline shape types.
  • Shapefile projection should be WGS 84
  • Shapefile sizing should be less than 2MB for the best dashboard performance

Shapefile Requirements for use with GMaps Plugin
View Troubleshooting Guide

  • GMaps Plugin only supports the Polygon and Polyline shape types.
  • Shapefile projection should be WGS 84
  • Shapefile sizing should be less than 2MB for the best dashboard performance

At Centigon Solutions, we have prepared common geo-data and collected resources for you to locate and download geo data in Shapefile format.

Free Geo Data Resources

GMaps Plugin will display the contents of .SHP files but does not provide any utilities for editing or manipulating shape data. For this we recommend using a GIS tool like ESRI ArcGIS or free open source tools like Quantum GIS. Both of these solutions will enable you to merge, delete, simplify, or re-project shapes to work well with GMaps Plugin.
TUTORIAL: Editing Shapefiles with Quantum GIS

Creating your own Regions and Territories

Most organizations operate with custom territories or geographic regions. Shapefiles provide the perfect base for editing and compiling custom regions. Quantum GIS basic GIS capabilities for merging and saving Shapefiles. CMaps Region Creator, provides automation to the region/territory creation process.
View CMaps Region Creator

Connect .SHP file to CMaps / GMaps Plugin
To visualize one or multiple shapefiles into your dashboard, you will first need to upload your shapefiles onto any web/application server. This needs to be a web application server that is accessible via HTTP. Ultimately, you need to be able to access the shapefile as a URL (http://yourwebserver/yourfile.shp). If you are publishing your dashboard (SWF) to a web server, shapefiles are only accessible via HTTP and will not work if the shapefile is on your local computer or file share.

For testing and development: Shapefiles can be loaded onto your local PC (FILE://yourfile.shp) for testing, though it is recommended to load the files onto your web/application server behind your corporate firewall. If you happen to use Shapefiles on your local PC for testing, you need to enable local Flash Security settings in Internet Explorer.

  1. Open CMaps / GMaps Plugin Property Sheet
  2. For any series, select the “Shape Data”
  3.  Select the configuration icon
  4. Select Shape Data
  5. Click “OK”
  6. With the standard properties showing you will now need to obtain a URL to a shapefile and paste it into a single cell within your Excel model. For testing you can use the following world shapefile: “http://gmapsplugin.net/shapes/countries/countries.shp”
  7. Bind the “Single shape file URL” property to a URL to your URL

Note: When binding a .SHP file path to your local PC:
You need to ensure that your local flash player security settings allow access to the drive for which your .SHP is loaded. Hosting shapefiles on your local machine will NOT work if your SWF file is opened from a file share, or from a server.

Note for Shapefile Server Deployment:
The web server will require a crossdomain.xml file for GMaps Plugin to successfully access and load the .SHP (or .TXT) file. A crossdomain.xml file should be placed into the ROOT directory of your web/application server.
Download sample crossdomain.xml policy file. If your IT organization needs an explanation of the crossdomain policy file, Adobe covers it in this CrossDomain.xml article.

  1. Save your dashboard before previewing
  2. Preview your dashboard to ensure the Shapefile loads in the map.

Extracting Shape Labels from DBF File
With a shapefile successfully rendered in CMaps Plugin or GMaps Plugin, now you will need to link labels to identify each individual shape. With all of the metadata (state, country, zip, etc) information contained in the DBF file, you will need to extract that information. CMaps Plugin does not currently support a direct import of a DBF file. Instead you can easily open up the DBF file in Excel and extract only what you need.

  1. Open Excel
  2. From inside of Excel, Click Open
  3. Set the file type to “ALL Files”
  4. Open the DBF file (Get an example results from a DBF file for Countries.shp)
  5. Copy the column(s) of data that you will use as unique identifiers (DBF Keys). Many times the filed will be an “ID” or “Name” which will identify each shape within the shape file.

    NOTE- Do NOT change the sort order of the DBF file when importing to SAP Dashboards (Xcelsius). If the sort order for the data is not desirable, you will adjust it in Step 5 inside of SAP Dashboards / Xcelsius.
  6. Paste the column(s) from Excel into Xcelsius.NOTE- If you obtain a CSV file containing the locations from Centigon Solutions, you can simply paste the contents into your SAP Dashboard / Xcelsius.

Define Shapefile and Data Order Keys

A Shapefile has a very specific data index/order that will NOT match your business data queries. Furthermore, there is no guarantee that your business data or query will contain all of the locations inside of a Shapefile. Built into CMaps Plugin and GMaps Plugin is a simple Data to Shape Linking & Visibility feature that simplifies this connection. You will first bind Shape File Order Keys which is a definition of all shapes inside of your shapefile. Then you will link corresponding column of data with your business data with corresponding keys.

For example, if the contents of a DBF file are listed as: “AZ, CA, NM, KY”

And the business data is listed as “CA, NM, AZ”.

We need the map to show 3 regions and ensure that the right data is mapped to the correct location. That is where the Data to Shape Linking & Visibility properties become critical to your success.

Shape File Order Keys

The Shape File Order Keys are obtained directly from the DBF file and contain a complete, distinct range of values obtained directly from the DBF file. The DBF file contains the labels/ids for each shape within a shape file and can be opened. (learn how to extract DBF data). Upon extracting the DBF data from the shapefile and binding it to the DBF key property, you can change the values but NOT the sort order.

Note: When you bind Shape File Order Keys, make sure to select the entire range and that you count how many records are selected. This information is very important for your data order keys

Data Order Keys

Data Order Keys define the data and ordering of business data, typically returned from your BI query. When you bind the Data Order keys, they will need to contain the same contents as the Shape File Order Keys, but can be in any order.

When a Data Order Key matches to a corresponding Shape Data Key the shape will appear. Otherwise the shapes are NOT displayed. The Shape Data Keys will define the data order for other GMaps Plugin properties including:

  • Address/Long,Lat
  • Labels
  • Values
  • Selector Source Data
  • Selector Position
  • Colors (alerts tab)
  • Alerts Targets (when using % alerts)

Editing Data Order Keys to Match Shapefile Keys

A common scenario experienced after connecting Shapefile and Data Order keys is that certain shapes will not appear in the map. This is because your business data may not match the Shapefile keys. For example, your BI Query may return “United States” when the Shapefile DBF contained “United States of America”. In these scenarios you can modify your Shape File Keys to ensure the right locations appear. This built in flexibility is a benefit of using Shapefile Keys.

Process for Data to Shape Linking & Visibility

  1.  Select the configuration icon from the CMaps Plugin / GMaps Plugin property sheet
  2. Click on “Shape File URL”
  3. Bind the DBF Key to a data range obtained from the DBF file.
    Note: The actual values within the DBF key can be changed to meet the requirements of your data source so you can modify the DBF key to match what your dashboard queries return. For example, if the DBF file value is “District of Columbia,” you can modify the value to “DC” without impacting the dashboard.
  4. Bind the Shape Data Key to a data range where you will control what shapes are visible from the .SHP file.

CRITICAL NOTE: When binding the Data Order Keys, you will need to ensure the total number of cells is the same number as the Shapefile Keys. For example, if your DBF file/Shapefile Keys contain 50 states, the Data Order Keys property needs to be bound to 50 cells, even if your BI query is returning 10 states at a time. In addition, when you bind labels, values, alert targets, and selector options they will also need to have a range of 50 cells to ensure the map can lookup and match data properly.