BACon 2021 Custom Viz in Cognos

BACon 2021
Creating Custom Visualizations in Cognos

Setting up the Development Environment
Software
• Installing NodeJS and NPM
1. Download NodeJS at https://nodejs.org/en/download
a. The latest LTS release is best. “14.17.5 LTS” currently.
b. Either 32 bit or 64 bit. It doesn’t matter for this application.
2. Run the installer and use the default settings
3. After install is complete, validate the node and npm installation.
a. Open a command-line interface (CLI). CMD on Windows or Terminal on OSX
b. Run the following command:
node --version
The CLI displays the current version of the node. Make sure it meets the
prerequisites.
• Installing the Cognos Analytics custom visualizations CLI tools

1. Download the Cognos Analytics custom visualizations command-line tools from the
following location: http://cognos.pm2analytics.com/viz-
workshop/bi/js/vida/customvis.tgz
2. In a command line interface, navigate to the location of the downloaded file
3. Run the following command:
npm install -g customvis.tgz
NOTE: On Apple OSX or Unix systems, you may need to use
sudo npm install -g customvis.tgz

4. After the process is completed, run the following command to validate the custom
visualizations CLI tools
customvis --help
The CLI should display all available commands.
Confidential & Proprietary

• Text Editor or Code Editor
o You need something to be able to edit code. This could be a simple text editor, even
Notepad could work. However, using an editor that can do syntax highlighting and
autocomplete will make your life much easier. These are the two I use most often:
▪ Notepad++ - https://notepad-plus-plus.org/downloads/
▪ Visual Studio Code - https://code.visualstudio.com/download
Create a Base Custom Viz
1. In your CLI navigate to a “Projects” folder. This can be wherever you want to keep your
custom visualization code.
customvis create “YourName Custom Sunburst”

a. This creates a folder with the named “YourName Custom Sunburst” with a base set
of files needed to create a visualization
3. In your CLI, navigate into the newly created folder
cd “YourName Custom Sunburst”

4. To start the new custom visualization, run the following
customvis start
a. This will install all necessary dependencies and start a local NodeJS process
b. Once it says “Started a local server”, it’s ready to go
5. Open the Cognos Analytics environment: http://cognos.pm2analytics.com/viz-workshop/
6. Create a new Dashboard
7. Select the default template and click Create
8. Select the Visualizations panel
9. Select the Custom tab

10. Drag the “Test visualization” to the main Dashboard canvas
11. Your custom visualization should say “Basic VizBundle”

Create HighCharts Visualization
Review HighCharts Options

Main Page: https://www.highcharts.com/
Demos: https://www.highcharts.com/demo
Sunburst: https://www.highcharts.com/demo/sunburst
API Docs: https://api.highcharts.com/highcharts/
Add HighCharts Library to the Project

The default template provided by the customvis application includes all the basic files necessary for a
custom visualization, but if we want to use the HighCharts library, there are a few updates that need to
be made.
1. In your CLI, type CTRL-C

2. Answer “Y” to the Terminate batch job question
3. Run the following commands one at a time:
npm install highcharts –save
npm install highcharts-more –save
npm install highcharts-sunburst --save
4. Open Windows File Explorer
5. Navigate to the custom visualization folder
6. Open externals.d.ts in a text or code editor
a. Replace with the following:
declare module "highcharts";
declare module "highcharts/highcharts-more";
b. Save and close externals.d.ts
7. Open package.json in a text or code editor
a. Review the dependencies section. It should have the following:
"dependencies": {
"@businessanalytics/customvis-lib": "file:customvis-lib.tgz",
"highcharts": "~9.2.0",
"highcharts-more": "^0.1.7"
"highcharts-sunburst": "^0.1.7"
},
b. Close package.json
8. In your CLI, run the following command:
customvis clean
This removes all the dependency files from the project folder leaving only the main source code

customvis start
a. This redownloads all the necessary dependencies and compiles the visualization code.
Your CLI should end with “Started a local server on port 8585”.
Save Point #1 -- If your files did not look like the above or something went wrong, you can download the
Step 1 file from the PM2 Download Site.
Use password: PM2BACon2021
Check the box next to “Step1_HighchartLib_YourName - Custom Sunburst.zip” and click Download in the
top left corner. Unzip this file on your machine and open a CLI in that folder. You should be able to
continue from that point.
Create HighCharts Visualization
1. Navigate into the “renderer” folder

2. Open Main.ts in your text or code editor
3. Update the import statement at the top to the following:
import { RenderBase, UpdateInfo, DataPoint, Point, Color, FormatType } from
"@businessanalytics/customvis-lib";
import Highcharts from "highcharts";
import More from "highcharts/highcharts-more";
import SunburstModule from 'highcharts/modules/sunburst';
More( Highcharts );
SunburstModule(Highcharts);
a. The top line imports all the different data types available from the customvis library. We
may not use all of them in this code, but we have them available as needed.
i. See CustomViz API for more info
b. Highcharts and highcharts-more are two different libraries that we will use to create our
custom viz.
c. More(Highcharts) just ties the two libraries together and get the “more” part ready to
use.
d. SunburstModule(Highcharts) ties the Sunburst library together as well.

4. Within the class object, add the following line:
private _chart: any;
a. This is local variable that will store the chart object
5. Update the “create” method to the following by removing the line with “Basic VizBundle”:
protected create( _node: HTMLElement ): HTMLElement

{
return _node;
}
6. Add a Highcharts object to the create method:

protected create( _node: HTMLElement ): HTMLElement
{
this._chart = Highcharts.chart( _node,
{
chart: {
type: "sunburst"
},
title: {
text:"This is my chart"
},
series:[{data:[1,5,3,7,6]}]
}
);
return _node;
}
a. Highchart.chart creates the chart object
b. _node points to the Dashboard widget in Cognos
c. By passing _node to the Highchart method, it knows where to place the chart
d. Everything else defines the chart being created
7. Save the file
8. Review CLI for a “Finished building” message
a. You may need to CTRL-C to restart customvis
9. Test the chart in the Cognos Dashboard

Save Point #2 -- If your chart does not look like the above or something went wrong with compiling your
code, you can download the Step 2 file from the PM2 Download Site.
Check the box next to “Step2_InitialChart_YourName - Custom Sunburst.zip” and click Download in the
Make the chart resizable
Now we have a basic chart working, but it doesn’t do much. If you try making it bigger or smaller, the
chart stays the same. We need a way for the chart to get updated.
1. An update method is part of the custom visualization library. It gets called every time the size of
the chart, a property, or the data is changed.
Add an update method:

protected update( _info: UpdateInfo ): void
{
let updateOptions: any = {};
if ( _info.reason.size )
{
updateOptions.chart =
{
width: _info.node.clientWidth,
height: _info.node.clientHeight
};
}
if ( Object.keys( updateOptions ).length > 0 )
this._chart.update( updateOptions, true, true );
}
a. updateOptions is a variable used only within the update method. It’s set to an object by
default.
b. If _info.reason.size is set, it means that the size of the object on the Dashboard has
changed. Set the height and width of the chart to match the height and width of the
Cognos widget.
c. The last if-statement says that if updateOptions has any values, then update the chart
with those values.
2. Save the updates
3. Review the CLI to make sure they compiled
4. Refresh the chart on the Dashboard
5. Try resizing the chart to see if it works
Check the box next to “Step3_ChartResize_YourName - Custom Sunburst.zip” and click Download in the

Connect the Data – Part 1
Cognos has the chart in the Dashboard, but we need a way to pass it some data instead of having it
hardcoded.
1. From the main MyCustomViz folder, open the file vizdef.xml in your text or code editor
a. For more information on this file, see the Visualization Definition Guide
2. Add slots and dataSets:
<?xml version="1.0" encoding="UTF-8"?>
<visualizationDefinition version="3.1"
xmlns="http://www.ibm.com/xmlns/prod/ba/vipr/vizBundle/vizdef.3">
<slots>
<slot name="categories" caption="Categories" type="cat" optional="false" />
<slot name="values" caption="Values" type="cont" optional="false" />
</slots>
<dataSets>
<dataSet>
<ref slot="categories" />
<ref slot="values" />
</dataSet>
</dataSets>
</visualizationDefinition>
a. Slots add a space on the visualization add a data item from Cognos
i. The first slot is of type “cat” or “categorical”. This is used for any dimension type
data.
ii. The second slot is of type “cont” or “continuous”. This is used for any measure
type data.
b. dataSets tie that slot with an object that gets passed back to our custom visualization
code
3. Save the file
4. Review the CLI. It should say “Generating vizdef.xml”
5. In Cognos, delete the visualization from the Dashboard panel
6. Add the Test visualization back in from the Custom tab under Visualizations
a. This is needed when the vizdef.xml changes. They are not picked up when only doing a
refresh.
7. There should now be fields available:

8. The fields exist, but they aren’t connected to anything. You can add data items, but you’ll still
only see the hardcoded chart. Next up, let’s tie them together.
Check the box next to “Step4_SlotsAdded_YourName - Custom Sunburst.zip” and click Download in the

Connect the Data – Part 2
1. Go back to Main.ts in your text or code editor

2. In the create method, remove the “series” line to take out the hardcoded values
3. The chart definition should look like this:
this._chart = Highcharts.chart( _node,
{
chart: {
type: "sunburst"
},
title: {
text:"This is my chart"
}
}
);
4. In the update method, add another if-statement to handle if the data changes. It should be at
the same level as the size change if-statement and before the chart update at the bottom of the
method.
if( _info.reason.data )
{
updateOptions.series = [
{
data: transformData(_info.data.rows)
}
]
}
5. This if-statement adds a series array that contains a data element. Instead of the hardcoded
values we previously included, this will allow us to use data from Cognos.
6. The data attribute has a function called “transformData”. We need to define what the function
does, but it’s needed because the data coming from Cognos is not in the right format for
HighCharts.

7. Let’s define the transformData method to format the data how HighCharts expects.
a. Just below the imports and above the start of the class, add a function:
function transformData(rows:Array<DataPoint>) : any {

var result = [{"name":"Total","id":"total","parent":null,"value":null}];
var keys = [];
rows.forEach(row => {
for (var i = 0; i < row.tuple("categories").segments.length; i++) {
if(!keys.includes(row.tuple("categories").segments.slice(0,i+1).map(e => e.caption).join("|"))) {
keys.push(row.tuple("categories").segments.slice(0,i+1).map(e => e.caption).join("|"));
result.push(
{
"name":row.tuple("categories").segments[i].caption,
"id":row.tuple("categories").segments.slice(0,i+1).map(e => e.caption).join("|"),
"parent": i == 0 ? "total" : row.tuple("categories").segments.slice(0,i).map(e => e.caption).join("|"),
"value": i == row.tuple("categories").segments.length-1 ? row.value("values") : null
}
);
}
}
});
return result;
}
b. This function iterates through all the rows from the Cognos data and generates a result
array that gets passed to Highcharts. This result array contains objects that have four
attributes: name, id, parent, and value. Depending on the level, some attributes may be
null. For instance, the value attribute is only populated at the lowest level of data.
8. Save the file
9. Validate it compiles in your CLI
10. Refresh the chart in Cognos
11. Add a source for you Dashboard
a. Public Folders → Data → 2019 NFL Game Data
12. Add “down” as Categories
13. Add “play_id” to the Values field
14. This should result in a chart that shows us how many plays there were for each down. It should
look like this:

Check the box next to “Step5_DataConnected_YourName - Custom Sunburst.zip” and click Download in
the top left corner. Unzip this file on your machine and open a CLI in that folder. You should be able to

Add Properties
This gets us a basic chart that displays data, but it doesn’t provide very many configuration options. For
instance, what if I wanted to add my own title? Let’s add a couple properties to be able to customize it.
1. In your text or code editor, open the vizdef.xml file

2. Under the “DataSets” section but before the “</visualizationDefinition>” tag, add the following:
<properties>
<group name="labels" caption="Label Properties">
<boolean name="showChartTitle" caption="Show Chart Title" defaultValue="true" />
<string name="chartTitle" caption="Chart Title" defaultValue="MyChart" />
</group>
</properties>
3. Adding these properties to the vizdef.xml will make them display in Cognos in the visualization
properties, but they won’t do anything we tie them to our HighChart viz in the code.
4. Open Main.ts in your text or code editor
5. In the “update” method, add another if-statement like this:
if ( _info.reason.properties )
{
updateOptions.title = {
text: _info.props.get ("showChartTitle") ? _info.props.get ("chartTitle") : null
}
}
Let’s break down what that is doing. The if-statement is checking the reason for the call to
update. If the reason is because of a property change, then execute this code.
updateOptions.title is setting the title attribute for the HighCharts chart, and specifically we’re
setting the “text” attribute. _info.props.get(“showChartTitle”) is looking at the property with the
name “showChartTitle”. In this case, that’s a Boolean value. If it’s set to True, then populate the
text attribute with the value in the “chartTitle” property. If it’s False, then set the text attribute
to null.

6. Test adding and removing chart title in Cognos
Check the box next to “Step6_CustomTitle_YourName - Custom Sunburst.zip” and click Download in the

More Configuration
The chart is functional now, and we can change the title. It’s still pretty bland though with only one
color. Let’s add some more configuration options to make a little more interesting.
1. Open Main.ts in your editor of choice

2. Review https://api.highcharts.com/highcharts/series.sunburst.colorByPoint
3. Add a line to the series update, next to the data call to the transformData function
{
{
colorByPoint: true,
data: transformData(_info.data.rows)
}]
4. Refresh the chart in Cognos:

5. What is N/A for a down? Let’s add play_type to the Categories and see what we it tells us.
6. That answers the question, but as we add levels like this, the color becomes a bit too much. We
can add some more configuration to make it look better. Instead of coloring every section
differently, we can make some adjustments based on the level. Review
https://api.highcharts.com/highcharts/series.sunburst.levels

7. Remove the colorByPoint attribute and add a levels attribute like this:
{
data: transformData(_info.data.rows),
levels: [{
level: 1,
color:"#FFFFFF"
}, {
level: 2,
colorByPoint: true
},
{
level: 3,
colorVariation: {
key: 'brightness',
to: -0.5
}
}, {
level: 4,
colorVariation: {
key: 'brightness',
to: 0.5
}
}]
}]
Level 1 is set to White. Level 2 is set to color by point. Levels 3 and 4 are to adjust the brightness of
Level 2 for their colors. This helps lower levels stay visually tied to their parent levels.

8. Refresh the chart in Cognos, and it should look something like this:
9. These are the default colors provided by HighCharts. We can also set our own set of colors. In
the “update” method under the properties change if-statement, add a line for setting colors. It
should look like this:
if ( _info.reason.properties )
{
updateOptions.title = {
text: _info.props.get ( "showChartTitle") ? _info.props.get ( "chartTitle") : null
};
updateOptions.colors = ['#33728f','#58508d','#bc5090','#ff6361','#ffa600'];
}

Check the box next to “Step7_LevelColoring_YourName - Custom Sunburst.zip” and click Download in

Third Down Conversion Analysis
Now that we have a pretty functional sunburst chart, let’s go back to our use case. We wanted to know
how the distance to go and type of play affected the result.
1. Remove all the Categories

2. Add Third Down Analysis Filter
a. Includes a few things to help narrow down to only third downs and regular offensive
plays
3. Add yrdtogo_grouping
a. Short: 3 yards or less
b. Medium: 4 to 7 yards
c. Long: 8 or more yards
4. Add result_first_down_text
5. Update chart title

6. Add play_type between the two categories. It should go yrdtogo_grouping, play_type, then
result_first_down_text

7. Add play_location under play_type
Now we can get a good sense of how many plays there were at each category breakdown, as well as the
success rate of different selections. For instance, look at the success of a pass up the middle on a
medium distance to go. Compared to passes to the left or right, it results in success a higher percentage
of the time, but there are significantly fewer pass plays up the middle compared to left or right.

Allow Drill Down (traversing)
Now that we have 4 levels in our sunburst chart, it can get difficult to see the outside slices. Let’s add
one more property to the chart to help with that.
1. Open Main.ts in your editor

2. In the update function, within the series definition, add an attribute called
“allowTraversingTree” and set it to true. It should look like this:
{
{
allowTraversingTree: true,
data: transformData(_info.data.rows),
levels: [{
level: 1,
…
3. Save the update

4. Refresh the chart in Cognos
5. Click on any of the sections of the sunburst

Here’s an example of clicking on the “Medium” distance. It gives us a much better view of the
Run section of the sunburst.
6. Click on the center circle or the “Back” button to go up a level.
Check the box next to “Step8_CompletedViz_YourName - Custom Sunburst.zip” and click Download in

Package and Deploy
At this point, we might want to share our visualization with someone else. They may find it useful, or we
could at least get feedback on what other customizations should be made.
1. Open the command line interface

2. Type CTRL-C
3. Answer “Y” to the Terminate batch job question
4. Enter the following command:
customvis pack
5. Option #1
a. If you have the appropriate privileges in your environment, open the Manage panel
b. Select Customization
c. Select Custom Visuals
d. Upload the zip file from your “YourName Custom Sunburst” directory
e. Open Dashboard or Report
f. Go to Visualizations and the Custom tab
g. Your visualization should now appear in the list for all users

6. Option #2
a. In Dashboard or Report there is an option to Add Custom Visual
b. Dashboard:
c. Report:
From there you can add a special icon or add further description to help other users understand your
visualization in the package.json file. As you make updates, just pack them up again and update the
visualization through the Manage panel. All existing Dashboards and Reports will have the updated
version automatically.

Final Deployable Visualization – If anything went wrong along the way but you would still like to have a
custom Sunburst Chart for your environment, you can download the file from the PM2 Download Site.
Check the box next to “Custom Sunburst.packed.zip” and click Download in the top left corner. This zip
file is ready to upload to any 11.2.0 (may work with later 11.1 releases as well) and use in your
Dashboards and Reports.
Other Things to Note
• If you want to distribute the code, use the “customvis clean” command to remove the
dependencies from the folder. This will make it significantly smaller and easier to share.
• After running “customvis pack”, the packaged zip file contains everything needed to deploy the
visualization, but the TypeScript code will be compiled into JavaScript.

BACon 2021 Custom Viz in Cognos

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BACon 2021 Custom Viz in Cognos

Uploaded by

Copyright:

Available Formats

BACon 2021

Creating Custom Visualizations in Cognos

• Installing the Cognos Analytics custom visualizations CLI tools

sudo npm install -g customvis.tgz

Confidential & Proprietary

Create a Base Custom Viz

customvis create “YourName Custom Sunburst”

cd “YourName Custom Sunburst”

Confidential & Proprietary

11. Your custom visualization should say “Basic VizBundle”

Confidential & Proprietary

Review HighCharts Options

API Docs: https://api.highcharts.com/highcharts/

Add HighCharts Library to the Project

1. In your CLI, type CTRL-C

Confidential & Proprietary

Use password: PM2BACon2021

Create HighCharts Visualization

1. Navigate into the “renderer” folder

Confidential & Proprietary

protected create( _node: HTMLElement ): HTMLElement

6. Add a Highcharts object to the create method:

Confidential & Proprietary

Use password: PM2BACon2021

Make the chart resizable

Confidential & Proprietary

Use password: PM2BACon2021

Confidential & Proprietary

Confidential & Proprietary

Use password: PM2BACon2021

Confidential & Proprietary

1. Go back to Main.ts in your text or code editor

Confidential & Proprietary

function transformData(rows:Array<DataPoint>) : any {

Confidential & Proprietary

Use password: PM2BACon2021

Confidential & Proprietary

1. In your text or code editor, open the vizdef.xml file

Confidential & Proprietary

Use password: PM2BACon2021

Confidential & Proprietary

1. Open Main.ts in your editor of choice

Confidential & Proprietary

Confidential & Proprietary

Confidential & Proprietary

Confidential & Proprietary

Use password: PM2BACon2021

Confidential & Proprietary

1. Remove all the Categories

Confidential & Proprietary

Confidential & Proprietary

Confidential & Proprietary

1. Open Main.ts in your editor

3. Save the update

Confidential & Proprietary

6. Click on the center circle or the “Back” button to go up a level.

Use password: PM2BACon2021

Confidential & Proprietary

1. Open the command line interface

Confidential & Proprietary

Confidential & Proprietary

Use password: PM2BACon2021

Other Things to Note

Confidential & Proprietary