Define Shapefile and Data Order Keys in CMaps Plugin

Want a complete overview of using Shapefiles with CMaps Analytics? Visit our Shapefile Learning Center

Why Shapefile Keys are Important

A Shapefile (.SHP) has a very specific structure for loading boundary data, which in most cases will not perfectly match your business data. This is an important aspect of CMaps Analytics process to benefit from the compression and speed of Shapefiles while offering the flexibility to load and blend your business data.

For example, while a region name may be defined as “United States of America”, your business query may use “United States” or “USA”. Shapefile keys grant the flexibility to ensure geographic data can seamlessly bind to your business data.

Shapefile and Data Order Keys

Built into CMaps Plugin and GMaps Plugin is a simple Shape File key property that uses a specific, rigid structure provided by the Shapefile’s DBF file. Learn more about the anatomy of a Shapefile. The Data Order keys comes directly from your business data, which is simply a list of the boundaries that you want to view in your map. You will learn how to use both of these properties together to display and filter geographic boundaries in your map.

Shape File Order Keys

The Shape File Order Keys are obtained directly from the DBF file, or can also be obtained from our Shape Data Explorer utility and will 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. 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.


You can obtain Shapefile order keys directly from a Shapefile DBF file (Database file), which can be easily extracted (view tutorial). This ships alongside most shapefiles. If you obtain data from Centigon Solutions, we also provide DBF keys as a simple CSV file so you can copy and paste directly into your dashboard.

Visit our Shapefile Explorer to find Shapefile Order Keys 

IMPORTANT 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 originate from your business data. Data Order keys property is a single column of data that directly controls the visibility of regions within a Shapefile.

For example screenshot below, lets assume that we load a “World by Country” Shapefile that contains over 250 countries in the Shape File and Shape File Keys column. (see example Shape File Key data). If we only loaded the following 4 countries from SAP BusinessObjects into our dashboard, the Data Order Key will ensure that only the 4 geographies appear on the map.

order keys

The Data Order Keys are extremely important because they also dictate the order of all data loaded into the map layer 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 and Shape File Keys contains “United States of America�. In these scenarios you can modify your Shape File Keys to ensure the right locations appear in your map. 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. This range should be copied directly from the DBF file or from our Shape Data Explorer and should not be re-ordered.
    Note: The actual values from the DBF file can be changed to meet the requirements of your data source. For example, if the DBF file value is “United States of America,â€� you can modify the value to “USAâ€� to ensure when your business data is linked and bound to “Data Order Keys” USA boundary will appear.
  4. Bind the Shape Data Key to a data range where your BusinessObjects queries will return data or where your static Excel data is located. The presence of locations in the Data Order Key column will cause boundaries to automatically appear.dataorder

CRITICAL NOTE FOR BINDING DATA ORDER KEYS: When binding the Data Order Keys, you will need to ensure the total number of rows bound is the same number as the Shapefile Keys. This ensures that your dashboard application can accommodate the total number of Shapes within a file. So if your Shapefile Keys property is bound to 250 rows, your Data Order Keys property must also be bound to 250 cells.

In addition to Data Order keys requiring additional row bindings, you must also bind the following properties to accommodate the total number of records allowed through the Shapefile Keys

– Labels
– Values
– Selector Source property
– Alerts Targets property

For example screenshot below, lets assume that we load a “World by Country” Shapefile that contains over 250 countries in the Shape File and Shape File Keys column. (see example Shape File Key data). Even though we want to only display 4 counties as pictured below, we still have to bind our Data Order Keys to a total of 250 cells, even if they are blank.

order keys