Purpose of this document
This document provides the steps required to implement an Interactive Map Widget for use with IBM Cognos Workspace 10.2.1 and 10.2.2. Earlier versions of IBM Cognos Workspace will not work with this version of Interactive Map Widget.
The technique outlined in this document was validated using the:
- IBM Cognos Workspace 10.2.1 using the GO Data Warehouse(query) package shipped with the samples
- IBM Cognos Workspace 10.2.2 using the GO Data Warehouse(query) package shipped with the samples
This document assumes that the IBM Cognos Business Intelligence (BI) content and file structure has been backed up using a tried and tested method prior to any attempt to implement the interactive map widget.
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.
Map vendors used by the Interactive Map Widget
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 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 BI service if one exists.
- Copy the correct version of the InteractiveMap.zip to your IBM Cognos 10 BI
installation directory. In this case the IBM Cognos 10 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 BI installation directory.
- Start the IBM Cognos 10 BI service.
When completed, the installation procedure will have added new files to the ./configuration and ./webcontent folders. No other files are added, 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 Workspace tools pane. To confirm the existence of this new Tools object:
- Use the Launch menu within IBM Cognos Connection to open the IBM Cognos Workspace.
- 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 Workspace Tools pane displaying the Interactive Map Widget
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 widget 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.
- Mouseover 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 based on specified column values.
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 the creation of an IBM Cognos Business Insight dashboard that uses the Interactive map widget.
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 widget.
- Within the IBM Cognos Connection Launch menu select Cognos Workspace Advanced. When prompted to select a package, locate and select the GO Data Warehouse(query) package.
- Within the Workspace 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 Workspace 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.
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 Cognos Workspace.
- Within the IBM Cognos Workspace 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 Workspace 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 Workspace Canvas displaying the value filter and List widget
- Within the right hand Toolbox pane, locate and drag the Interactive Map Tools 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 Workspace canvas displaying the value filter, the interactive map and the Report Viewer 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
item shown in the interactive map panel. Items are shown in the order defined in the
<map> elements can be added or removed as
<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
<provider>ESRI</provider>. Layer overlays can be added
an ESRI map using the
<Layer1>, <Layer2>, <Layer3>
<Layer4> sub-elements. The
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:
var google_key = "" is used to set your required Google key
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
sub-element for any
<map> element is used to define your required
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/
New Features in IBM Cognos Workspace 10.2.2
IBM Cognos Workspace 10.2.2 Report Viewer can now filter the Interactive Map Widget allowing dashboards to be optionally built without the requirement for a filter widget. The following sections provide the steps to use the report to filter the map and use the map to filter the report.
Using report to filter map
Report filtering is enabled by clicking the Master filter icon on the viewer toolbar (Figure 10).
Figure 10. Master filter icon displaying the Master filter tooltip
Upon enabling this feature, the map can be filtered by selecting one or more List values. The map will show items that match the selected item names. In Figure 11 Alberta, Newfoundland, Nova Scotia and Ontario have been selected in the List object. The corresponding Map object has been filtered accordingly display the appropriately sized blue measure circle over the North American provinces.
Figure 11. List report with selected values used to filter the map object
Using map to filter report
The map can be configured to filter other widgets by selecting the Map Actions > Click filters workspace menu item, in the map flyout panel. This map flyout panel is depicted Figure 12 showing the available options of Click shows popup, Mouseover shows popup, Click filters workspace and No actions (display only).
Figure 12. Map Actions flyout panel
In Figure 13 we see the provinces of Alberta, Newfoundland, Northwest Territories and Ontario were selected within the map widget using a shift-click action. The Report Viewer widget displaying the List has been filtered accordingly and only displays the selected provinces.
Figure 13. Map widget with the selected items filtered in the Report Viewer widget List report
Interactive Map Widget Logging
Map widget display and data import issues can be debugged using the Trace Output option available in all supported versions of the Firefox and Chrome web browsers. Limited trace options are available in Internet Explorer 9 or higher.
Trace output (interactive)
Interactive trace output can be selected once an Interactive Map Widget is placed on the IBM Cognos Workspace canvas. The trace data display is enabled on the Options Panel > Maps tab as illustrated in Figure 14.
Figure 14. Maps dialog box displaying the Debug mode drop down list
The Debug mode field to selects the following functions:
- Off (default) - No trace information is generated. This is the most efficient mode of operation and should be used when debug trace information is no longer required.
- Browser Console - Trace information text is sent to the developer console window in a Firefox, Chrome or Internet Explorer web browser. The appropriate development tools plugin(s) must be installed for the browser prior to selecting this option. The option will not be shown if a debug console is not available.
- Popup Window – Trace information text is sent to a browser popup window. This is the easiest trace option to enable. It works in all supported Firefox and Chrome web browsers. This option is not enabled for Internet Explorer web browsers.
Trace output (static)
If trace output is desired prior to launching a map widget, the following procedure can be used.
- Locate and backup the following file:
- Using a text editor, modify that line that defines variable
sage.Trace.Startup. The default value for this variable is
sage.Trace.Startup = “off”;.The assigned
sage.Trace.Startupvalue, in quotes, selects the following function:
- off (default) - No trace information is generated.
- console - Trace text is sent to the developer console.
- window – Trace text is sent to a popup browser window in Firefox and Chrome web browsers. Trace text is sent to the developer console in Internet Explorer.
- Save the changes and restart the IBM Cognos BI service. The selected trace
options will be used the next time a map widget is used within IBM Cognos
Trace.jsfile should be restored to its original state when trace display is no longer needed.