Purpose of this Document
This document provides the steps required to implement an interactive map widget for use within IBM Cognos Business Insight 10.1.1.
The technique outlined in this document only applies to the IBM Cognos Business Insight 10.1.1 and was validated using the:
- GO Data Warehouse(query) package shipped with the samples
This document assumes that the IBM Cognos BI content and file structure has been backed up using a tried and tested method prior to any attempt to implement the technique.
Exclusions and Exceptions
The technique outlined in this document requires the use of undocumented and unsupported capabilities in IBM Cognos BI. As a result the technique and its associated files are provided “as is” and are not considered supported.
Supported Map Vendors
The interactive map widget is able to utilize online maps from the following popular vendors:
- ESRI Maps from ESRI Incorporated (http://www.esri.com)
- Google Maps from Google Incorporated (http://www.google.com)
- Bing Maps from Microsoft Incorporated (http://www.microsoft.com)
Each of the vendors listed above have licensing terms that restrict usage of their respective services. Be sure to adhere to each vendor's terms and conditions before attempting to implement this technique. The default configuration of the interactive map widget uses only publicly available service URLs. No access key or other information is passed to these services until you modify the configuration settings.
Installing the Interactive Map Widget
The attached archive InteractiveMap.zip copies the required files to your IBM Cognos 10.1 BI install location. The steps outlined below will need to be performed on each IBM Cognos BI server and gateway install location within the IBM Cognos BI environment.
Doing the Installation Step by Step
The following steps will install the Interactive Map Widget:
- Stop the IBM Cognos 10.1 BI service if one exists.
- Copy InteractiveMap.zip to your IBM Cognos 10.1 BI installation directory. In this
case the IBM Cognos 10.1 BI installation is a 64-bit Windows installation which was
installed on the C:\ drive with the following installation path:
- Double-click InteractiveMap.zip and unpack to your IBM Cognos 10.1 BI installation directory.
- Start the IBM Cognos 10.1 BI service.
When completed, the installation procedure will have added new files to the ./configuration and ./webcontent folders. No other files are deleted or modified.
Confirming a Proper Installation
Upon successful installation of the InteractiveMap.zip file, an Interactive Map Widget should now be available within the IBM Cognos Business Insight Tools pane. To confirm the existence of this new Tools object:
- Use the Launch menu in IBM Cognos Connection to open IBM Cognos Business Insight.
- Click the Create New button to create a new, empty workspace.
- Click the Toolbox tab. When the Tools pane
displays, an Interactive Map object should now be visible between the
Image and My Inbox objects. This is illustrated in Figure 1.
Figure 1 - IBM Cognos Business Insight Tools pane displaying the Interactive Map object
The Interactive Map Features
The following section describes the features available for the Interactive Map object.
The Map Panel shows a live base map and plotted points. As shown in Figure 2, the Interactive Map object was used to create a widget which displays a map of North America. The data points for the number of customers are displayed as green circles with a size that is proportional to the value being represented.
Figure 2 - Interactive Map widget displaying North American and data points for customers within North America
Standard scrolling, panning and zooming map operations are enabled. Filter sliders are shown in the bottom left corner. These sliders control symbol filter ranges based on different column values. The column names shown control disk size and color range respectively. Different columns can be selected in each drop list.
The map can be customized in several ways. All customizations are saved by clicking the Save icon on the workspace toolbar.
The Options Panel is opened and closed by clicking the Toggle control on the left side of the map. This is illustrated in Figure 3.
Figure 3 Toggle control for the Options Panel
The Options panel shows the following three contained expansion panels:
- View - Display and viewing options
- Maps - Map setup options
- Data - map data grid
The View panel has the following fields:
- Map Actions:
- Click shows popup - Popup box is displayed when map symbol is clicked.
- Mouse over shows popup - Popup box is displayed when mouse placed over map symbol.
- Click filters workspace - Other widget content is filtered when map symbol is clicked. Use Shift-click for multiple selections.
- No actions (display only) - No mouse events are processed.
- Data shown with:
- Pins - Locations shown with push-pin graphics.
- Size – Controls symbol size with a slider that allows you to select the desired size.
- Color – Controls symbol color with a palette that allows you to select the desired color.
- Size and Color – Controls symbol size and color using the slider and palette.
The Maps panel has the following fields:
- Available Maps:
- A list of available maps is shown. Changing the selection causes the associated map to be displayed in the map panel.
- Title Column:
- Controls the title of the fly outs when hovering over the data points on the map.
- Location defined by:
- No Column Specified - No symbols will be shown.
- Latitude and longitude – When this is selected, fields titled Latitude column: and Longitude column: will appear and position values are read from the values in those fields.
- Country Names - When this is selected, a field titled Country names column: will appear and position values are determined by the selected value in this field.
- Place Names - When this is selected, a field titled Place names column: will appear and position values are determined by the selected value in this field.
- (X,Y) coordinates – When this is selected, fields titled X coordinate column: and Y coordinate column: will appear and position values are read from the values in those fields.
The Data panel, as shown in Figure 4, shows the underlying items for each plotted symbol.
Figure 4 – Data panel showing the underlying data items used to plot the symbols
Selecting an item in the list, selects the associated map symbol.
Checking and un-checking an item shows and hides the associated map symbol.
When an item name is not found in the system lookup table, a warning symbol is shown next to the name (as shown in Figure 5).
Figure 5 – Data items list highlighting the items that were not found with a warning symbol
Using the Interactive Map Widget
The Interactive Maps object shows points and data using a source IBM Cognos list report. The list report must have location references in one of the following formats:
- Numeric latitude and longitude
- Name of a country
- Name of place like a province or state
The following sections will step a user through the creation of the report and creating an IBM Cognos Business Insight dashboard that uses the Interactive map object.
Authoring a Map Compliant Report
The following section outlines the steps required to build a list report within IBM Cognos Business Insight advanced to be used by the Interactive Map object.
- Within the IBM Cognos Connection Launch menu select Business Insight Advanced.
- When prompted to select a package, locate and select the GO Data Warehouse(query) package.
- Within the Business Insight Advanced Welcome page click on Create New.
- Within the new dialog box, click the List object and then click the OK button.
- Click the title and enter Sample Map Report 1.
- Drag and drop the following Sales and Marketing (query) > Sales (query) items to the report container:
- Retailers > Retailer Country
- Sales Fact > Planned revenue
- Sales Fact > Revenue
- Sales Fact > Gross Profit
Figure 6 - IBM Cognos Business Insight List report displaying the data points to be used by the Interactive Map object
- Click the Save button.
- Type the Name: Sample Map Report 1.
- Upon clicking the Save, the report can now be used to build an interactive map visualization.
Authoring a new Interactive Map
In the following section, the previously created report will be used to create an interactive map.
- From the IBM Cognos Connection Launch menu select Business Insight.
- Within the Business Insight Welcome page click on Create New and choose the Blank report template.
- Locate and drag the previously created and saved Sample Map Report 1 onto the canvas. Once the canvas refreshes, it will display the Retailer country, Planned revenue, Revenue and Gross Profit list report with its associated values. This is illustrated in Figure 7.
Figure 7 - IBM Cognos Business Insight canvas with the List report dragged on to the canvas
- Within the right hand pane select the Toolbox tab, then locate and drag the Select Value Filter item to the canvas, placing it to the left of the list report.
- Within the Properties - Select Value Filter dialog, type the text Select Country for the Show descriptive text: entry at the bottom of the dialog.
- Click the OK button to add the value filter to the canvas. When completed, the canvas should now display a value filter displaying all the Retailer country values on the left hand side of the canvas. The right hand side of the canvas will display the List report filtered to the selected value filter values. This is illustrated in Figure 8.
Figure 8 - IBM Cognos Business Canvas displaying the value filter and List widget
- Within the right hand Toolbox pane, locate and drag the Interactive Map object and drag it onto the canvas between the value filter and the list object.
- When presented with the Properties - Interactive Map dialog, click
the Browse and select the previously created Sample Map Report 1 list report. The Interactive Map widget will now be shown on the canvas between the left hand value filter and the right hand list report object. This is shown in Figure 9.
Figure 9 - IBM Cognos Business Insight canvas displaying the value filter, the Interactive Map and the List widgets
Server Configuration Options
The section describes how to customize the types of maps displayed by the Interactive Map widget.
Maps service URLs are defined in the file:
<map> element is used to define each
<map> item shown in the interactive map panel. Items are
shown in the order defined in the configuration file.
<map> elements can be added or removed as required.
<map> sub-elements can also be changed to reference custom URLs or alternate display names.
ERSI Maps Configuration
The URL for ESRI map services can be changed in the file:
Changes can be made to any
<map> element with
sub-element equal to
Layer overlays can be added an ESRI map using the
<Layer4> sub-elements. The
<key> sub-element for any
<map> element can be used to define a system-wide access key.
Google Maps Configuration
The system-wide access key for Google services is defined in the file:
The variable var google_key = "" is used to set your required Google key value.
Microsoft Bing Maps Configuration
The URL for BING map services can be changed in the file:
Changes can be made to any
<map> element with sub-element equal to
<key> sub-element for any
<map> element is used to define your required system-wide key.
By default, the interactive map widget displays a warning across the bottom of the map reminding the user that they must comply with the respective map vendor’s license terms. This message can be suppressed after an administrator has determined that all the license terms have been met for all users.
To suppress this warning change the
<licensed> tag value
from False to True in the file:
The interactive map widget uses a server-side lookup table to match country names with average geographic latitude and longitude or the approximate visual center of a given country. This comma separated text file is stored in:
This file may be edited as required. The column with heading LOOKUP is used to search for exact name matches. The columns with headings LATITUDE and LONGITUDE are used for positional coordinates.
The data in this file is provided "as-is" and is sourced at the time of publishing from http://www.naturalearthdata.com/ under the Natural Earth Terms-of-Use described at http://www.naturalearthdata.com/about/terms-of-use/.
The interactive map widget uses a server-side lookup table to match arbitrary place names with average geographic latitude and longitude or the approximate visual center of a given place. It initially contains state and province names for selected countries. This comma separated text file is stored in:
This file may be edited as required. Any named place or entity can be added. The column with heading LOOKUP is used to search for exact name matches. The columns with headings LATITUDE and LONGITUDE are used for positional coordinates.
This file may be edited to modify any of the columns provided. to the file as required. The data in this file is provided "as-is" and is sourced at the time of publishing from http://www.naturalearthdata.com/ under the Natural Earth Terms-of-Use described at: http://www.naturalearthdata.com/about/terms-of-use/.
|Interactive Map Widget archive||InteractiveMap.zip||897KB|
Dig deeper into Business analytics on developerWorks
Experiment with new directions in software development.
Tips for improving outcome and controlling risk.
Software development in the cloud. Register today and get free private projects through 2014.
Evaluate IBM software and solutions, and transform challenges into opportunities.