IBM Cognos Visualization Customizer Documentation

Using IBM Cognos Visualization Customizer

Product: IBM Cognos BI - Extensible Visualization

Area of Interest: Documentation

Using IBM Cognos Visualization Customizer 2

Copyright and Trademarks

Licensed Materials - Property of IBM.

Copyright IBM Corp. 2013

IBM, the IBM logo, and Cognos are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

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. IBM does not accept responsibility for any kind of loss resulting from the use of information contained in this document. The information contained in this document is subject to change without notice.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.


Table of Contents

INTRODUCTION........................................................................................................ 4

PURPOSE OF DOCUMENT ......................................................................................................... 4 APPLICABILITY ..................................................................................................................... 4 CAVEATS ..4

OVERVIEW ................................................................................................................ 4

INSTALLING AND LAUNCHING THE IBM COGNOS VISUALIZATION CUSTOMIZER ...................................... 5 THE IBM COGNOS VISUALIZATION CUSTOMIZER USER INTERFACE .................................................... 5 The JSON Editor ............................................................................................................... 6 The Extensible Visualization Bundler Interface .................................................................... 7 USING THE IBM COGNOS VISUALIZATION CUSTOMIZER TO CREATE A VISUALIZATION ............................ 9 Creating the Extensible Visualization Bundle based on Existing JSON Grammar ..................... 9 Deploying the Extensible Visualization Bundle into the IBM Cognos BI Environment ............ 12 Using the Extensible Visualization within IBM Cognos Report Studio ................................... 13 Making a Change to an Extensible Visualization Bundle ..................................................... 15

APPENDIX A: JSON GRAMMAR FOR SAMPLE BAR CHART ..................................... 18

APPENDIX B: THE CONTENTS OF AN EXTENSIBLE VISUALIZATION BUNDLE ...... 32


Introduction

Purpose of Document

This document accompanies the IBM Cognos Visualization Customizer tool, which can be used to customize extensible visualization for consumption within IBM Cognos BI product suite.

Applicability

IBM Cognos Visualization Customizer can be used to modify visualization to be consumed within:

IBM Cognos BI 10.2.1.1

Caveats

The IBM Cognos Visualization Customizer tool is delivered As is. The IBM Cognos Visualization tool is only available in the English language.

Engagement with IBM Services is available for customers wanting to work with more complex modifications with this tool.

The IBM Cognos Visualization Customizer should be reviewed prior to using the tool. It should be noted that the IBM Cognos Visualization tool should be used to modify existing visualizations from AnalyticsZone.com

IBM Cognos Customer cannot assist with questions around this tool nor provide guidance or assistance around updating the visualization JavaScript Object Notation(JSON) grammar or extensible visualization bundles.

It is highly recommended that a backup be done of the visualization prior to making any modifications.

The first time the tool is opened, license terms will be displayed and must be agreed upon by the user before access is given to use the tool.

Overview

With the release of IBM Cognos BI 10.2.1.1, extensible visualizations are now consumable outside of the active reports as standard reports. The IBM Cognos Visualization Customizer tool was created to provide the ability to adjust the pre-packaged extensible visualizations located on http://www.analyticszone.com (https://www.analyticszone.com/homepage/web/displayMarketplacePage.action#search/-/:All,BI%20Version:10.2.1.1) to satisfy these new charting requirements. The following sections of this document will cover:

Installing and Launching the IBM Cognos Visualization Customizer

A Brief Overview of the IBM Cognos Visualization Customizer User Interface

An End to End Tutorial of Editing an Existing Extensible Visualization


Installing and Launching the IBM Cognos Visualization Customizer

After downloading the IBM Cognos Visualization Customizer.zip file, unzip the contents locally onto the file system. The first time the tool is opened, a license terms dialog will appear, asking to accept the terms prior to starting to work with the tool. Access to the tool is only gained if the terms are agreed upon from that dialog.

The IBM Cognos Visualization Customizer can be launched by double clicking the Vizualization Customizer.jar file. Once the tool launches, and the license terms are accepted, the user will be presented with the initial view illustrated by the following screen capture.

Figure 1 Initial view after launching the IBM Cognos Visualization Customizer.

The IBM Cognos Visualization Customizer User Interface

The IBM Cognos Visualization Customizer user interface is divided into two functional areas. The left hand pane is the JSON editor, which is used to display, format and edit the JSON grammar. The right hand pane is the extensible visualization bundler interface. This interface is used to provide a visual representation of the graph created by the JSON grammar. The interface is also used to generate and display the Chart Type Definition, IBM Cognos Report Studio specific language files and the thumbnails before they are bundled.


The JSON Editor

Table 1 User Interface of the JSON Editor.

The IBM Cognos Visualization Customizer JSON editor.

The IBM Cognos Visualization Customizer JSON Editor Toolbar.

Format: This applies a visually appealing format to the JSON code.

Validate: This validates the syntax of the JSON code. Any validation errors will be displayed in a separate pop up dialog box.

Data Manipulation: The drop down displays a multitude of options to modify the sample data within the JSON code to see what affect it has on the graph display.

Color Palette: The drop down displays a collection of pre-defined color palettes which can be used to see what affect it has on the graph display.

Search and Replace: This can be used to search, search and replace or replace all grammar matching the entered criteria.


The Extensible Visualization Bundler Interface

Table 2 The Extensible Visualization Bundler Interface.

The Visualization Bundler Interface.

The three main functional areas of the Visualization Bundler Interface which are represented by the Rapid Adaptive Visualization Engine(RAVE), Chart Type Definition and Thumbnails tab

The screen view of the RAVE tab.

The Draw Chart Button uses the JSON grammar to visually represent the chart.

The screen view of the Chart Type Definition tab.


The Bundle Name is the name of the extensible visualization bundle. This name needs to a unique name. An example of a Bundle Name would be: vis.sample.bar.stacked.default.

The Bundle Author is the name of the person or corporation who created the bundle. An example of a BundleAuthor

would be: ibm.com.

The Bundle Tags are the tags that will be used within the imported extensible visualization gallery of IBM Cognos Report Studio to group the extensible visualizations. The multiple tags will be space separated. An example of some

Bundle Tags would be: Bar BarStacked.

The Generate Viz Bundle Definition button generates all the chart specification based on the defined JSON grammar, it also creates all the underlying supporting string resource files.

The Validate Bundle button is used to ensure the Bundle and its contents are valid in structure and syntax.

The Chart Type Definition tab displays the chart definition based on the JSON grammar. The Chart Type definition can be manually edited within the lower right hand side preview pane.

The String Resources tab displays the language file generated with default strings in English. The language file is used by IBM Cognos Report Studio to display tool tips and additional information about the extensible visualization within the imported Gallery. The String Resources can be manually edited within the lower right hand side preview pane.


The screen view of the Thumbnails tab.

The Generate Thumbnails button uses the chart preview to generate image files which will be used when viewing the visualization within the imported visualization gallery.

Using the IBM Cognos Visualization Customizer to Create a Visualization

The following example will use the JSON grammar provided within Appendix A of this document to create and modify an extensible visualization. The example will also cover the steps required to import this extensible visualization into the IBM Cognos BI 10.2.1.1 environment.

Creating the Extensible Visualization Bundle once edits are made based on Existing JSON Grammar

To create the extensible Visualization bundle:

1. Copy the JSON grammar from Appendix A and save it to the file system with a .json extension. For this example the file was created on the C:\ drive with a name of MyBar.json. This is the JSON from the cluster bar visualization from AnalyticsZone.com

2. Launch the IBM Cognos Visualization Customizer by double clicking the VisCustomizer.jar file.

3. From the available File Menu, select the Open Viz JSON and locate the file created earlier.


4. With the file selected, click Open. Once the IBM Cognos Visualization Customizer refreshes, the JSON code should be displayed within the left hand side JSON Editor as illustrated below.

Figure 2 JSON visible within the JSON Editor.

5. To ensure the JSON grammar is well formed, click on the checkmark to perform the validation.

6. Click OK to the pop up dialog box which states the VizJSON is well formed.

7. Within the right hand Visualization Bundler Interface, click on the Draw Chart button located within the RAVE tab. Once the screen refreshes, the Bottom of the RAVE tab should now display the generic chart display represented by the JSON grammar.

Figure 3 Chart Display within the RAVE tab.

8. Within the right hand Visualization Bundler Interface, click on the Thumbnails tab.


9. Within the Thumbnails tab, click on the Generate Thumbnails button to create the thumbnails to be used by imported extensible visualization gallery. When the screen refreshes, the bottom of the Thumbnails tab should display the thumbnails of various sizes.

Figure 4 Thumbnails tab displaying the Generic Chart Thumbnails

10. Click on the Chart Type Definitions tab.

11. Within the Chart Type Definitions tab, provide the Bundle Name, Bundle Author and the Bundle Tags. For this example the following values were used:

Bundle Name: vis.sample.mybar.stacked.default

Bundle Author:IBM.com

Bundle Tags: Bar


Once the above fields have been filled in, Click on the Generate Viz Bundle Definition button to create the bundle. When the screen refreshes, the Chart Type Definition preview should now display the Chart Type definition based on the visJSON. In most cases the definition is accurate, but it is possible to manually edit and change the definition if required. This is also illustrated by the following screen capture.

Figure 5 Chart Type Definition Tab after Bundle Generation.

12. From the available File menu, select the Save As and save the zip file to the local file system. For this example the zip file will be saved to the C:\ drive with the same name as the Bundle Name.

Deploying the Extensible Visualization Bundle into the IBM Cognos BI Environment

In order to use the newly created extensible visualization bundle within the IBM Cognos BI Product, the bundle needs to be imported into the Extensible Visualization Gallery(Library). To do this:

1. Using a browser, logon to the IBM Cognos Connection portal with a user that has access to the IBM Cognos Administration.

2. Launch IBM Cognos Administration and click on the Library tab. Once the browser refreshes, the Library tab will display all the previously imported extensible visualizations as illustrated by the following screen capture.


Figure 6 IBM Cognos Administration Library Tab.

3. Click on the Import Visualization icon at the top right hand side of the screen to evoke the New Visualization Import Page.

4. Within the New Visualization Import Page, click on the Browse link. Within the Browse dialog box, locate and double click the extensible visualization bundle zip file saved earlier. For this example the following file name and

location was used: C:\vis.sample.mybar.stacked.default.zip.

5. Within the New Visualization Import Page, click on the Import button. When the import completes, the New Visualization Import Page will display as follows:

Figure 7 Import Page after a Successful Visualization Import.

6. Click the Close button to return to the Library tab.

7. Click the refresh icon at to top right hand side of the screen to display the newly imported extensible visualization within the Library tab. At this point the extensible visualization is now ready to be used.

Using the Extensible Visualization within IBM Cognos Report Studio

1. Using a browser, launch the IBM Cognos Report Studio.

2. After selecting a package, select the New Blank report template. For this example the Go Sales(Query) samples package was used.

3. Within the top left Source pane, switch to the Toolbox tab and locate the visualization object.


Figure 8 IBM Cognos Report Studio displaying the Visualization toolbox

item.

4. Drag the Visualization object onto the blank canvas on the right hand side of the screen. Doing so will evoke the Imported Visualization Gallery.

Figure 9 IBM Cognos Report Studio Visualization Gallery.

5. Locate the imported Bar-Stacked extensible visualization. The environment used in this example has two seemingly identical Bar Stacked objects. The recently imported one can be determined by the properties within the right most pane of the Visualization Gallery dialog box.

Figure 10 Visualization Gallery Chart Properties.

6. Click the OK button to add the extensible visualization to the canvas. 7. From the available Source objects, drag some data items into the extensible

visualization drop zones. For this example the following items were used:

Size: [Sales (query)].[Sales].[Revenue]

Y Category: [Sales (query)].[Time].[Year]

Series: [Sales (query)].[Products].[Product line]


8. From the available toolbar objects, click the run icon to execute report.

When the IBM Cognos Report Viewer refreshes, the extensible visualization is presented to the user. This is also illustrated by following screen capture.

Figure 11 IBM Cognos Viewer Output of the Extensible Visualization.

9. Save the IBM Cognos Report studio report as it will be used later in this

tutorial.

Making a Change to an Extensible Visualization Bundle

The following section will step a user through a generic color edit and re-deploy of the extensible visualization. To change the color of Camping Equipment:


2. Launch IBM Cognos Administration and click on the Library tab. Once the browser refreshes, the Library tab will display all the previously imported extensible visualization.

3. Locate the extensible visualization to be updated and use Download option from the down arrow menu to download the extensible visualization bundle zip file.

Figure 12 Download Menu for a Specific Extensible Visualization.

4. Chose a local file location and save the zip file. For this example the filename

Library_vis.sample.mybar.stacked.default.zip was saved to the C:\ drive. 5. Launch the IBM Cognos Visualization Customizer and use the File\Open menu

to open the previously saved Library_vis.sample.mybar.stacked.default.zip file.

6. Use the Validate JSON checkbox icon and the Chart Type Definition\Validate Bundle button to ensure the bundle saved and opened correctly.


7. From the toolbar color palette icon, select the Blue Categorical Color menu item. When the screen refreshes, the graph is now displayed using the new color palette.

Figure 13 Updated Graph with new Color Palette.

8. To reflect the new colors, update the thumbnails by selecting the Thumbnails

tab, then clicking the Generate Thumbnails button. 9. With the new color and thumbnails in place, re-generate the bundle by

selecting the Chart Type Definition tab and clicking the Generate Viz Bundle Definition button.

10. From the available file menu, select the Save As and save the updated bundle with the original name. For this example the original name was: C:\vis.sample.mybar.stacked.default.zip.


12. Launch IBM Cognos Administration and click on the Library tab. Once the browser refreshes, the Library tab will display all the previously imported extensible visualizations.

13. Click on the Import Visualization icon at the top right hand side of the screen to evoke the New Visualization Import Page.

14. Within the New Visualization Import Page, click on the Browse link. Within the Browse dialog box, locate and double click the extensible visualization bundle zip file saved earlier. For this example the following file name and

location was used: C:\vis.sample.mybar.stacked.default.zip.

15. Within the New Visualization Import Page ensure the Replace Existing Entries checkbox is checked then click the Import button. When the import completes, the New Visualization Import Page will display as follows:


Figure 14 Replace existing entries on Import.

16. Click the Close button to return to the Library tab.

17. Re-run the previously saved IBM Cognos Report Studio report. As the IBM Cognos Viewer refreshes, notice that the chart colors have not updated to the new color palette.

18. Open the report within IBM Cognos Report Studio.

19. From the available Tools menu item, select Update Visualizations.

20. Save the report and re-run it.

21. As the IBM Cognos Viewer refreshes, the extensible visualization object now reflects the new colors. This is also illustrated by the following screen capture.

Figure 15 IBM Cognos Viewer Output with Updated Colors.


Appendix A: JSON Grammar for Sample Bar Chart

The following JSON grammar has been obtained from the stacked bar chart on http://www.analyticszone.com. The JSON grammar is used throughout this document as part of the tutorial.

{

"copyright":"Licensed Materials - Property of IBM. IBM Cognos Products:

RS. (c) Copyright IBM Corp. 2013. US Government Users Restricted Rights -

Use, duplication or disclosure restricted by GSA ADP Schedule Contract with

IBM Corp.",

"data":

[

{

"id":"dataSet",

"fields":

[

{

"id":"categories",

"label":"abc",

"categories":

[

"abc",

"abc",

"abc",

"abc",

"abc",

"abc",

"abc",

"abc",

"abc",

"abc"

]

},

{

"id":"series",

"label":"abc",

"categories":

[

"abc",

"abc",

"abc"

]


},

{

"id":"size",

"label":"abc"

}

],

"rows":

[

[

4,

0,

13.14

],

[

3,

0,

13.18

],

[

2,

0,

13.28

],

[

0,

0,

14.7

],

[

6,

0,

15.12

],

[

5,

0,

15.02

],

[

1,

0,

14.55

],


[

4,

1,

7.95

],

[

3,

1,

8.62

],

[

0,

1,

9.09

],

[

6,

1,

10.06

],

[

5,

1,

10.64

],

[

1,

1,

11.97

],

[

2,

1,

14.85

],

[

4,

2,

11.6

],

[

3,

2,


11.64

],

[

0,

2,

10.93

],

[

5,

2,

22.3

],

[

1,

2,

12.46

],

[

2,

2,

13.44

],

[

9,

0,

18.18

],

[

8,

0,

15.7

],

[

7,

0,

16.96

],

[

9,

1,

9.85

],

[


7,

1,

18.82

],

[

8,

1,

13.46

],

[

9,

2,

11.22

],

[

6,

2,

17.99

],

[

7,

2,

13.84

],

[

8,

2,

20.06

]

]

}

],

"grammar":

[

{

"bounds":

{

"width":"100%",

"height":"100%",

"left":0,

"top":0

},

"coordinates":


{

"dimensions":

[

{

"scale":

{

"local":false

},

"axis":

{

"preferredSize":

{

"min":"5px",

"preferred":"15%%",

"max":"200px"

},

"gridStyle":

{

"fill":

{

"a":0.35,

"h":0,

"s":0,

"v":0.7

},

"snap":true

},

"lineStyle":

{

"fill":

{

"a":0,

"h":0,

"s":0,

"v":0.5

}

},

"markStyle":

{

"fill":

{

"a":0,

"h":0,


"l":0,

"s":0

}

},

"tickStyle":

{

"fill":"#808080",

"font":

{

"family":"Arial Unicode MS, Andale WT, Tahoma,

Arial, MS UI Gothic, Gulim, SimSun, PMingLiU, Raghu8, sans-serif",

"size":"9pt"

},

"padding":3

},

"title":

[

{

"$ref":"size"

}

],

"titleStyle":

{

"fill":"#808080",

"font":

{



"size":"9pt",

"weight":"bold"

}

}

}

},

{

"scale":

{

"local":false

},

"axis":

{

"preferredSize":

{


"min":"5px",

"preferred":"20%%",

"max":"250px"

},

"lineStyle":

{

"fill":

{

"a":0.25,

"h":0,

"l":0,

"s":0

}

},

"markStyle":

{

"fill":

{

"a":0,

"h":0,

"l":0,

"s":0

}

},

"tickStyle":

{

"fill":"#808080",

"font":

{



"size":"9pt"

},

"padding":3

},

"title":

[

{

"$ref":"categories"

}

],

"titleStyle":

{


"fill":

{

"a":0.6,

"h":0,

"l":0,

"s":0

},

"font":

{



"size":"9pt",

"weight":"bold"

}

}

}

}

],

"transforms":

[

{

"type":"stack"

},

{

"type":"transpose"

}

]

},

"elements":

[

{

"type":"interval",

"position":

[

{

"field":

{

"$ref":"size"

}

},

{

"field":

{


"$ref":"categories"

}

}

],

"color":

[

{

"id":"colorId",

"scale":

{

"local":false

},

"field":

{

"$ref":"series"

},

"modifies":"both",

"palette":

[

"#1183ad",

"#39b2ac",

"#60942c",

"#d4a600",

"#d15c00",

"#b2293d",

"#532f8c",

"#a64c8b",

"#53abcc",

"#86b347",

"#f0cc00",

"#e2515b",

"#764da8",

"#6ecfc7",

"#e6944a",

"#c767ae",

"#84c7e0",

"#b3d66d",

"#ffe36a",

"#e88686",

"#9a77ce",

"#9ce3e0",

"#fabe79",

"#de92ca",


"#bfe2ef",

"#cfe68a",

"#fff69b",

"#f2bcbc",

"#c6b5e5",

"#c0f5f0",

"#fdd6b0",

"#f9bcf3"

]

}

],

"split":

[

{

"field":

{

"$ref":"series"

}

}

],

"style":

{

"fill":

{

"type":"linear",

"angle":-90,

"colors":

[

{

"color":

{

"a":0.9,

"dSaturation":0,

"dValue":0

},

"offset":0.04

},

{

"color":

{

"a":0.9,

"dSaturation":0,

"dValue":0


},

"offset":1

}

],

"global":false

},

"stroke":

{

"width":0.03

},

"width":"80%",

"outline":

{

"dValue":-0.25

}

}

}

],

"style":

{

"fill":"transparent",

"padding":

{

"bottom":"2%",

"left":"2%",

"right":"2%",

"top":"5%"

}

}

}

],

"legends":

[

{

"scale":

{

"reverse":false,

"local":false

},

"aesthetics":

[

{

"aesthetic":


{

"$ref":"colorId"

}

}

],

"boundsStyle":

{

"fill":"transparent",

"padding":

{

"top":"4.5%"

}

},

"labelStyle":

{

"fill":"#808080",

"font":

{

"family":"Arial Unicode MS, Andale WT, Tahoma, Arial, MS UI

Gothic, Gulim, SimSun, PMingLiU, Raghu8, sans-serif",

"size":"9 pt"

}

},

"location":

{

"width":"20%"

},

"titleStyle":

{

"fill":"#808080",

"font":

{

"family":"Arial Unicode MS, Andale WT, Tahoma, Arial, MS UI

Gothic, Gulim, SimSun, PMingLiU, Raghu8, sans-serif",

"size":"9 pt",

"weight":"bold"

}

}

}

],

"legendPosition":"right",

"version":"4.0",

"size":


{

"width":500,

"height":500

},

"style":

{

"fill":"transparent"

}

}


Appendix B: The Contents of an Extensible Visualization Bundle

The following image illustrates the internal structure of an extensible visualization bundle. The images folder contains the generated thumbnails, the resource folder contains the string definition files and the .json file is the actual JSON grammar.

Figure 16 Contents of an Extensible Visualization Bundle.

Documents

IBM Cognos Visualization Customizer Documentation