Tip or Technique

Report Studio Workshop - Maps

Product(s): IBM Cognos 8 Area of Interest: Report Design

Report Studio Workshop - Maps

Copyright Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to the information contained in this document will be documented in subsequent editions. This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos. Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries, or both. All other names are trademarks or registered trademarks of their respective companies. Information about Cognos products can be found at www.cognos.com This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to [email protected] .

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

Contents
1 1.1 1.2 1.3 2 3 3.1 3.2 3.3 3.4 4 5 6 6.1 6.2 6.3 6.4 7 7.1 7.2 8 9 10 11 12 13 13.1 13.2 14 INTRODUCTION ............................................................................................ 4 PURPOSE ............................................................................................................4 APPLICABILITY .....................................................................................................4 EXCLUSIONS AND EXCEPTIONS ..................................................................................4 REPORT STUDIO MAP THEORY ..................................................................... 4 REGION LAYERS............................................................................................ 5 DISPLAY LAYERS ...................................................................................................8 FILL EFFECTS ..................................................................................................... 10 MAP TITLES ...................................................................................................... 14 REGION LAYERS .................................................................................................. 18 PRE-DEFINED PALETTES............................................................................. 25 POINT LAYERS ............................................................................................ 27 MAP DICTIONARY....................................................................................... 36 OVERVIEW ........................................................................................................ 36 CREATE ALIASES IN REPORT STUDIO ......................................................................... 37 CREATE ALIASES IN MAP MANAGER .......................................................................... 42 MORE ABOUT MAP MANAGER .................................................................................. 46 MAPS AND MULTILINGUAL APPLICATIONS ............................................... 47 BINDING QUERY DATA TO THE MAP DICTIONARY .......................................................... 47 USING MAP MANAGER FOR TRANSLATIONS.................................................................. 49 DRILL THROUGH ON MAPS......................................................................... 55 MAP LEGENDS ............................................................................................. 59 NOTES ......................................................................................................... 61 CUSTOM PRE-DEFINED PALETTES .............................................................. 67 ADDING CUSTOM MAPS.............................................................................. 73 NOTES ABOUT MAPPING TECHNOLOGY ..................................................... 73 MAPINFO AND COGNOS......................................................................................... 73 MAPINFO GST FILES ........................................................................................... 74 CONCLUSION .............................................................................................. 74

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

1 Introduction
1.1 Purpose This document provides a step-by-step review of the main features associated with maps and their use in Report Studio. Applicability The features discussed are available in IBM Cognos 8. This document has been updated for the MR2 release. Exclusions and Exceptions This workshop is designed to operate in an English locale only. We will discuss map localization later in this workshop. In the meantime, please set your preferences in IBM Cognos Connection (and therefore Report Studio) to English.

1.2

1.3

2 Report Studio Map Theory

Maps are created in non-IBM Cognos applications such a MapInfo and ESRI1. These products allow one to specify many different sets of information within a map. IBM Cognos supports a small and well-defined subset of the capabilities of these products to allow you to display numeric results by location within a map. Report Studio supports two layers types that are defined with a map: regions and points. Region layers are areas on the map like continents, countries, states. Regions are of arbitrary shape as determined by the map requirements. Points are spots on the map such as cities, factories, stores and the like. Points are always displayed as circles. The map definition may contain an arbitrary number of layers of the two layer types. Report Studio operates on a three-layer model using the region and point layers for dual purposes. It is up to the report author to determine which layers are to be used in any given map. 1. Region layer a. Color code areas on the map to compare values b. Report Studio allows one per map within the current report c. Example: Countries 2. Point layer

Maps are imported into an IBM proprietary format before use. IBM Cognos can import maps from the MapInfo format only. Maps from other vendors can generally be converted using non-Cognos tools into the MapInfo format and then imported by IBM Cognos. IBM does NOT ship the MapInfo source data. If you wish to create your own maps you will need to use the mapping software available from vendors such as MapInfo and ESRI.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

a. Color code or size circles on the map to compare values b. Report Studio allows one per map within the current report c. Example: Cities 3. Display layers a. Show additional map details to provide context to the reader b. Report Studio allows 0, 1 or more per map within the current report c. Example: On a map showing data by country, also display the capital cities (with no data by city). Lets look at each of these in turn to see how they can be used.

3 Region Layers
Regions are areas on the map such as continents, countries, states, etc. You use regions with a measure to compare the values of that measure across regions using contrasting colors. For example, the countries on the world map are regions against which we map sales success. Green is good in this example.

Regions can be color coded based on a measure such as quantity, revenue, profit, etc. The minimum and maximum measure quantity values by country will be calculated and colors assigned accordingly. Lets create a simple map in Report Studio to see how the map system operates.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Open Report Studio with the GO Sales and Retailers package2 and create a new Map report. We would like to compare revenue by country for the whole world, so select the World map.

Since we want to show revenue within each country, select Countries + Territories as the Region Layer. We have no requirement for a point layer yet, so leave Point Layers set to (None). Likewise, we have no requirement for a display layer, so do not select any display layers.

Click OK to complete the basic map definition. You can now see that Report Studio allows you to define the details for the layer you specified:

This is a sample package that ships with IBM Cognos 8 and can be installed by your administrator.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

If you had decided to add a point or display layer, you would also see them appear in the map prototype. Lets examine the Region layer details:

1. Region layer: A selectable object used to access the properties of the region such as the palette. 2. Color: The measure, such as Revenue, which drives the layer values. 3. Location: The data item, such as Country, that binds the data to the chart regions (the names in the data must match the names in the chart dictionary). 4. Color Legend Title: The text that will appear as the legend title Again, we wish to show revenue within each country. The next step is to define the data items which will populate the map. Drag \Orders\Revenue measure into Color. Drag \Countries\Country to Location.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps As soon as you set the Location, a new element Refine Location appears as so:

Refine location is used with a second data item to qualify the location where the location is not unique. For example, the cities with the names Paris, London, Halifax, Sydney, and others appear in multiple Countries around the world. The Refine location is used to qualify the duplicate values and make them unique so that one instance of Paris can be distinguished from another. Since the Country names are unique, there is no need to use this element for this chart. Run the report to see the result:

In all, this is a quick process to plot the revenue by country for the entire world. However, the map might be even nicer if the ocean was colored blue. 3.1 Display Layers Lets take a quick sojourn into display layers for a moment. You can select one or more region or point layers defined within the map as display layers. These are layers which are displayed on the map for added context or to improve the appearance but do not show query data. In some maps, there are display only layers. In the world map for example, the Ocean layer cannot be used to plot data. But generally any region or point layer not used to display data can be used as a display layer. You can select zero, one or more display layers.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

Return to Report Studio. Select the Map and select the Map and Layers property.3 Select Oceans as the display layer.4

3 4

You can also right-click on the map and select Edit. Note that you can select/unselect multiple display layers by shift and control click.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

10

Click OK to return to the report layout. Report Studio now shows the Display layer in the map prototype as so:

Run the report.

The report looks much nicer with a pretty blue color filling in the oceans of the world. 3.2 Fill Effects You may also wish to change the un-used region color to something specific.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

11

Return to Report Studio and select the Region Layer:

Select the Fill Effects property:

As you can see the fill defaults to the light grey color. You can set it to a color, a gradient or a pattern. Click Gradient. Click OK to accept the default black and white gradient. Run the report.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

12

Note that the countries with no data appear in the black and white gradient:

Return to Report Studio and select the Map. Edit the Fill Effects property to use a Color and set the color to Silver. Run the report:

Return to Report Studio.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

13

Perhaps we would like to see a richer blue for the ocean. To do so, select the Ocean display layer:

Select the Fill Effects property and set the gradient down from Blue to Aqua:

Run the report:

The pale blue was lovely before but this is marvellous. Return to Report Studio and keep this report open for the next section.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps 3.3 Map Titles The various titles that can appear on the map are:

14

As with charts, these titles can contain static text or data values. By default, the only title that appears on the map is the axis title which is set to the map name. There is both a Legend Title that applies to all legends and a title specific to each color or size legend.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

15

A map with multiple measures will have multiple legends, each with its own Color or Size Legend Title as in this example:

Note that the legend title is a map property and the color and size legend titles are legend properties. To access the legend properties, select the region or point layer object: Lets add some titles to our map. Select the Map and set the Title property to Show. The map prototype now shows the titles:

As with chart titles, all map titles are actually rectangular areas into which you can drop multiple text objects.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps A text object can have any one of several different sources:

16

By default, Report Studio places a single text object into the map title for you. As the text object is currently empty, Report Studio displays the text Double click to edit text. Select the text object in the chart title and set the text to Total Revenue: . Note the trailing space after the colon. Drop the Revenue query item into the title area after the text object. Your map should look like this:

Run the report. The text and Total Revenue for the report are shown:

Styles (font, etc.) can only be applied to the entire title, thereby affecting all objects within. You can apply a data format to each of the items in the title, not the title itself. Select Revenue in the chart title. Examine the properties and you will see there is a Data Format property but no style properties such as font. Select the Chart Title object. Note there are style related properties such as Font but no Data Format property. Set the Font of the Chart Title to Times New Roman, size 14, Bold.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

17

Run the report:

The child text objects inherit the style from the parent title object5. This inheritance of properties is not specific to maps. This is how all reports operate. Styles applied to parent objects are inherited by the child objects. This is really a reminder for anyone who had forgotten this lesson. Select the map object and set the Foreground Color to Yellow. Run the report:

The Yellow is inherited by child objects that also support foreground color property.

A note about font usage in maps (and charts): the text processing in maps and charts is does not support emulation of font attributes not supported by the true type font. So, while font user interface may allow you to specify italic or bold text, if there is no support for these attributes in the true type font then the specification will be ignored. For more information, please see Report Studio Workshop 3 Charts.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

18

You can also set a background color on the map. To do so, you must remove the map fill effects to allow the image to appear through the transparent map background. Images are stretched to the size of the map. There are no sample images with IBM Cognos 8 that show this feature off nicely so we will move to the next topic: layers. 3.4 Region Layers Returning to our map, how did Report Studio know to divide the chart (legend) into 3 colors Red, Yellow and Green? The legend colors are determined based on how the palette for a given layer is defined. Each layer has its own palette. Return to Report Studio and click the region layer to select it:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select the Palette property to open the palette dialog. We did not define a palette, so a default palette is used:

19

This palette says: Regions (Countries) who values are in the bottom 33% of the maximum value of the Color (Revenue measure) are to be displayed in Red Regions (Countries) who values are > 33% but <= 66% of the maximum value of the Color (Revenue measure) are to be displayed in Yellow Regions (Countries) who values are > 66% of the maximum value of the Color (Revenue measure) are to be displayed in Green. In other words, simple traffic light style data presentation; Green is good (high) and Red is bad (low). Report Studio will calculate the maximum value for you automatically.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps The Palette Type information at the top of the dialog is most interesting:

20

Report Studio supports both Discrete and Continuous colors. In other words, the colors can be individual colors such as Red, Yellow, Green or gradients such as Red through Green . Furthermore, the Percentage option determines whether the numeric divisions between ranges are based on actual data values or percentages of the maximum value. Since weve seen Discrete colors with the default settings, lets take a look at Continuous colors (gradients). Select the Continuous Colors option:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

21

As you can see, Report Studio will now assign gradients of the specified colors to show a finer comparison of values between regions. Click Ok and run the report:

Did we really get the result we wanted? Return to Report Studio. The default palette was discrete percentages with transitions at 33% and 66%. We simply changed the palette from discrete percentages to continuous percentages. Does that really give us the result we want? Take a careful look at the legends from the last two times you ran the report: Discrete Percentage Continuous Percentage

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

22

If you look carefully at the colors of the Continuous Percentage you will see that the green color dominates the scale. In fact, the green is applied all the way from the 66% marker to the end of the scale.6 Lets go back to the palettes defined in the report:

Was changed to

In earlier releases of IBM Cognos 8 the continuous percentage legend would render from 0 to the top boundary. In the example above the legend would show values at 0%, 33%, and 66%. This could be corrected by adding another palette color at the 100% mark. The legend would then display the value at the 100% measure value for the map.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

23

Look at what this palette says. If the value is greater than 0% and less than 33% display as a gradient from red to yellow. If the value is greater than 33% and less than 66% display as a gradient from yellow to green. If the value is greater than 66%, show the value as green. This is what we asked for and this is what we got. We didnt ask for a transition from the 66% marker to the end so the color is a solid green all the way to from 66% upwards. What we really want is to have a smooth transition from 0% (red) to 50% (yellow) and finally to 100% (green). Change the palette values as so:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Now, run the report:

24

This displays the appropriate color scales now and the green portion of the legend is equally scaled to the other two colors. We can actually even play some cool tricks with the palette depending on what the user wants to see. For example, if the user wants to see all values below 30% as red, all values greater than 70% as green with a transition from Red to Green, we could do this:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

25

If the user also wanted a red to yellow to green transition, we could do this:

If you have specific values to test against, you can manually encode specific values by de-selecting percentage. The values must be hard coded; there is no option to drive the values off the data. When using continuous colors, only colors such as Red, Yellow or #345464 can be used as we must calculate the gradient between the colors. This means you cannot use patterns or gradient colors within the gradient. What would a gradient from would a gradient from to this to this mean? What mean?

We can use patterns and gradients as discrete colors of course.

4 Pre-Defined Palettes
Report Studio also pre-defines some palettes you can use. These are defined to fit in with the IBM Cognos Connection skins with similar palettes to the Cognos Connection Classic, Contemporary and Modern skins as well as a set of additional palettes. Note that you can also create custom chart palettes. By aligning the map and chart palettes, you can, as we have done, create complementary color schemes.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select the Region Layer in the map and the palette property. Open the Palette drop down to view the sets of pre-defined palettes. Note there are tool tips which describe each palette.

26

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select the Modern palette and run the report:

27

To return to the default palette, select the Corporate palette.

5 Point Layers
Points define sites on the map such as cities, manufacturing plants, or other locations of interest. Points appear as circles that can be color coded and/or sized according to a measure value. For example, we might show cities in different colors to indicate comparable revenue with different size circles to show comparable product quantity. Lets use North America as our example this time.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

28

Open Report Studio with the GO Sales and Retailers model and create a new Map report as so:

Be sure to select exactly the above items. Drop \Orders\Revenue as the Color.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Drop \Retailers\City as the Location:

29

Run the report:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

30

You might be asking yourself why an error occurs. Our GO Sales and Retailers data contains information from cities all around the world. Our map has only North American cities. This means we have query data for which there are no matching cities in the map. By default, this is flagged as an error as you have just seen. In other words, the error message is telling you that your query data does not match the map youve chosen. We can tell IBM Cognos 8 to ignore this error in which case the extraneous data is not charted. Select the map and set the Ignore Data with No Features property to Yes. Run the report:

Alternatively, and more correctly, we could have filtered the query to ensure that is only contained data from North America. Next, lets try changing the point size.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Drop \Orders\Quantity onto the map Size area:

31

Now the color of the city will show the relative Revenue and the size will show the relative Quantity: Run the report:

The large green circle tells you that some city had both high revenue and quantity. The large red circle shows a region where there was high quantity but low revenue, which may indicate a city to watch. This map needs some labels though to help us identify which circle belongs to which city. Return to Report Studio and select the Point layer. Set the Labels property to Show.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Run the report:

32

Now we can identify the cities on the map. However, the labels are placed directly on the point references without regard for overlap. Therefore the labels work best with a smaller numbers of separated data points. Note that Region labels are positioned within the map definition. They may be placed within a product such as MapInfo and imported when the original IBM Cognos 8 map file is created. Point labels are positioned at run time based on the center of the point. However, we can style the labels to make them smaller. Return to Report Studio and select the map. Set the font to Andale Mono, size 8.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Run the report.

33

Thats a little better. Note that the font setting is at the map level and therefore affects many text elements within the report such as the legend values. The font settings for the legend can be defined separately though. As an alternative, you can also Unlock the report and select the chart (Map) body. This allows you to set the Fill Effects, Background Image, Background Color, Foreground Color, Font and Horizontal Alignment properties without impacting the other objects in the map. First, lets remove the font settings we just applied. Select the map and set the font properties to default:

Next, use the Unlock button

to unlock the report layout.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select the Chart Body7:

34

Set the Font property to Andale Mono, size 8, and then run the report:

Why is this chart body and not map body? Because in XML report specification terms they are the same object and it did not seem important to have two objects where one will suffice.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

35

As you can see, only text within the chart body is affected.

Return to Report Studio and Lock

the report.

Lets filter the data for this report and see if we can improve the displayed points on the map. Return to Report Studio and create a summary filter [Revenue] > 1000000 (thats 1 million). Set the filter scope to City. Run the report:

This is much better. The small data points that had little impact on Revenue have been removed and we can clearly see the major contributors. Another great feature for interactive use is tooltips. Return to Report Studio and select the Point layer. Set the Labels property to Hide. Select the map and set the Tooltips property to Show.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

36

Run the report and hold your mouse over a city to see the tooltip:

Note that Tooltips operate in HTML only.

6 Map Dictionary
6.1 Overview When we display your data on a map, we use key values in your query such as Country or City to bind (match) to like-values in the map. Each map contains a dictionary of key values for each layer Country and City names for example in different languages. For example, a map might have country names in several languages as so: en Canada Great Britain United States Japan fr Le Canada La Grande Bretagne
Les Etats-Unis d'Amrique Le Japon

de Kanada
Grobritannien Vereinigte Staaten von Amerika

Japan

ja

Not all maps are translated to all languages. Please do not assume which names are translated. To confirm the available translations you will need to check the specific map definition. We will document which sample maps are in which languages and we hope to make more maps/translations available as free web downloads in the future.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

37

The map dictionary can also contain aliases. The United States of America for example, might also have aliases of The US of A, United States, USA, etc. Aliases are also organized by language, so you might have different aliases for the same place in different languages. For example, in French, Les Etats-Unis d'Amrique might also be aliased as USA and Les EtatsUnis. If your data does not match the map values (perhaps you data contains England and the map uses Great Britain) there are 3 solutions (4 if you want to change the data in your database): 1. Create a calculation which renames the country in the query
if ([Country] = England) then (Great Britain) else ([Country]).

This could be done in the Framework Manager model is you are working with RDBMS based data. 2. Create an alias in the map in each report. We will see how to do this in a moment. 3. Create an alias in the map definition itself using Map Manager. We also see how to do this in a moment. 6.2 Create Aliases in Report Studio Lets see how to create aliases within the report. Open Report Studio with the GO Sales and Retailers package and create a new map report using the World map. Select Countries + Territories as the region layer and select Oceans as the display layer. Drag \Orders\Revenue measure into Color. Drag \Countries\Country to Location. Run the report. As we did not get an error telling us there are query values which are not in the map, all the query country names must align with the map country names. Lets change this so that we can illustrate the creation of the map aliases. Edit the Country data item and change the expression to:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

38

if ([gosales_goretailers].[Countries].[Country]= 'United States') then ('USA') else ([gosales_goretailers].[Countries].[Country])

As the map does not contain a country named USA, running this report should result in a failure which we will fix using an alias. Run the report:

Perfect. Now we can create an alias to fix this problem. Select the map and select the Dictionary property:

What you see are the aliases defined for the instance of the map within this report.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Click on the Add button:

39

The Name field is the name contained in the map (definition). You can type in the name if you are certain you know exactly how it is spelled, or you can search the map definition. Press the Search button. Lets search as so8:

Press the search button.

Report Studio searches only in the language specified in the previous (alias) dialog. If the name exists in another language then you will need to return to the previous dialog in order to modify the search language.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select United States and press OK.

40

Report Studio will add the selected value to the alias definition:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Enter USA as the alias and press OK:

41

Click OK and then run the report. The query and map country names align once more and we see our data correctly:

Creating aliases in the report is fine if they are to be used only in that report. However, this does not allow the aliases to be reused as defaults for other maps.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

42

Save this report as USA Alias as we will need it in the next workshop step. 6.3 Create Aliases in Map Manager We can use Map Manager to create new aliases within the map definition itself. This makes the aliases available to all reports created using the map. The next set of steps will change the world.cmf map file in your product installation. You might wish to create a back copy of that map before doing this exercise. The maps are found in the maps directory under the IBM Cognos 8 installation directory. Map Manager is a Windows based application which is launched from the Windows Start menu. Open Map Manager and then open the World.cmf map from the maps directory in your IBM Cognos 8 installation location. Map Manager can be used to perform several tasks. First, it can import maps from the MapInfo (.gst) format into the Cognos (.cmf) format. This is invoked using the File/Import menu. We will not perform an import as part of this workshop as MapInfo format files are not shipped with IBM Cognos 8.

Maps may be updated through product releases. The changes that you make in the map definitions will not be applied to the updated map files. Therefore, you will have to manage the change process.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

43

On import, you can select which information in the map will be used to alias each layer. For example, in the World map, we imported the Country name with two aliases the FIPS code and the ISO code. This is why you may see two aliases for some countries that are the same. For example, the World map has two aliases of AF for Afghanistan because the FIPS and ISO codes are the same, but Algeria has two different aliases as the FIPS and ISO code do not match.

Second, Map Manager allows you to set the image that appears in the Choose Map dialog:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps The Map Manager interface presents this option in the Image pane as so:

44

This is primarily intended to allow you to set the thumbnail image when importing new maps to IBM Cognos 8. I doubt many you will want to change an existing map thumbnail but the option is available. We will not change the thumbnail image as part of this workshop. Third, Map Manager allows you to set the description of a map by language. These descriptions would appear along with the copyright information in the yellow description area of the Choose Map dialog seen above. The maps IBM Cognos ships do not currently have descriptions. The Map Manager user interface is as so:

The copyright information is concatenated with the description and shown in Report Studio. As the copyright information is required by our partner contracts, Map Manager does not allow you to change or remove it. For license reasons, the copyright information will also appear for certain maps in reports.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

45

Forth, Map Manager can be used to manage aliases with the map definition. The Map Manager interface for this capability looks like the following:

The upper portion of the interface is the set of existing aliases. You can edit or delete aliases as required. The lower portion of the interface lets you create new aliases. Lets create our United States, USA alias. We want the alias to be in English, so we will not change the language. United States is a country, so select the Country + Territories layer. Enter un in the Find field and select United States as the Feature.

Enter the Alias USA and then press the Add Entry

button.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Note that the alias now appears in the dictionary:

46

Save the map. Now, lets use this map in a report. IBM Cognos 8 only loads each map file once. The map information is then cached the information within the running application. So, to load the latest copy of the world map, you must stop and re-start IBM Cognos 8. Do so now to refresh the world map definition. Open the USA Alias report we created earlier in Report Studio. As you may recall, we created an alias USA in the report itself. Select the map Dictionary property and delete the USA alias you created earlier. Run the report. We now use the alias defined in the map using Map Manager and the report runs correctly. One thing we have not yet seen in Map Manager is the ability to import and export translated strings but we will get to that shortly. 6.4 More about Map Manager There are many things you might wish to do with maps. It is important to understand what Map Manager can and cannot do. What Map Manager cannot do is: 1. Create or modify maps 2. Import non-MapInfo format maps. a. Maps must be converted to MapInfo format before being imported. 3. Export maps to MapInfo or other formats. 4. Combine features in existing layers to create custom regions.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

47

a. For example, one wishing to create sales territories based on the world map requires mapping tools from a map vendor because Map Manager does not provide this capability. 5. Create a zoomed in map showing a portion of the map in a larger size. As you can see, Map Manager delivers IBM Cognos map functions atop the vendors maps. Map Manager is not a replacement for the map vendor tools.

7 Maps and Multilingual Applications

7.1 Binding Query Data to the Map Dictionary When a user runs a report, the users language (run locale) is used to bind (match) values from the query to the map dictionary. When using the GO Sales and Retailers model, the country names have been translated for many languages. If the country report we were working on is run in English (the run locale is en-any region), I will see English country names coming from the database. Binding these values to the map will also succeed by using the English country names in the map. If the run locale is changed to French (run locale of fr-any region), the database will return French country names in the query and these will be bound to French country names in the map. What is happening behind the scenes is that IBM Cognos 8 is using the users language (run locale) to determine the map dictionary language. If the run locale is French, then we use the French dictionary. There are several considerations of importance based on this. First, if you are testing and creating aliases, you have to test in all languages and create aliases in each language as required. Second, if the query data language of your choice does not exist in the map dictionary then it will not be possible to match the data language to the map language. You can use Map Manager to add translations or aliases as required. Third, if the users language (run locale) does not exist in the map dictionary, then IBM Cognos 8 will use the default language for the map. In the IBM Cognos supplied maps, most have the default language set to English. If the data is not in the default language of the map dictionary, then no matches will be found. You can correct this using Map Manager to change the default language to match your data or by adding aliases.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

48

Fourth, if the users language (run locale) DOES exist in the map dictionary but the query data is not in the same language, then no match will be found. Consider this scenario: 1. The map dictionary is in French and English. 2. The users language is French. 3. The query data is in English. IBM Cognos 8 will use the users language French - to match the French map dictionary values to the English query data. No matches will be found. We will not drop back to use the default language because the users language does exist in the map dictionary. In this scenario there are two approaches. If the query data is consistently in a single language then the Data Language property of the map can be set to match the query data language. This will override the user locale settings. The data values from the query will be matched to the map aliases in the language specified by the Data Language property. If the query data is multilingual but does not cover all languages such as when: 1. The map is available in English, French, and Japanese 2. The query data is available in English and Japanese 3. The users language is in French Then one of the data languages must be selected to act as a default for undefined locales. Once the default language is selected and appropriately implemented in your model or report then aliases for the unavailable data language must be created in the map under the default language. In the example above where French is not matched to a data language, you may choose English as the default language for your data. Once that selection is made you can create English language aliases for the French names within Map Manager or within the report. For example, for the French country name Les Etats-Unis d'Amrique, we would create an alias of United States of America in the English language as so:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

49

Fifth, the language of the data may changes within each row such that some rows have United States and some Les Etats-Unis d'Amrique. Perhaps there is even a second query column which states the language, en/fr. You would use Map Manager to create aliases to manage this scenario. As you can see, we have given multilingual application a lot of thought. 7.2 Using Map Manager for Translations Map Manager allows you to add translations to your .cmf format maps. The export/import mechanism uses a simple tab delimited format. The export will output all strings from the map, including the map name and the dictionary entries. Lets take a look at an example. Using Map Manager, open the austria.cmf map. Examine the language drop downs for the descriptions or aliases and youll see that this map is in English and German. Select Export from the Language menu. You can export any of the existing languages. Select English and German to be exported. You can also select a language which is not in the map to be exported. You may be asking how we can export a language which is not in the map. Lets try it and see what we get.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select French as an export language. Well take the defaults and export all layers.

50

Press the export button and name the file c:\austria.txt. Open the file in notepad and youll see something like this:
de en fr Austria sterreich Stdte Graz Cities Graz

Innsbruck Innsbruck

Each element is separated by a SINGLE tab character. Selecting French has simply placed the correct language code into the header row for us.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps This file could now be translated as required and then re-imported. de en fr sterreich Austria l'Autriche Stdte Cities Villes Graz Graz Graz Innsbruck Innsbruck Innsbruck We are not actually going to do that as we do not have all the required French translations for this map.

51

Note: If you are going to change a map, make a backup first. The modified map must be deployed to all IBM Cognos ReportNet or IBM Cognos 8 servers. Changes made to a map must be re-applied with each new product release to ensure that the map information is up to date and contains all the required aliases or translations. It is important to understand the role of the Base Language of the map. The base language is used on import to fill in the blanks if an imported translation is missing strings. This allows you to perform a partial translation of the parts of the map you feel are relevant to you and allow Map Manager to provide default strings for the remainder. The base language is selected using the Language menu. At run-time, the base language is also the default language used if the users language does not match a language in the map. For example, if the map was in English and French with a base language of English and the user preferences are set to German, then English would be used to bind query values to the map dictionary. This means that the query values must also be in English or they will not match the base language of the map. On import, Map Manager must match the strings in the translation file to those in the dictionary. The base language is NOT used for this purpose. Map Manager uses the first (left-most) language that appears in the imported translation file to match strings. Strings from all other languages will be added to the dictionary. Existing strings in those languages will be overwritten. Thus, if a map contained an error in the French spelling of Monde as so: en fr World Modne Cities Villes

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

52

You could export the English and French, correct the spelling and re-import the file. Assuming the other French strings were correct, they could be removed from the translation file and the existing French strings would be preserved on import. Alternately the correct translations could be left in the translation file and the existing strings would be overwritten with the same values. Lets take a look at this process. Lets say we did not want our map to be called World. We really want it to be called Map of the World in English, Carte du monde in French and Diagramm der Welt in German. Backup the world.cmf map file. Open Map Manager. Open the world.cmf map file. Export the languages English, French and German (in that order) to the file c:\world.txt (overwrite the previous text file). Leave Map Manager open. Open the c:\world.txt file in notepad. You will see information as so: en fr De World Monde Welt Translate the French and German strings as so: en Fr De World Carte du monde Diagramm der Welt Be sure to leave a SINGLE tab character between the English, French and German strings. You can either delete the remaining rows or leave them as they are. By leaving the English string intact, Map Manager can import the new French and German strings. Save the changes to the text file and return to Map Manager.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

53

Select the /Language/Import Translation File menu. Select the file c:\world.txt and click Ok to open the Import Translation File dialog. Note that Map Manager tells you that English is the key translation language. Select French and German as languages to import:

Click OK to Import this file. We have now done half the job. We need to also change the English from World to Map of the World. We will use the translation file again for this next change. Create a new export file with English) as so: Fr Carte du monde just French and English (or German and en World

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

54

Note that the English translations are in the second column and not in the first column. Since the first column is our import key we must ensure that English appears as a non-key column so that the translations can be applied. Edit this file in notepad and fr Carte du monde change the English string as so: en Map of the World

Import the file using Map Manager. The French strings will be the keys for matching the values and the English values will be overwritten. The end effect is that we have re-labeled our map. Save the map. Map Manager can take as long as a minute to save a map, so please be patient. Stop and re-start IBM Cognos 8. Open Report Studio with the GO Sales and Retailers package. Create a new map report.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Note that the name of the map has been changed:

55

You can use these same steps to change any of the strings in a map.

8 Drill Through on Maps

Maps support drill through to allow you to call another report and pass down parameters or data values. Maps do not currently support drill down which is a drill action to expand the current map focus by replacing the current map with a new map for the selected region.. Drill on maps can be specified in two ways. First, on the overall map so that the same drill through definition is applied to all regions/points. Second, specific drill paths can be specified for individual regions/points. Lets define a map-wide drill through. We wish map revenue by country and then allow the user to click on a country to see more details about sales in that country. We will create the target drill report first. To do so, open Report Studio with the GO Sales and Retailers package and create a new list report.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Add the query items: \Countries\Country \Products\Product line \Orders\Revenue \Orders\Quantity \Orders\Margin Create a new detail filter: [Country] = ?CountryParm? Run the report. Select any country for the generated prompt control. You should see the sales information for the specified country. Save this report as Drill Target. Create a new Map report using the World map.

56

Select Countries and Territories as the region layer and select Oceans as the display layer. Drag \Orders\Revenue measure into Color. Drag \Countries\Country to Location. Select the Map object and edit the Drill Throughs property. Add a new drill through using the Drill Target report you created a moment ago.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Configure the parameters as so:

57

Save this report as Map Drill Parent. Run the report and place your mouse cursor over any country with data and note that the cursor becomes a .

Click on the country to drill to the target report. Note that the Country name is passed down correctly and the list report is filtered accordingly. Return to the parent report in Report Studio. As you can see, maps support drill through in the same way as any other report. It is also possible to define a drill through which is specific to a given region or point on the map. This is done by selecting the region or point layer and defining drill through specific to a given value. While this does allow you to define different drill paths for different regions/points, GO Sales and Retailers does not offer a compelling scenario to demonstrate this. However, the region/point drill is defined by selecting the region or point layer from the map in Report Studio. By selecting the Map Drills property the following dialog will be come available.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

58

Clicking the New button will allow you to select the appropriate region or point.

Once you have selected the region or point the OK button will bring you to the Drill Throughs dialog where report and parameters can be defined.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

59

9 Map Legends
A legend is generated for each layer measure on the map. The map legend can be hidden or moved to the left, right (default) or bottom which may not be the best choice for presentation purposes:

The map legend also offers many formatting options. Similar to the titles the font and color of the legend can be set by accessing the properties of the legend object.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

60

The Legend Title can be customized to display any text. The method to do so varies slightly from other Title objects in that other titles will use a blank text item by default. The Legend Title does not contain a blank text item because for legend objects the default title is typically populated by the query items themselves. Lets take a look at modifying the Default Legend Title. Open Report Studio using the GO Sales and Retailers package and create a new map report using the World map. Select Countries and Territories as the region layer and select Oceans as the display layer. Drag \Orders\Revenue measure into Color. Drag \Countries\Country to Location. If you run the report now the legend will display Revenue as we expect. Drag a Text Item from the toolbox onto the Default Legend Title and type in Revenue: . Note the space at the end of the text. Next, drag Revenue from the query Data Items to the right of the text item in the Legend Title.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Run the report to get the following output:

61

10 Notes
Notes operate much like they do on a chart. You can set the Note content (text, query item or report expression), the x,y location on the map and the size of the marker display area. To take a look at this, open Report Studio with the GO Sales and Retailers package and create a new map report using the World map. Select Countries and Territories as the region layer and select Oceans as the display layer. Drag \Orders\Revenue measure into Color. Drag \Countries\Country to Location. Now, lets add a note with the Total Revenue.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Select the map and edit the Notes property to open the Notes dialog:

62

Click the New button

to create a new note:

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Click OK to return to the report layout. A Notes section with the New Note appears in the map prototype:

63

As with the map titles, the note is an area into which you can add text items including static text, query items and so on. Double click the text New Note to edit the text. Change the text to Total Revenue: . Note the trailing space.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Drop the Revenue query item into the note:

64

Run the report:

The note appears in the default location. The note is actually made up of 3 parts. 1. The note object

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

65

a. 2. The note content object

a. 3. The text items that make up the note

a. Select the note object:

and

Note the default size and location properties:

We want to note to be wide enough to display on a single line in the bottom left hand corner of the map.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps Ensure the note object is still selected and set the border to:

66

Set the location properties as follows: Bottom - 105 (px). Left - 85 (px). Height - 20 (px) Width - 230 (px). Run the report:

I think we can improve on the note so that it isnt as obstructive. Return to Report Studio and select the Note content:

Set the Horizontal Alignment property to Center.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

67

Set the Background Color to Transparent and then run the report:

This is a much more attractive note than when using the white background because the map is still visible and the note provides useful context for the values that are plotted on the map itself.

11 Custom Pre-Defined Palettes

Report Studio defines a set of palettes to be used for both charts and maps. You can add to or modify the palettes that appear in this dialog by editing the <IBM Cognos 8 install location>\webcontent\pat\ChartPalettes.xml file. This file is read by Report Studio on startup. The palette is copied from this palette file into the report. Therefore, changing this file will not update existing reports but will take effect for new reports. The ChartPalettes.xml file defines three types of palettes: 1. chartPalette used for a non-gauge chart 2. gaugePalette used for gauge charts 3. numericChartPalette used for maps When creating a map palette (a numericChartPalette), Report Studio needs to know the following: 1. The unique id, name and tooltip of the palette
<namedChartPalette10 id="CorpStd" label="Corporate Standard Map Palette for Percentages" tooltip="Standard % Palette">

10

There are also attributes idsLabel and idsTooltip which allow you to refer to strings in the language resource files. You would need to use the LDK to add and localize those string resources.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

68

2. Confirmation that this palette is a map palette (numericChartPalette) and whether the palette is for percentage or compared to maximum value
<numericChartPalette>

Or
<numericChartPalette percentValues="true">

3. Whether the palette is discrete or continuous a. Discrete i. The value ii. The color, gradient or pattern iii. Note: this example is for percentages
<discreteChartPalette> <discreteChartPaletteEntry paletteValue="33"> <chartColor value="Red"/> </discreteChartPaletteEntry> <discreteChartPaletteEntry paletteValue="66"> <chartGradient direction=" right" fromColor="#RGB color value or name" toColor="#RGB color value or name"/> </discreteChartPaletteEntry> <discreteChartPaletteEntry> <<<< Implied maximum value <chartPattern patternType="patter name as shown below" foregroundColor="#RGB color value or name" backgroundColor="#RGB color value or name"/> </discreteChartPaletteEntry> </discreteChartPalette>

b. Continuous i. The value ii. The color

<continuousChartPalette> <continuousChartPaletteEntry paletteEntryValue="0" paletteEntryColor="#339966" /> <continuousChartPaletteEntry paletteEntryValue="100" paletteEntryColor="#993333" /> </continuousChartPalette>

IBM Cognos Proprietary Information

Report Studio Workshop - Maps The valid gradient directions are shown as from Black to White:

69

The valid patterns are:

The named palettes appear in the Report Studio user interface in the order defined within this file. For example, this palette:

Would be defined as:

<namedChartPalette id="DPP" label="Discrete Percentage Palette" tooltip="Discrete Percentage Palette"> <numericChartPalette percentValues="true"> <discreteChartPalette> <discreteChartPaletteEntry paletteValue="33.33"> <chartColor value="#339966"/> </discreteChartPaletteEntry> <discreteChartPaletteEntry paletteValue="66.67"> <chartPattern patternType="cross" foregroundColor="blue"

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

backgroundColor="olive"/> </discreteChartPaletteEntry> <discreteChartPaletteEntry> <chartGradient direction="left" fromColor="red" toColor="white"/> </discreteChartPaletteEntry> </discreteChartPalette> </numericChartPalette> </namedChartPalette>

70

Please note that all quotes are plain text quotes " and ' and not Microsoft Word smart quotes and . This palette

Would be defined as:

<namedChartPalette

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

id="CPP" label=" Continuous Percentage Palette" tooltip=" Continuous Percentage Palette"> <numericChartPalette percentValues="true"> <continuousChartPalette> <continuousChartPaletteEntry paletteEntryValue="0" paletteEntryColor="#993333"/> <continuousChartPaletteEntry paletteEntryValue="50" paletteEntryColor="#CC9933"/> <continuousChartPaletteEntry paletteEntryValue="100" paletteEntryColor="#339966"/> </continuousChartPalette> </numericChartPalette> </namedChartPalette>

71

Lets use this palette. We will be modifying the default palette for your product installation. It is recommended that you make a backup of the ChartPalettes.xml file before applying any changes. Open notepad and edit the file <IBM Cognos 8 install location>\webcontent\pat\ChartPalettes.xml. Add the text above to the XML file. The order of the namedChartPalette elements is not important so long is the new specification falls inside the <namedChartPalettes> element. For the sake of our example you can add the palette entry to the end of the file at the following position:
... </namedChartPalette>

Insert the new Palette here

</namedChartPalettes>

Save this file.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps This file is only read on Report Studio startup so close and re-open Report Studio to enable the changes made in the ChartPalettes.xml file. Create a new map report using the World map. Select Countries and Territories as the region layer and select Oceans as the display layer. Drag \Orders\Revenue measure into Color. Drag \Countries\Country to Location. Select the Region layer and select the Palette property. Note that our custom palette now appears for us to use.

72

This saves us from having to re-define this palette in each report.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

73

12 Adding Custom Maps

Any new maps must be developed using non-IBM Cognos tools such as those provided by MapInfo, ESRI and the like. The steps to add maps to IBM Cognos 8 are quite straight forward. 1. Using an appropriate tool such as MapInfo or ESRI, prepare the map you require a. At this stage, if you can have the base dictionary values match your data, it will save you from having to create aliases later. b. At this stage, you choose the data you wish to use to name and alias the regions/points within the map c. Map Manager will allow you to specify a single source item for the name of each place and zero, one or more additional items from which to generate aliases. d. Save the map in the MapInfo .gst format (IBM Cognos 8 Map Manager only imports MapInfo .gst files) 2. Use Map Manager to import the map to create an IBM Cognos 8 .cmf format map file. a. Please note that importing is an intensive process that may take a few minutes to complete. 3. Optionally: a. If you wish to have the dictionary in multiple languages, export a translation export file and then have it translated. The file can then be imported to apply the translations. b. The map and layer names that appear in Report Studio can be modified through the export/import mechanism also. 4. Optionally: a. Create any aliases you require b. If your map names already match your data or you have imported the required aliases, you can skip this step. 5. Copy your map into the IBM Cognos 8 maps directory. 6. Update the MapGroups.xml file. This file is used to present the maps in the Choose Map dialog in Report Studio. 7. Use your map.

13 Notes about Mapping Technology

13.1 MapInfo and IBM Cognos You may have read a Press Release about IBM Cognos and MapInfo and be wondering exactly how IBM Cognos uses MapInfo technology and maps.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

74

In a nut shell, IBM uses very little MapInfo or other vendor map technology. This has been done to reduce the dependency on 3rd party vendors. The map engine in IBM Cognos 8 is fully developed from scratch by IBM using only IBM technology. Map Manager is a wholly IBM developed tool. The map file format used by the IBM Cognos 8 map engine is a wholly IBM developed format. There is, however, one considerable issue with having a proprietary map file format; people using mapping software already develop non-IBM Cognos maps using MapInfo, ESRI and the like. Further, the aim is not to enter into the realm of creating map development software to allow people to create IBM Cognos file format maps. Therefore, the solution was to choose one or more map formats that can be imported into IBM Cognos 8. MapInfo is an ideal solution because they have an existing technology that could integrate into Map Manager and almost all mapping software can produce MapInfo files. Therefore, the only use of MapInfo technology is for map import with Map Manager. IBM Cognos 8 also uses some MapInfo maps. These maps are imported into the IBM Cognos 8 map file format using Map Manager. During that import, the MapInfo maps are converted into the IBM Cognos 8 map file format to be used by the IBM Cognos 8 map engine. As MapInfo does not have all the name translations that are needed, we also license some map name files from one or more other vendors. 13.2 MapInfo GST Files Most people developing MapInfo map files have never heard of nor used MapInfo .GST files. These files are used by the MapInfo technology we use in Map Manager to import maps. Map developers will be more familiar with .TAB and other files. The GST file is essentially a project or header file which lists all of the other files that make up a map definition.

14 Conclusion
We have done a lot of great works with maps including giving you the ability to add your own maps for specific applications. The formatting and layout options that we have discussed will bring considerable flexibility and power to your reports and allow you to create stunning maps and dashboards for your organization.

IBM Cognos Proprietary Information

Report Studio Workshop - Maps

75

IBM Cognos Proprietary Information