From SpagoBI to Knowage

Stephen Ogutu (CBIP, OCP)

 Copyright © 2017 by Stephen Ogutu

All rights reserved, including the right to reproduce this book or portions thereof in any form
whatsoever. For information, address:

Stephen Ogutu,
P.O. Box 8031-00200
Nairobi Kenya.

Trademarks: All other trademarks are the property of their respective owners. Stephen Ogutu
is not associated with any product or vendor mentioned in this book.

Limit of Liability/Disclaimer of Warranty: While the publisher and author have used their best
efforts in preparing this book, they make no representations or warranties with respect to the
accuracy or completeness of the contents of this book and specifically disclaim any implied
warranties or merchantability or fitness for a particular purpose. No warranty may be created
or extended by sales representatives or written sales materials. The advice and strategies
contained herein may not be suitable for your situation. You should consult with a professional
where appropriate. Neither the publisher nor author shall be liable for any loss or profit or any
other commercial damages, including but not limited to special, incidental, consequential, or
other damages.

1
Dedication
This book is dedicated to all fathers who go back home to their children every evening. God
bless you for bringing up a responsible generation and being there for your wives.

2
Contents
INTRODUCTION ............................................................................................................................................ 6
Business Intelligence with Knowage ........................................................................................................... 7
Business Intelligence ................................................................................................................................ 8
Introduction to Knowage ..................................................................................................................... 9
Knowage Suite ...................................................................................................................................... 9
Knowage BD.......................................................................................................................................... 9
Knowage SI ........................................................................................................................................... 9
Knowage ER .......................................................................................................................................... 9
Knowage LI.......................................................................................................................................... 10
Knowage PM ....................................................................................................................................... 10
Knowage PA ........................................................................................................................................ 10
Installing Knowage ............................................................................................................................. 11
A word about Metadata..................................................................................................................... 15
OLAP (Online Analytical Processing) ......................................................................................................... 17
OLAP (Online Analytical Processing) ..................................................................................................... 18
Your first OLAP document in Knowage ................................................................................................. 24
Step 1: Load database. ....................................................................................................................... 24
Step 2: Create Data source connection. ............................................................................................ 25
Step 3: Create Business Model .......................................................................................................... 27
Step 4: Mondrian Schema. ................................................................................................................. 32
Creating a schema .................................................................................................................................. 32
Mondrian Schema Catalog ................................................................................................................. 58
Creating OLAP document ................................................................................................................... 59
Location Intelligence with SVG Viewer Engine ..................................................................................... 69
What is Location Intelligence? ............................................................................................................... 70
The Problem. .......................................................................................................................................... 71
Solution................................................................................................................................................... 71
Creating SVG map with Inkscape. .......................................................................................................... 71
Template ................................................................................................................................................. 81
Dataset.................................................................................................................................................... 82
GIS with Knowage ...................................................................................................................................... 86
Introduction to GIS ................................................................................................................................. 87

3
 Scenario one ........................................................................................................................................... 89
Solution................................................................................................................................................... 89
QGIS ........................................................................................................................................................ 91
GeoServer ............................................................................................................................................... 95
GeoJSON ............................................................................................................................................... 102
Knowage with GIS ................................................................................................................................ 105
GIS Document ....................................................................................................................................... 109
Attribute table ...................................................................................................................................... 118
Charts and Cockpit ................................................................................................................................... 128
Introduction to cockpits ....................................................................................................................... 129
Charts .................................................................................................................................................... 129
Assignment. .......................................................................................................................................... 140
Key Performance Indicators ..................................................................................................................... 141
Strategy................................................................................................................................................. 142
Performance measurement ................................................................................................................. 142
Key performance indicators ................................................................................................................. 142
KPI in Knowage. .................................................................................................................................... 142
STEP 1 – Measures definition. ............................................................................................................. 142
STEP 2 – KPI definition. ........................................................................................................................ 144
STEP 3 – KPI Scheduler. ........................................................................................................................ 147
STEP 4 – KPI Document. ....................................................................................................................... 148
Knowage Report Designer ....................................................................................................................... 152
BIRT ....................................................................................................................................................... 153
Database connection............................................................................................................................ 158
Publishing Report. ................................................................................................................................ 165
Creating a dashboard with BIRT and Knowage ....................................................................................... 171
Creating a dashboard with BIRT and Knowage ................................................................................... 172
Problem to be solved by dashboard. ................................................................................................... 173
SOLUTION. ............................................................................................................................................ 173
Report parameters ................................................................................................................................... 196
Introduction .......................................................................................................................................... 197
BIRT report parameter .................................................................................................................... 198
List of Values (LOV). ....................................................................................................................... 201

4
 Analytical Drivers ................................................................................................................................. 203
Cross Navigation with BIRT and Knowage ................................................................................... 210
Introduction. ...................................................................................................................................... 211
The Master Document. ........................................................................................................................ 212
Problem to be solved by cross navigation........................................................................................... 212
SOLUTION. ............................................................................................................................................ 213
Child Report. ......................................................................................................................................... 219
Analytical Driver. .................................................................................................................................. 223
Cross Navigation Definition ................................................................................................................. 227

5
 INTRODUCTION
How much information you learnt in school do you actually use in your daily life? Not so much I
guess. Most books contain hundreds upon hundreds of pages and the reader gets lost in so
much detail they just give up. In writing this book, I have decided to cover only the important
subjects in Knowage so that at the end of it, you will be productive in this technology. You can
then use the online documentation available on Knowage website to continue you journey in
this beautiful piece of software. This book has been written to both the non-technical and
technical user who just wants to download and start using Knowage immediately for his
Business Intelligence assignment or to provide better reports for his company. I have decided to
call this book baby steps because it is really a step by step guide for someone who is just
beginning his or her thousand-mile journey in Knowage and Business Intelligence. This book is
not meant for the expert. Let us begin by taking our first step on the next page.

6
 LESSON ONE

Business Intelligence with Knowage

OBJECTIVES
After completing this chapter, you should be able to:

1. Describe the importance of Business Intelligence to an Organization.

2. Download, install and configure Knowage.
3. Login to Knowage and describe the various components.

CONTENTS

 Introduction to Business Intelligence.

 Introduction to Knowage.
 Knowage components.
 Configuring Knowage.

7
Business Intelligence

The world today generates terabytes of data from many sources. Millions of tweets, Facebook
updates and emails are sent each day. Millions of transactions occur in the financial and retail
sector every hour. How do we make use of this vast amount of data to the benefit of business?
How do you present the information to the management in an easy to use format? For
decades, many IT managers have relied on the big software corporations to provide them with
the business intelligence software that can help with the task of generating and presenting the
required reports and performing data analytics. Fast forward to this last decade, it is not only
the big businesses that generate vast amounts of data but also small startups that have online
presence.

A web startup might require business intelligence software to make sense of customers that
visit their web site. Traditional business intelligence software does not come cheap and before
the advent of the open source software, it was almost impossible for businesses with small
budgets to afford BI software.

Thankfully, the open source community has produced wonderful business intelligence software
which is easy to use and can be deployed in an enterprise setting. Knowage is a business
intelligence software from Italy which is licensed under the Affero GPL v3 and supports all the
components of business intelligence such as OLAP, dash boards, reports and charts. Knowage
comes in two versions; Community Edition and Enterprise Edition. We will be using the
Community Edition.

According to the online encyclopedia Wikipedia, Business Intelligence refers to computer-based

techniques used in identifying, extracting and analyzing business data, such as sales revenue by
products and/or departments, or by associated costs and incomes. Business Intelligence
technologies provide historical, current and predictive views of business operations. Common
functions of business intelligence technologies are reporting, online analytical processing,
analytics, data mining, process mining, complex event processing, business performance
management, benchmarking, text mining and predictive analytics.

Business Intelligence systems are very important for decision making and sometimes they are
referred to as decision support systems. To put this in perspective, assume you are the CEO of a
large bank. Which kind of information would you like to know about your bank at any given
time? You might want to know how many account holders are in a certain age group, for
example so as to make a decision on which products best suits them or you may want to know
how much you spend to acquire a customer. Naturally, you always want to know what your
competitor is doing. This is in a branch of Business Intelligence called Competitive Intelligence.

8
Introduction to Knowage
Knowage is an open source business intelligence suite from Italy and is licensed either as
community edition or enterprise edition. In their website, the developers state that
“… Knowage Community Edition is not a toy version or a trial with relevant restrictions. Coming
from the long history of SpagoBI, Knowage Community Edition includes the whole set of
analytical capabilities and guarantees a full end-user experience”. The community edition
therefore can be used in a production environment. Throughout this book, we will take you
through all the analytical capabilities of knowage community edition so that by the end of the
book, you should be ready to use it for your business intelligence project. The community
edition is released under the Affero GPL v3 license so that means you can get the source code,
distribute copies of it and even modify it. You can use the link below to read the entire license:

https://www.gnu.org/licenses/agpl-3.0.en.html

Knowage Suite

Knowage is composed of several modules which can be used individually or combined to make
a complete solution. It is composed of the following modules:

Knowage BD
This is the module used for the analysis of large datasets or what is commonly referred to as big
data.

Knowage SI
Knowage Smart Intelligence (SI) is used with traditional data sources available in the Enterprise
to produce:

1. Multidimensional analysis (OLAP).

2. Reports
3. Cockpits

It also supports self-service BI, adhoc reporting and multitenancy.

Knowage ER
Knowage Enterprise Reporting (ER) is used to produce static reports with parameters using
traditional data sources. The reports can be tabular, have charts or infographics and can be
exported to CSV, RTF or XLSX, PDF, XLS. The reports can be accessed online or scheduled to be
sent to respective users at specified time.

9
Knowage LI
Knowage Location Intelligence (LI) is used to visualize data as a map and supports both dynamic
maps such as Web Map Service (WMS), Web Feature Service Interface Standard (WFS) and
static maps (SVG).

Knowage PM
Knowage Performance Management (PM) is used to measure and evaluate business
performance through the use of KPI’s and scorecards.

Knowage PA
Knowage Predictive Analytics (PA) is used to perform forecasts through the use of data mining.
It supports the use of languages such as R or Python and can also perform What-if analysis

10
Installing Knowage
We will be using the Community Edition of Knowage so go to the link
http://forge.ow2.org/projects/knowage and select Knowage Server. As at writing this book, the
version that was available for download was Knowage Installer 6.0.0 CE. Select this version and
download for your platform.

Secondly, download and install MySQL as it will be needed by Knowage. MySQL can be
downloaded from https://www.mysql.com/downloads/
When you begin installation of Knowage, the first screen will be the welcome screen. Click on
Next on this screen.

On the next screen, you need to accept the GNU AFFERO GENERAL PUBLIC LICENSE and click on
next.

11
On the next screen, we will select Chart.js as the other options are not open source. If you have
license for or you want to pay for Highcharts JS, then you are free to do so.

We will be installing all modules of Knowage so select everything on the next screen.

12
Then select the destination directory. We will install in C:\knowage\server and click Next.

13
On the next screen, you will be asked for MySQL settings. This will create a database called
knowage_ce that will hold the Knowage metadata. Click on Next.

Once everything has been specified, installation will begin.

14
Once the installation is complete, you will get the screen below. Click on Finish for it to create
desktop links for starting and stopping Knowage.

A word about Metadata

Knowage Community Edition needs a database to store its own data for authorization,
schedules, configurations, alerts and several other things. This information is called metadata
and is stored in the MySQl database that you provided above. If you navigate to the MySQl
database knowage_ce, you will find several tables created by Knowage installer as shown
below. These are the metadata tables.

15
16
 LESSON TWO

OLAP (Online Analytical Processing)

OBJECTIVES
After completing this chapter, you should be able to:
1. Describe the importance of OLAP to your business.
2. Compare between pivot table in excel and OLAP document in Knowage.
3. Create Mondrian schema.
4. Create OLAP documents in Knowage

CONTENTS

1. Introduction to Online Analytical Processing (OLAP).

2. OLAP cubes.
3. Star and Mondrian Schema.
4. Step by step example.

17
OLAP (Online Analytical Processing)

Prepare the database.

The data for this assignment is in the MySQL dump foodmart.sql. If you have not already done so, load
the MySQL dump in your database so that you follow along. Secondly, you will also need the csv file
OLAP.csv and Microsoft excel to perform comparisons between OLAP and Pivot tables.

Online Analytical Processing (OLAP) enables one to analyze different dimensions of

multidimensional data. It enables one to analyze data from different perspectives. Consider
sales data as an example. One might be interested in analyzing sales data in terms of the date
when the sale occurred, the region the sales occurred and the store the sales occurred. The
sales amount we are analyzing is called a measure. The way we analyze the measure (sales
amount) is called a dimension. Therefore, the sales date is one dimension of looking at the sales
data; the store where the sales occurred is another dimension of looking at the sales data. We
can therefore look at the sales data by date, by store etc.

To help you understand measures, dimensions and star schema, we would like to demonstrate
using simple data with one dimension and one measure for a fictitious company Shemma
Global.

Below is a sample problem description:

Shemma Global is a Business intelligence company that specializes in data mining and analysis.
They would like to view the memory usage of one of their servers by event time. The server
event logs are stored in a MySQL table as shown below.

From the diagram above, we are only interested in two columns, the event_date and
used_memory (highlighted in blue). The event_date is our dimension (how we would like to
view the data) and the used_memory is the value we would like to measure (the measure).

18
Normally dimension data like date, sales region e.tc are not stored in a fact table which has
measures but in a dimension table. A foreign key is then included in the fact table to link the
two. Consider a telecommunication company as another example. We would make the fact
table the central table in our schema surrounded by dimension tables as shown below. We call
this kind of schema a star schema.

In the above example, it is easy to answer questions like how many mobile phone subscribers
were activated in the last quarter or how many subscribers are postpaid or prepaid. If we were
to build an OLAP document for this assignment, we would build a single fact table (Table 1) and
link it to the dimension tables using foreign keys.

OLAP Cube
An OLAP cube is a collection of measures (facts) and dimensions. In the telecommunication
example above, we can create a cube which can answer questions like how many subscribers
were activated on a certain year, certain quarter or certain month, or how much airtime was
consumed by customers from Nairobi region or how many subscribers are in pre-paid.

19
If you run a business, you might want to monitor several aspects of it to help you in planning
and decision making. You may want to know your customer behavior for example, the number
of men as opposed to women who patronize your business so that you create a specific product
or service for them. You might also want to monitor which product is performing well so that
you order more or which is not doing well so that you cancel its production. You might also be
interested in stores that are losing money so that you make a decision on whether to close
them or make changes in the processes or leadership. From this discussion, we see that a
business can be viewed from different perspectives which can be time, product, customer,
store etc.
The different perspectives are called dimensions when using OLAP (Online Analytical
processing). We can therefore see that most analysis is multidimensional. If you only have a
single dimension to consider e.g. time in month, then you do not need an OLAP tool and can
use a spreadsheet for example, as shown below in figure OLAP1.

Fig. OLAP 1

However, we know that businesses are normally complex and we have many variables to track.
For the remainder of this chapter, we will use the sample data shown in figure OLAP 2 below to
aid in our discussion.

20
Fig. OLAP 2

This data is from the sample foodmart database that comes with the SpagoBI All in one
installation. All we have done is to convert it from HSQLDB to both MySQL and Excel which we
will use to demonstrate OLAP. From the excel data in figure OLAP 2, there are six dimensions
that we want to track namely product, sales month, sales quarter, sale year, customer and
store. The three measures that we are interested in are store sales, store cost and unit sales.
To aid us in understanding OLAP in Knowage, we would like to present a simple problem and
solve it using excel. Once we understand how to do this in excel, it will become clear why OLAP
is a superior solution than excel.
Problem description:
Sega Foods Limited is a private company that owns several food stores throughout Kenya. The
General manager would like a report that summarizes:

1. The total store sales per store summarized by year, quarter and month.
2. Ability to compare sales between years, quarters and months.
3. The total store cost summarized by year, quarter and month.

Solution:

Open the Excel file Store Sale that came with this book. You will notice that under worksheet
Store Sale we have 251,359 rows of data that we want to analyze. The first column is the
product name, the second column contains the month the product was sold, the third column
has the sales quarter, followed by sales year, customer account, store name, store sales, store
cost and lastly unit sales as shown below.

The second worksheet Pivot, contains a pivot table that has the summaries of the data and can
therefore be used to answer the questions outlined above. So let us walk through the questions
answered by the pivot table then we will compare the result with Knowage.
Question One: What is the total sales per store summarized by year, quarter and month?

21
Before we can answer the question above, we need to understand what we are measuring. In
this case, it is sales per store. The question is, how do we need to look at the store sales? How
do we want to summarize it? This brings in the idea of time dimension. We want to summarize
the store sales using time but in what hierarchy? First, we will need a summary for the year,
then the quarter and lastly the month. So to use OLAP terms, store sales is the measure, and we
have three dimensions; year, quarter and month. The dimension hierarchy is:
1. Year
2. Quarter
3. Month

Solution 1: Excel
We can solve this problem using pivot table in excel as shown below. You can click on the
worksheet pivot on the file Store Sale to see how it is done.

From the pivot table above, we can get the total sales for each store summarized by year,
quarter and month. Let us take Store 11 for example, we can see that for 2011, the total sales
for this store was 55,044.29 (cycled in yellow). The total sales for quarter 2 was 14,333.48
(cycled in red) and sales for October was 4,077.27 (cycled in blue).
Solution 2: Knowage
Let us compare results above to what we would get if we used OLAP in Knowage.

22
Just like in excel, we can see that the store sale values for 2011 is 55,044.29 and total sales for
Quarter 2 is 14,333.48. So the values are the same. The question therefore is, why should we
use OLAP tool in Knowage if excel does the same thing and is easy to use? There are several
advantages of using Knowage over excel namely:
1. Knowage supports several datasets both traditional and big data.
2. It is easy to share as all you need is a browser.
3. It is secure and supports profiles for different users.
4. Supports what-if analysis
5. There is a limit to how much data excel can accommodate where as Knowage is limited
only by system resources and underlying DBMS or data source.

23
Your first OLAP document in Knowage
We have discussed what OLAP is all about and compared it the pivot functionality in excel. Now
we want to look at how to create an OLAP document in Knowage. We shall provide a step by
step tutorial to help you achieve this.

Step 1: Load database.

Navigate to the folder Database that came with this book and load the file foodmart.sql to your
database if you have not already done so. Here are the steps to load the file.
1. Visit the link https://dev.mysql.com/downloads/workbench/ to download the graphical
tool MySQl workbench that will help us import the data and easily manage MySQL.
2. Install MySQl workbench and connect to your MySQl server and select Data
Import/Restore.

3. On the next screen, click on Import from Self-contained file and select the foodmart.sql
file that came with this book.

24
 4. Click on start import. It will take you to a screen where you can monitor the import
progress.

Step 2: Create Data source connection.

Once we have imported the sample data we will need to demonstrate OLAP, we need to login
to Knowage instance that we installed previously and create a connection to the MySQL
database. Proceed as follows.
1. Navigate to http://localhost:8080/knowage and login with username biadmin and
password biadmin.

25
2. Click on highlighted region below to open menu.

26
 3. Under Data Providers, select Data source

4. Click on add new.

5. On the next screen:

a. For label use “MySQL Foodmart”.
b. For description, use “MySQL Database”.
c. For dialect, use MySQL.
d. For URL use jdbc:mysql://localhost/foodmart
e. Enter username and password
f. For driver, use com.mysql.jdbc.Driver
g. Click on Test. It should be successful.

h. Click on Save

Step 3: Create Business Model

To create a business model, proceed as follows:

1. Under catalogs, select Business Models catalog.

27
2. Select new button.

3. Use the following to fill the fields:

a. For name use “Sales Model”.
b. For description use “Sales Model”.
c. For category, use “Default Model Category”.
d. Select the “MySQL Foodmart” as data source then click on “Save”.
4. Click on enable “Enable Meta Web”

5. Click on “Meta Web”

6. Select the tables sales_fact, store and time_by_day. Ensure the checkbox for “Physical
Model” and “Business Model” are selected.

28
From our discussions on Dimensions and Fact tables in Lesson One, we will notice that
the table “sales_fact” is the fact table here as it contains all the measures that we want
that we will be summarizing for this cube. These measures are highlighted below.

Also notice that there are two important foreign keys; TIME_ID which is used to link the
sales_fact table to the dimension table time_by_day which contains the sales day, sales
quarter, sales year e.tc and STORE_ID which is a foreign key that links the sales_fact
table to the dimension table store. Our star schema therefore looks like this:

29
7. On the Business Model tab, expand Sales fact by clicking on the highlighted icon below.

30
8. Click on “STORE SALES” and change the type to Measure.

9. Do the same for “STORE COST” and “UNIT SALES”.

10. Click on Save

11. Under “BUSINESS MODELS' CATALOGUE”, click on “Sales Model” and then select
“Enable Meta Web”.

12. Next, select Generate.

31
 13. On the next dialog click on Create

14. Creation of the business model is now complete. Next we need to create a Mondrian
schema which together with the model we will use to create an OLAP document.

Step 4: Mondrian Schema.

We have now created our business model but before we use it in Knowage to create an OLAP
document, we need to create a Mondrian schema. So what is a schema? Basically, a schema is a
structure used to define either a relational database or multi-dimensional database. In a multi-
dimensional database, the schema is usually a star schema as we have discussed in previous
chapters. The schema defines several items including:

1. The logical model which describes the entities, relationships, attributes for entities etc.
2. How the logical model is mapped to the physical model.
3. Hierarchies which are levels of the dimension attribute. For example, for the time
attribute, we can have the following hierarchy:
a. Year
b. Quarter
c. Month

4. Members
5. Cubes

Creating a schema
A Mondrian schema is represented as an XML file and you can create one is a text editor like
notepad. However, this is a time consuming activity which we need not go through as there are
now graphical editors that can generate the schema XML which we can then upload into
Knowage to create our OLAP document.

32
Follow the steps below to download and install a free GUI tool to use in creating the schema.
1. Go to https://sourceforge.net/projects/mondrian/files/schema%20workbench/ and
download the latest version of Schema Workbench which is 3.14.0 as at writing this
book. This software is licensed under Eclipse Public License v1.
2. Both the Schema Workbench and Knowage requires Java so install the latest version in
the machine where you will be using these tools.
3. Once the Schema Workbench is installed, use the workbench.bat file to start it then
under Options, select Connection.

4. The connection menu is used to connect to the database that has the dimension and
fact tables. You need to connect to the foodmart database that came with this book as
shown below.

33
5. Click on File->New->Schema

34
6. Give the Schema a name “Store”.

7. The first thing we need to add is a cube. A cube is a collection of dimensions and
measures and to create one, click on “Add cube” button.

35
8. For the name of the cube use “Sales”, description use “Sales Cube”.

9. From the definition of a cube, remember it is a collection of dimensions and measures

and measures are normally found in a fact table so let us add a fact table. If you look
keenly at the image above, you will see a message “Fact name must be set” at the
bottom of the screen. This is because we have not added a fact table to our cube. To do
so, right click on the cube and click on “Add Table”

36
10. Select the sales_fact table from the foodmart database. This is the table that contains
the Measures we want to look at.

37
11. Apart from measures, the other component of a cube is a dimension. Infact, if you look
at the bottom of the image below, you can see that it says “Cube must contain
dimensions”. We have two dimension tables that we want to include in our cube
namely store and time_by_day. Right click on the cube and select “Add Dimension”

12. The first dimension we need to add is the time dimension that contains the year,
quarter and month the sale occurred. Therefore, for name of the dimension, use
“Time”. We also need to specify which column will be used by the fact table as a foreign
key to help link with the dimension table. For foreignKey, use “TIME_ID”.

38
13. Next, we need to add a hierarchy to our dimension. Click on the dimension and add for
name, use “Period”. Ensure hasAll is checked. allmemberName should be “Sales Period”.
The primaryKeyTable should be “time_by_day” and primaryKey should be “TIME_ID”.

39
14. Once you have added hierarchy, the next step is to add levels. Select the Period
hierarchy and click on add level.

15. The first level we want to add is year. Therefore, for the level name, use “Year”, the
table “time_by_day”, for description use “Year” and the column “THE_YEAR”.

40
16. Add the next which is Quarter with parameters shown below.

41
17. Finally on levels for this dimension add the month level as shown below.

42
18. To finish off with this hierarchy, add the dimension table by right clicking on Period
hierarchy and clicking on add table.

43
19. Select the dimension table time_by_day. That will be it for this dimension.

44
20. The next dimension we need to add is the store dimension. So again, right click on cube
and add dimension.

45
21. Use the properties shown below.

46
22. Next add the hierarch store with the following properties.

23. Under store, add one level called “Store”.

47
24. For this hierarchy, add the dimension table.

48
25. Our cube now has two dimensions, time dimension and store dimension. It also has a
fact table but what is missing are the measures. In the “sales_fact” table, what is it that
we want to measure? We will measure:
a. Store sales in the column “STORE_SALES”.
b. Store cost in the column “STORE_COST”.
26. Right click the sales cube, and select “Add Measure”

49
27. Use the following properties:
a. For name, enter "Store Sales".
b. For column, use "STORE_SALES".
c. For datatype, use "Numeric".
d. For formatString, use "$#,###.##".
e. For aggregator, use "sum".

28. Once done, it should appear as below.

50
29. Add another measure “store Cost” with the following properties.

51
30. Lastly, we want to show you how to add a calculated member. This will be the
difference between Store Sales and Store Cost. We will call it “Profit”. Right click on the
cube and select “Calculated Member”

52
31. Use the following:
a. For name use "Profit".
b. For formula, use "[Measures].[Store Sales] - [Measures].[Store Cost]".
c. For dimension, use "Measures"

53
32. Once you have added the calculated member, you need to add a calculated member
property where you will specify the format string. Right click on the calculated member
and select “Add Calculated Member Property”

54
33. For name use “FORMAT_STRING” and value “$#,###.##”

55
34. Save the schema as SchemaFoodMart.xml. It should look as follows.

56
<Schema name="Store">
<Cube name="Sales" visible="true" description="Sales Cube" cache="true" enabled="true">
<Table name="sales_fact" alias="">
</Table>
<Dimension type="StandardDimension" visible="true" foreignKey="TIME_ID" name="Time">
<Hierarchy name="Period" visible="true" hasAll="true" allMemberName="Sales Period"
primaryKey="TIME_ID" primaryKeyTable="time_by_day">
<Table name="time_by_day" alias="">
</Table>
<Level name="Year" visible="true" table="time_by_day" column="THE_YEAR" uniqueMembers="false">
</Level>
<Level name="Quarter" visible="true" table="time_by_day" column="QUARTER" uniqueMembers="false"
description="Quarter">
</Level>
<Level name="Month" visible="true" table="time_by_day" column="THE_MONTH"
uniqueMembers="false" description="Month">
</Level>
</Hierarchy>
</Dimension>
<Dimension type="StandardDimension" visible="true" foreignKey="STORE_ID" name="Store"
description="Store">
<Hierarchy name="Store" visible="true" hasAll="true" allMemberName="All Stores"
primaryKey="STORE_ID" primaryKeyTable="store" description="Store">
<Table name="store" alias="">
</Table>
<Level name="Store" visible="true" table="store" column="STORE_NAME" uniqueMembers="false"
description="Store">
</Level>
</Hierarchy>
</Dimension>
<Measure name="Store Sales" column="STORE_SALES" datatype="Numeric" formatString="$#,###.##"
aggregator="sum" visible="true">
</Measure>
<Measure name="Store Cost" column="STORE_COST" datatype="Numeric" formatString="$#,###.##"
aggregator="sum" visible="true">
</Measure>
<CalculatedMember name="Profit" formatString="" formula="[Measures].[Store Sales] - [Measures].[Store
Cost]" dimension="Measures" visible="true">
<CalculatedMemberProperty name="FORMAT_STRING">
</CalculatedMemberProperty>
</CalculatedMember>
</Cube>
</Schema>

57
Mondrian Schema Catalog
The schema that we have created above needs to be stored in Knowage as a Mondrian Schema
catalog. Once this is done, then we can use it together with the business model we had created
previously to create an OLAP document. Proceed as follows to save the schema to in Knowage.
1. Under Catalogs, select “Mondrian schemas catalog”.

2. Click on add button

3. For name use “Store” and description “Store Sales” and under “File Upload”, select the
SchemaFoodMart.xml file we had created previously.

58
 4. Click on Save.

Creating OLAP document

Finally, we have all the components we need to create an OLAP document. We have the source
database, we have the business model and we have the Mondrian schema. To create the OLAP
document, proceed as follows:
1. First, we need to create a folder where we will save our OLAP document. Under “Profile
Management”, select “Functionalities management”.

2. Create a new folder with the options below. This means that anyone with admin role
will be able to have full access to this folder. Save.

59
3. Click on “Document development icon”.

4. Select New button then “Generic Document”.

60
5. For label use “Store Sales”.
6. For Name use “Store Sales”.
7. For Description use “Store Sales”.
8. Under type, use “On-line analytical processing”.
9. For the engine, use “OLAP Engine”.
10. Select the data source where Foodmart database is created.
11. Under “Functionalities Tree”, select “OLAP” then Save.

61
12. Select “Generate new template”

13. For “Template Type” select Mondrian.

14. Select the Mondrian Schema we had created previously.
15. Select the cube

62
16. Click on “Start”. And you will have finished with your first OLAP document. By default, it
will show you the total sales for all periods for all stores.

17. Drag the Store dimension just beside the measures.

63
18. Click on the highlighted icon (+) to view all stores.

19. Then click on the measures filter (highlighted in yellow) so that we can add other
measures like cost and profit.

20. Select Store Cost and Profit and click on Save.

64
21. Now we can analyze the data in any way we desire.

22. There are some additional configurations you can do by clicking on the button shown
below on the right of the page.

23. Then selecting “Configure buttons visibility”

24. Then selecting the button you want to be visible and click on Save template and close
the designer.

65
25. You will then need to save the document. See yellow arrow below.

26. Click on the back button then execute the document.

66
27. Now you can see the buttons have been added.

28. Let us try one by viewing the OLAP MDX query

29. It will display the MDX query. Try to use the other buttons.

67
68
 LESSON THREE

Location Intelligence with SVG Viewer Engine

OBJECTIVES

After completing this chapter, you should be able to:

1. Describe what Location Intelligence is.

2. Describe the importance of Location Intelligence to your business.
3. Use the Knowage with SVG and GIS

CONTENTS
Location Intelligence.

 What is Location Intelligence?

 How is location Intelligence useful to an organization?
 Creating a location intelligence document, Step by Step.

69
What is Location Intelligence?

Location Intelligence is the integration of Business Intelligence and Geographical data. This
gives a visual representation of the data on a map.

Consider the document above. This is a document that shows the number of livestock that are
at risk due to famine to be used by a disaster preparedness organization. For
the policy makers, it would be easier to understand as they will be interested in regions with
red color. You can see that we have different tones of green color on the map. The regions
which have a higher tone like Upper Eastern have more livestock at risk compared to other
regions. In this chapter, we will learn how to create such documents. The document shown
above is created using both an SVG map and an xml template. Apart from the map and the
template, you will also need a source of data. So we need
70
to understand how to create these 3 components:

1. An SVG map.
2. An XML template.
3. Data source.

The Problem.
Assume you are a consultant for the Kenya Red Cross and you are tracking an upcoming famine
in the month of August. You have data from various provinces and regions in Kenya and you
would like to put them in a map so that you can project it in the big screen on the conference
room. The map will be updated automatically as data comes from the provinces.
Solution.
To solve this problem, we will need two things:
 We will need the data. For this exercise the data is in the table livestock_by_county in
the database bidb.
 We will need to create an SVG map.

SVG or Scalable Vector Graphics is XML based standard. We will be creating the map of Kenya
with its various regions. We can do this with a free tool called Inkscape or you can use Corel
Draw if you have a license for it. Instead of starting from scratch, follow these steps to create a
map based on an already existing map. If you are good with inkscape or Corel draw, you can
skip this and draw your own SVG map. Note that if you are not interested in creating the svg
map, there is already an existing one under the folder “Location Intelligence” with the CD that
came with this book. It is called Kenya_Map.svg. If you chose not to create the the map, jump
to step (iii) otherwise follow the following steps to create the map.

Creating SVG map with Inkscape.

1. Navigate to the link below to download a sample SVG map that we will modify.
http://upload.wikimedia.org/wikipedia/commons/2/2c/Kenya_location_map.svg

2. Once the map is opened in your screen, take a screenshot of the page and crop the
image using Microsoft Paint or any tool of your choice. Save the image as Kenya.png. If
you open your file, it should look like below.

71
 We will use this image as the base of our SVG map since we do not want to waste time
drawing the map of Kenya with all its borders.

3. Download and install Inkscape.

4. Open Inkscape.

5. Go to File->Open then Select the PNG image we had downloaded above.

6. Select embed.

72
7. You can see that the regions are already separated by lines so we will just use a fill tool
with white color to segment and name each region we need. We will start with Upper
Eastern, (III) on the map.

73
8. Click on the fill tool (I) then select the green color (II) and then click on the area III. The
map will change as show below.

9. To see how this region will look like in xml, use the selection tool to highlight it (I) then
click on Edit - > XML Editor (II).

74
10. Click on id (I) and on box (III), type the name of the region you had selected as “Upper
North Eastern” then click on “Set”.

75
 Note that the fill color is 00FF00 i.e green. We need to change it back to white so click
on fill and change it to fill:#ffffff i.e white. Why are we doing this? We do this because
once we are done with naming all regions, they should all be white and will only take
the color based on data from the database. Click on Set to make the changes
permanent.

11. Next we need to give the region a label so using the text tool, label it as “Upper North
Eastern” as shown below.

76
12. We are finished with the region “Upper North Eastern”. Now do the same for “Lower
North Eastern”.

13. Finish the other areas. Your map should look like this.

77
14. Now we need to select all regions and group them. Name this new group “county”. How
do you do this? Click on a region, say “Western” then hold down the shift key and then
click on the other regions. Once all the regions are selected, to group them, go to object
and select group.

15. When you look at the xml, it should be as shown.

78
Note that all regions are under the county group. So how will Knowage know how to color the
various regions based on the data from the database? It will compare the names of the regions
against a column called county in the database. This column will have names similar to the
various regions in the SVG map. So always ensure your group name is same as the column
name where the region names are stored. See below for a sample table we will be using for this
assignment.

79
IMPORTANT:

Open the SVG with a text editor, search for style="fill:#ffffff;stroke-width:1.1509186" or

equivalent and replace with fill="#ffffff". We have noticed that if you use the first one, then
your map will not be filled with color coding in Knowage!

Now save the file as Save.svg.Your map is ready!

SVG Catalog

Now that we have the map, let us load it into Knowage. Login to Knowage as user biadmin and
under Catalogs select SVG.

80
Click on Insert. Under name use KENYA_PROVINCES. For Description use “Kenyan Provinces”.
Enter “Kenya” as Hierarchy and 1 for Level and lastly county for Member. Then for Template,
browse for the file we created in previous step or if you did not create it, you can use the map
in the “SVG\Kenya.svg” from the resources folder that came with this book. Click on Save once
you are done.

Template
Now we that we have finished with the map, let us create the location intelligence
document template. Most documents in Knowage needs a template that defines the structure
and source of data and the location intelligence document that we are going to create is no
different. Remember up to this point, we have managed to create the SVG map to be used in
the document and saved it in Knowage with the name KENYA_PROVINCES. The template we are
going to create has the structure outlined below and will be rendered with the SVG Viewer
Engine.

NOTE: If you do not want to type in your own template, you can use the template that
came with this book under “SVG\Kenya_Livestock.xml”.

The HIERARCHY tag must match what we had used when saving the SVG file in Knowage
catalog. In the MEMBER tag, we need to specify the dataset where data will come from as
measure_dataset and the level must match what we had used in the SVG catalog.

81
Dataset
The final piece that is missing is creating the data set. From Knowage, create a dataset with
same name “kenya_county” which is what we have specified in the template above. It should
read from the table “livestock_by_county”. This is from the database bidb that came with this
book.

82
Create a document with the properties shown below

83
Save your document and execute. You will get the results below. Now highlight on any area,
having in mind that the stronger the color, the more livestock at risk in that area.

84
85
 LESSON FOUR

GIS with Knowage

OBJECTIVES
After completing this chapter, you should be able to:

4. Configure and use QGIS.

5. Configure and use GEOSERVER.
6. Describe properties of the attribute table.
7. Create a GIS template.

CONTENTS

 Introduction
 Qgis
 Geoserver
 Knowage
 The attribute table
 Template
 Cross Navigation

86
Introduction to GIS

Kung Fu means supreme skill from hard work. Preparation, endless repetition, until your mind is
weary, and your bones ache, until you're too tired to sweat, too wasted to breathe. That is the
way, the only way one acquires kung fu.

Hundred Eyes - Marco Polo (2014) Season 1

In this chapter, we will learn how to integrate Knowage business intelligence software and a
geographic information system (GIS). Business Intelligence systems are used to provide useful
information from the millions of transactions done by businesses daily while GIS systems are
used to analyze all types of geographical data. The marriage of these two systems provides a
powerful platform that is used for visual analysis of data that can be appreciated by even non-
technical users. This is not a chapter on GIS but rather a chapter on integration of GIS and
Business Intelligence. However, the reader does not need to have any background training on
GIS or Knowage because we will be introducing these concepts gradually and even readers new
to these technologies will be able to pick up.

87
Introduction to GIS
So what is GIS? We can say that it is any system that stores and analyses geographical data.
Several software does exist in the market that fills this role. Such software includes both
desktop and browser based variants such as Bing Maps, ArcServer, Google Earth, Arcmap and
QGIS. We will be using the free QGIS for this tutorial.

When dealing with GIS, we normally store two types of data:

1. Attribute data – This is textual data that describes features in the map for example
population information about countries. It basically says what a feature is.
2. Spatial data – This describes where the feature is to be found and is made up of
coordinates and other information about map features. Further, spatial data can either
be vector based or raster based. Vector based data uses paths to render the image while
raster uses pixels. In this book, we will see how to represent several features in a map as
vector consisting of points, lines, and areas. We will also use raster data. Do not worry
about this verbose description, it will become clearer once we begin the practical
exercise.

88
To aide us in learning GIS, we will be using a real world problem and providing its solution. So
let us first understand the problem outlined in Scenario one below.

Scenario one
The SpagoBI training website www.learn-spagobi.com has several students from different
countries all over the world. The owner wants to map the students in a map of the world so
that he can easily see which countries has the most users of his website. This will allow him to
customize the courses to better suit his audience. How can we use Knowage and GIS to achieve
this?

Solution

Diagram 1

89
Diagram 1 shows a sample location intelligence document that meets this need. We will create
a document similar to this in Knowage. If you look at diagram one keenly, you will notice
several things:

1. Colored cycles are used to represent countries that has students in learn-spagobi.com.
The size of the cycle denotes the number of students. A bigger cycle will represent more
students in a country as opposed to a smaller cyle. Later on in the course, we will also
see how to use thematic points with different colour coding to denote this.

2. The map has attribute data that gives more information about a country if a cycle is
clicked. For example, when we click on the cyce on Kenya, it tells us that the ISO code
for Kenya is KE, it gives us the population, longitude and latitude e.t.c. We will learn how
to add our own attribute data, how to modify existing attribute data and how to reat
attribute data from a relational database to make it dynamic.

3. Lastly, we note that this map came from existing sources like google map or any other
source with up todate maps. We will use maps from http://thematicmapping.org but
you can follow along with maps from your own sources.

90
QGIS

To help us provide a solution to what have been described in scenario one, get started with
Knowage and GIS, we will first need to download and setup a GIS software that we will need to
manipulate and view the maps that we will then be analyzed together with additional data, by
Knowage.

So what is QGIS? Wikipedia gives a very good summary of what this software is. Here is what
they say about it. QGIS (previously known as "Quantum GIS") is a cross-platform free and open-
source desktop geographic information system (GIS) application that provides data viewing,
editing, and analysis capabilities. Similar to other software GIS systems QGIS allows users to
create maps with many layers using different map projections. Maps can be assembled in
different formats and for different uses. QGIS allows maps to be composed of raster or vector
layers. Typical for this kind of software the vector data is stored as either point, line, or
polygon-feature. Different kinds of raster images are supported and the software can perform
georeferencing of images.
(http://en.wikipedia.org/wiki/QGIS)

Now if you check our requirements for scenario one above, you see that the first thing we need
is a world map. It is in the countries in this map that we will put cycles to denote a country
where a student resides, the bigger the cycle, the more students we have in that country. Since
we are not in the business of creating maps, we will need to download the world map from
somewhere. Again as we do not want to pay for this map, we can get one from a reputed public
source. Then once we have the map, we can use QGIS to modify its attributes. Follow these
steps.

1. Download QGIS Desktop 2.8.2 from

https://www.qgis.org/en/site/forusers/download.html
2. Install the QGIS software in your machine. It will come with several other software that
we will not be using e.g GRASS GIS 6.4.3, MSYS and QGIS Browser 2.8.2 and SAGA GIS
(2.1.2). We are only interested in QGIS Desktop 2.8.2.
3. From your desktop or start menu, click on QGIS Desktop 2.8.2. icon. It has the icon
similar to the one below.

91
4. This will open the QGIS desktop.

5. Now what we need is a map that we can manipulate in the QGIS software. Since in
SpagoBI we need to show location of all students that have enrolled at learn-
spagobi.com from all over the world, we will need to download a world map. You can
get one from here http://thematicmapping.org/downloads/TM_WORLD_BORDERS-
0.3.zip The file comes in a format called a shape file which is a data format for GIS
systems. The zip file when extracted will contain several files:

a. A file with the extension .shp which has the geometry data.
b. A file with the extension .shx which is the index for the .shp file. This allows you
to go backwards and forward on the .shp file faster,much like indexes do in a
book or a relational database.
c. A file with the extension .dbf which stores attributes for each shape. This file is in
the dBase format.
d. A file with the extension .prj which has the coordinate system and projection
information in the Well-known text (WKT) format.

92
6. Extract the map to the location E:\BI\TM_WORLD_BORDERS-0.3. You will notice that the
map comes as several files as discussed above.
a. TM_WORLD_BORDERS-0.3.dbf
b. TM_WORLD_BORDERS-0.3.prj
c. TM_WORLD_BORDERS-0.3.shp
d. TM_WORLD_BORDERS-0.3.shx

7. Now in QGIS, go to Layer Menu. Select Add Layer and click on Add Vector Layer as
shown below.

8. Browse and select the TM_WORLD_BORDERS-0.3.shp file then click on open.

93
9. It will load the map. Now let us look at the attributes of this map. Under Layers, right
click on TM_WORLD_BORDERS-0.3 and select “Open Attribute Table”

94
 10. This will allow you to view the attributes of the shapes. Do you remember, from our
discussion in step 5, in which file these attributes are stored?

In future, we will be using QGIS to change some of these attributes, modify column
names, delete attributes, change color of maps, make them transparent etc. but for
now, that will suffice for the introduction to QGIS.

GeoServer

Once we have modified the attributes of the map we had downloaded in QGIS, we will need a

95
way of publishing or distributing it to Knowage. We do this using another software called
GeoServer. This server allows you to share your map with a large audience who will just need a
URL to be able to access it. So now let us go to http://geoserver.org/ and download the latest
version of GeoServer in my case version 2.7.1.

Extract the file to the location C:\BI\geoserver-2.7.0-bin\geoserver-2.7.0 or any free location in

your computer. Geoserver by default uses the port 8080 so you might want to change it to
something else since SpagoBi also uses this as the default port. So open the file
C:\BI\geoserver-2.7.0-bin\geoserver-2.7.0\etc\jetty.xml and change the port to 8090

Then use the batch file on C:\BI\geoserver-2.7.0-bin\geoserver-2.7.0\bin\startup.bat to

startup the Geoserver.

96
Open a web browser and navigate to the URL http://localhost:8090/geoserver/web which is
the Geoserver URL. Login with username admin and password geoserver. The first thing we
need to create is a workspace. A workspace is used to organize the items you will be creating in
Geoserver. So to create a workspace, click on Workspaces (Arrow 1) then select Add new
workspace (arrow 2)

97
For name, enter learnspagobi and for the URI use http://learn-spagobi.com and make it the
default workspace then click on submit.

98
Next, we need to create a store. The store will be used to connect to a source of data which can
either be vector or raster. In our case, we will create a store which will connect to the shapefile
which we modified using QGIS previously. Remember, you can also have the data store come
from a database for dynamic maps.
Click on stores (arrow 1)and select add new store (arrow 2).

Select the first option, which is “Directory of spatial files (shapefiles)”

For workspace, use the workspace we created previously. For Data Source Name , use
WORLDMAP. Put any description you like. Then under Connection Parameters, browse for the
directory where we have the file TM_WORLD_BORDERS-0.3.shp and select it then click on save.

99
On the next screen click on publish.

Under Declared SRS (arrow 1) , enter EPSG:4326 and for SRS handling (arrow 2), use “Reproject
native to declared” then under “Lat/Lon Bounding Box” click on “Compute from native bounds”
(arrow 3) then save.

100
This will automatically create for you a layer called TM_WORLD_BORDERS-0.3. This is the layer
that we will call from Knowage. So let us check that it is working. Click on layer preview then
search for your workspace you just created. Then click on OpenLayers KM.

If you have done all the steps correctly, you can see that the map will be rendered. If you click
on any area of the map, it will show you details about it. If you check the image below, you can
see that we selected China. You can also zoom in and out of the map.

101
GeoJSON

You can directly call the map from geoserver in Knowage but we will show you how to use an
offline method by converting the map to a GeoJSON file that you can use even without an
additional overhead of geoserver. Follow these steps to create a GeoJSON file.

1. Under layer preview, in “All Formats”, scroll down to “WFS” and select “GeoJSON”.

2. Click on “Raw Data”.

102
3. Click on copy, paste in a text editor like notepad and save the file as “World.json”
4. Next, we need to create a layer catalog in Knowage using this file so that we can use it
to create GIS documents.
5. Under catalogs, select “Layers catalog”

6. Enter data as shown below then Save.

103
We will stop there for now, load some data into Knowage and see how to analyze it together
with this map.

104
Knowage with GIS
We have now learnt how to modify our map data using QGIS and how to publish this map in the
Geoserver ready for use by any map consuming application like Knowage.
Like we had stated before, we will use the following scenario to help us make a sample map.

The scenario:

The SpagoBI training website www.learn-spabobi.com has several students from different
countries all over the world. The owner wants to map the students in a map of the world so that
he can easily see which countries has the most users to his website. This will allow him to
customize the courses to better suit his audience. How can we use Knowage to achieve this?

From the scenario above, you can see that we need several things.
1. We need a world map. We have already loaded one in Geoserver and is ready to be
used by Knowage.
2. We need the student data that defines which country they come from so that we can
link it to the map data.

To achive number two above, that is load the student data, we will need to login to Knowage
and create a dataset called “SpagoBI Students” with the contents of the file GIS/Learn-
spagobi.com Users.csv which came with this book, proceed as follows:

Login to Knowage as user biadmin password biadmin. Navigate to Data Providers

-> Data Set.

Create a new dataset called DS_SPAGOBI_STUDENTS. Under detail tab, enter the following:

105
Under type, select file and upload the Learn-spagobi.com Users.csv file that came with this
book.

106
Put the delimiter and quote character.

Preview the file and if all is fine, save.

107
IMPORTTANT: - You should change STUDENTS to be of type measure otherwise you will have a
problem when trying to create indicators in the Knowage GIS template.

108
GIS Document

Finally, we are ready to create a GIS document. Follow these steps:

1. Create a generic document with these properties and click on “Save”.

2. Next click on “Template build”

3. Under “Layer”, click on “ADD LAYER” and select the json file we had saved in Knowage
catalog.

109
4. Under “Dataset join columns”, click on “ADD JOIN COLUMN”. This is where we link the
map with the data from Knowage data set. We will link them using the FIPS column.

5. Under “Indicators”, select “ADD INDICATOR”, then select “STUDENTS”. Remember this is
the value we want to output in the map. The STUDENTS column has the total number of
students per country. Therefore, it will be used to color the map.

6. Under “Filters”, select “COUNTRY”. This is what we will use to filter the map data. For
example, if we only want to view data for a particular country or countries, we will filter
using this column.

110
 7. Under “Map menu configuration”, select defaults.

8. Save the template.

IMPORTANT: This book also comes with a ready template which you can use by clicking on
“Browse” and selecting “World_Template.json” file. The file is in the GIS folder.

Now that you are finished with the template, execute the document. The output is shown
below.

111
Let us look at some of the map properties:

1. Under the Map tab, you can see that the default map type is “Map Zone” as shown
below.

112
2. However, this can be changed to “Map Point”

113
3. Since we had only specified on “INDICATOR”, we have it selected by default.

114
4. You can use the filter property to select only specific countries. In the example below,
we have selected Brazil only.

115
5. You can also use the config tab to change the colors and the method used (either
quantile or equals intervals).

116
117
Attribute table
If you click on any country, it will give you more information about that country. For example, if
we click on Brazil, it will give us information about Brazil as shown below.

So the question is, where do the information like population, longitude and latitude come
from? It is not in the dataset we created so where do Knowage get it? It gets it from the
attribute table. In case you do not want to display some of this data, you can simply delete it
using QGIS, or even add more information to be displayed if someone clicks on a country. We
can also read this data from a database to make it dynamic. For the shapefile we used,
physically, the information is stored in dBase, a type of database. So how do we view this
information and how do we modify it if we need to? We can use the QGIS software to do this.

Start your QGIS and open the TM_WORLD_BORDERS-0.3.shp shapefile as we had done
previously and open the attribute table.

118
Let us look at the information for Brazil from the attribute table highlighted below in red.

119
120
Compare this information to what we were getting in Knowage.

You can see that the data is similar which means that both the data in QGIS and the one in
Knowage came from the attribute table. From attribute table, we can see that Kenya’s
population is 35 million. Let us change it to 42 million using the editing feature.

Then enter the value 42,000,000 in the POP2005 field.

121
Save your attribute table. Now reload your Knowage document and check if the population
information have changed for Kenya. You will find that it is still reading the old values. This is
because Knowage is not reading the information directly from the shapefile but from the
GeoJson file you created using the Geoserver. So if you want the changes to be visible in
Knowage, you will need to reload the shapefile in the geoserver and and create a new GeoJson
file then upload to your layers catalog in Knowage.

What if you wanted to modify the column information in the attribute table? You might even
want to delete the column entirely. All these can be done using QGIS. Let us say we want to
delete the SUBREGION and modify POP2005 to be POP2015.

To make the changes above, proceed as follows.

1. Start the QGIS desktop.

122
2. We will need to download the Table manager plugin to help us modify columns. Click on
Plugins then select Manage and Install Plugins…

3. Search for Table manager then install it.

4. Now, on the left bottom of QGIS, click on the double arrows and click on Table Manager
icon.

123
5. Select POP2005 and select Rename.

124
6. Change it to POP2015.
7. Select subregion and then select delete.

125
8. Confirm deletion.

9. Save your new shapefile as World2.

126
10. Use this shapefile to create a new store in geoserver and from it a new GeoJSON file.
Load it in Knowage and check if the changes have taken effect.

127
 LESSON FIVE

Charts and Cockpit

OBJECTIVES
After completing this chapter, you should be able to:
8. Describe the importance of cockpits.
9. Create various charts in Knowage
10. Create cockpits in Knowage.

CONTENTS

 Introduction
 Charts
 Cockpits

128
Introduction to cockpits

Cockpits enable us to get a snapshot of the business as at a particular point in time. They give a
summary of all business components in one screen or less. Consider an aircraft or automobile
cockpit for example. Just by glancing at it, you will know the status of your aircraft or car in an
instant. Similarly, in the world of business, you need a report that will tell you the status of your
business in an instant without going through voluminous amounts of data. This is the function
of a cockpit. In this lesson, we will learn how to create the various charts and then combine
them to create a cockpit.

Charts
A chart is a graphical representation of data and are important in easing the understanding of
large amount of data. By just looking at the chart, we can easy understand trends and
relationships in the data that would be very difficult to interpret by looking at the raw data in a
tabular format.

Knowage supports several charts like bar, pie, line, word count, Sunburst, Chord, Heatmap,
Radar, Treemap and many others. We shall begin our discussion of charts by looking at one of
the most used charts, a bar chart.

Follow these steps.

1. First, we need to create a data set where the simple bar chart will get its data. There is
already an SQL statement under Cockpit\Data Sets\ bar_no_parameter.sql that we will
use for this example.
2. Login to Knowage and create a new dataset called DS_BAR_NO_PARAM with the
content of this file and FoodMart database.

129
3. Ensure you set all other columns except column X as measures then save the data set.
4. Then create a new cockpit.

5. Under cockpit menu, select data configuration.

6. Under datasets, click on “Add dataset”. Select “DS_BAR_NO_PARAM” and Save.

7. Unser “Data Cockpit Settings”, click on Save.

130
8. Under “Cockpit menu”, click on “Add Widget”.

9. Under chart, click on add.

131
10. On the “Dataset” tab, select the dataset we added previously.

11. On the “Chart Engine Designer”, under “Chart” tab, select Bar as the style.

12. On the “Structure” tab,click on MONTH and MONTH_NUM to be the category. Click on
REVENUE, COSTS_STORE and SALES_STORE to be the Y axis.

132
13. Under “Categories”, select ordering column.

14. Select MONTH_NUM to be ordering column and type to be ascending. This way months
will be ordered from January to December.

133
15. Under configuration tab, change the chart title to “Revenue by Month”. Change the font
as desired.

134
16. On the “Style” tab, select “Show borders” with properties shown below.

135
17. Now let us add some additional colors.

136
18. And legend.

137
19. Save the cockpit as “Revenue”

138
20. Execute the document.

139
Assignment.

Using the already created documents and data set, modify your cockpit to look like the one
shown below.

140
 LESSON SIX

Key Performance Indicators

OBJECTIVES
After completing this chapter, you should be able to:

11. Understand strategy

12. Describe the importance of Performance measurement.
13. Understand Performance measures.
14. Understand Key performance indicators.

CONTENTS

 Strategy
 Performance measurement.
 Performance measures.
 Key performance indicators.
 KPI in Knowage.

141
Strategy
Businesses normally do not operate compulsively but they follow a well-defined plan to achieve
a certain business objective. This involves setting goals and providing resources needed to meet
those goals. This high level plan is called a strategy.

Performance measurement
Once you have come up with a strategy, you need a way of monitoring the progress of
executing it, otherwise, you may not meet the objectives you set out to accomplish. You do this
through Performance measurement and it involves setting up performance measures. The
performance measures are the indicators that track implementation of your strategy.
Key performance indicators
KPIs (Key Performance Indicators) are performance measures used to check performance of an
organization. Remember that the KPI must align with your goal otherwise you will be measuring
something that is not relevant to achievement of your objective. There are very many KPIs that
one can use but we will limit our discussion to only one as it cuts across all industries, profit. We
will use profit as our KPI and show you how to define this in Knowage. Note that any business
that is not tracking its profit or loss will not be open for long. It is a very important financial
metric.

KPI in Knowage.
Now that we understand what KPIs are and the importance of performance measurement, we
want to demonstrate how to perform performance measurement using Knowage. We will
assume that we want to measure the gross profit of an organization by subtracting the costs
from sales. To simplify this example, we will be using the query below which uses random
numbers in MySQl to simulate the values of store sales, store cost and measurement date.
SELECT RAND()*(20000-10000)+10000 as STORE_SALES,RAND()*(10000-0)+0 as
STORE_COST,now() as TODAY_DATE
If you run the query, you will get the result below.

We will divide the creation of KPI document into several steps as outlined below.
STEP 1 – Measures definition.
Remember from our definition of KPI that they are performance measures used to check
performance of an organization. What we want to measure for now is profit and so this will be
our performance measure. We need to define the profit measure in Knowage as the first item.
Follow the steps outlined below to do this.

142
1. Under KPI model, select “Measure/Rule Definition”.

2. Click on the “Plus” icon.

3. Under the “Query” tab, use the query below.

4. On the metadata tab, we need to tell Knowage which of the columns returned by our
query are measures or attributes. We have two measures, the store sales and store cost
and one attribute, the date.

5. We have not defined any alias or placeholder so skip these and click on Save. Give the
definition the name “Profit Measure”.

143
 6. Close
STEP 2 – KPI definition.
Once we have measure, we need to define the KPI itself. To do this, follow the steps below:
1. Under KPI model, select “KPI Definition”.

2. Click on the “Plus” icon.

3. Under the “Formula” tab, press control key together with space. Select STORE_SALES.

4. Click on the function and select sum and then apply.

144
5. Press tab to get out of the function, then put a minus sign and repeat the procedure for
store cost. From the below image, you can see that we have built the formula for gross
profit i.e summing all sales and taking away the sum of costs.

6. On the “Cardinality” tab, there is nothing to change so skip.

7. Next we need to create a threshold. Click on “add new threshold item”. We will have a
range of three. From 0 to 5000, 5001 to 8000 and 8001 to 20000. We will then color the
145
 first range red, the second orange and the last green. This means that if the profit is
below 5001, then it will show as red in the KPI tool and when profit hits 8001, it will be
in the green region as the target will have been met.

8. Save both the threshold and KPI definition.

146
STEP 3 – KPI Scheduler.
The next step is to define when the KPI will be executed by use of the KPI scheduler. Follow
these steps to do this:

1. Under KPI model, select “KPI Scheduler”

2. Click on the “Plus” icon.

3. Under “KPI” tab, click on “Add KPi associations” and select the “Profit KPI”.

4. There are no filters defined so skip this tab.

5. Under “FREQUENCY” tab, select the Start date to be today and stop executing this KPI at
the end of the year. We will be executing it every minute to allow us test.

147
 6. Save the scheduler.

STEP 4 – KPI Document.

The last step is to create the KPI document itself. Follow these steps:

1. Create a generic document with the following properties.

148
2. Click on the “Template build”

3. Under “KPI LIST”, click on “ADD KPI ASSOCIATIONS” and select “Profit KPI”

149
4. Under “View As”, select speedometer. For minimum range use 0 and maximum 20000.

5. Under options, select everything.

6. Save the template and execute document.

If you change template to use KPI card, this is what you will get if you execute document
so the choice is yours.

150
151
 LESSON SEVEN

Knowage Report Designer

OBJECTIVES
After completing this chapter, you should be able to:
1. Describe BIRT reports.
2. Configure BIRT reports.
3. Create BIRT reports.
4. Host BIRT reports on Knowage server.
CONTENTS

 BIRT Reports.
 Introduction to BIRT reports.
 Creating BIRT reports.
 Hosting BIRT reports on Knowage server.

152
BIRT
BIRT is the acronym for Business Intelligence and Reporting Tools and is an open source
initiative to create a fully functional reporting tool using open source tools. BIRT supports
various types of reports such as lists, charts, crosstabs and compound reports. In this chapter,
we will learn how to create BIRT reports and how to publish them in Knowage server. The first
report we will create is a simple list report similar to the one shown below. It has a logo, a
heading and data from the database.

NOTE: If you are not interested in following these steps, you can find the complete report file
under BIRT\Administrative Costs.rptdesign which you can deploy in your Knowage.

Let us proceed and create a new report.

1. We will need data from the database bank that came with this book. Import the
contents of the file Database\bank.sql to your MySQL server.
2. Download Software.
In this chapter, we will be using the eclipse based BIRT reporting software Knowage
Report Designer. Download the Knowage Report Designer if you have not already done

153
 so as it comes with everything we need. To download the software, go to the URL below
http://forge.ow2.org/project/showfiles.php?group_id=442&release_id=6002

3. Select the Knowage designer for your platform.

4. Ensure that your already have java installed and that the JAVA_HOME variable is set
correctly.
5. Extract the designer to a folder of your choice e.g
C:\Knowage\KnowageReportDesigner_6.1.0_win64
6. Start the Knowage Report Designer by clicking on the file KnowageReportDesigner.exe if
on windows. You will notice that this is very similar to the SpagoBI studio if you had
used it in previous versions.

7. Create a new project by going to File->New->Project..

154
8. Under Business Intelligence and Reporting Tools select Report Project.

9. Click Next.
10. Under project name use “Business Intelligence”. For the storage location, use default.
11. Your new project will now be visible on the navigator on the bottom left of the page.

12. Define a new report. Click on File -> New -> Report.

155
13. For the report name, enter “Administrative Costs”

14. For the report template, select blank report and click on finish.

156
15. Your new report should be visible on the navigator.

16. Reports can get their data from various sources such as flat files or relational databases.

157
Database connection.

Reports can get their data from various sources such as flat files or relational databases.

Prepare Database.

We will be using the table admincosts2010 to generate this report. This table and others are
included in the mysql dump bank.sql that came with this book.

We need to create a connection to the database from the Knowage Report Designer. Proceed
as shown below.

1. Click on Data -> New Data source.

2. Select JDBC Data Source, and on Data Source Name put “Mysql Local”

3. For the Data source details, enter the following. These might be different if you are
running the database on a different port or location.

158
4. Change the URL, username and password appropriately. Click on Test Connection. This
should be successful before you proceed. Click on Finish.

5. When you click on Data Explorer, your new connection should be visible under “Data
Sources”.

159
6. With the Data Explorer still opened, right click on Data Sets, and select New Data Set.

7. For the data source location select Mysql Local (The data source you just created
above).
8. For data set name, put AdminCost.
9. For the query text, use “select * from admincosts2010”. This will select all the contents
of the table admincost table.
10. Click on finish.
11. On your dataset, click on preview results, this will output the contents of the table
admincost2010.

160
12. Click on Palette and under report items, select grid and drag it to your report. The grid
allows you to organize the items in your reports like images, charts, text etc.

13. Create a grid with 2 columns and one row.

14. Drag an image icon to the first cell.

161
15. Click on embedded image then select the shemma.jpg image from the images folder
that came with this book.

16. Drag the image to make it smaller.

17. Drag the text item to the second cell.

18. For the type of text, select HTML. Write a header as shown. As you can see, you can use
html to format your text.

162
19. Next we will include the actual data on the report. To include data from the data set we
created above on the report, click on the Data Explorer tab. Expand data sets and drag
AdminCost on an empty area of your report.

20. Select the columns that you want to include in your report. In this case, we want to
include items for first quarter only (JAN, FEB, MAR).

21. Using the property editor, change the heading for id, item, january, february,march.You
will get result below.

163
 a. Before change

b. After change

22. To test the report we just created, click on Run -> View Report -> In Web Viewer.

23. And there you have it, your very first BIRT report!

164
Publishing Report.

Next we need to publish our report to the Knowage server. The first thing we need to do is
create parameters that will be used to pass database username, password, URL and class. If we
do this, then our report will be dynamic and can be used in any Knowage server even if
database name and password are different from the ones that we used to create the report.
Proceed as follows.

1. In the data explorer, right click on Report Parameters then click on New Parameter. For
the name enter driver.

2. Create other parameters url, user and pwd.

3. Right click on the data source “Mysql Local”, click on edit and select Property Binding.
Attach the parameters as shown below.

165
4. We are going to manually deploy this report to Knowage. In our second report, we will
show you how to upload automatically using Knowage Server. Right click on report and
select properties.

166
5. Note the file path.

6. Login to Knowage and create a data source to point to the Bank database that we have
used to create this report.

167
7. Create a new document with the following properties.

168
8. Under Show document templates, select the folder you want your document to be
stored.

9. Click on browse and navigate to where your “Administrative Costs.rptdesign” report file
is stored. This is the path we highlighted in step 4 above.

169
10. Save and execute the document.

11. Congratulations on creating your first BIRT report on Knowage!

170
 LESSON EIGHT

Creating a dashboard with BIRT and Knowage

OBJECTIVES
After completing this chapter, you should be able to:

1. Describe BIRT reports.

2. Configure BIRT reports.
3. Create a dash board with BIRT reports.
4. Host BIRT dash board on Knowage server.
CONTENTS

 Creating a dashboard with BIRT and Knowage

 Preparing the database.
 Creating Birt reports.
 Using grid, charts and tables in one report.

171
Creating a dashboard with BIRT and Knowage

In this chapter, we will be creating a dashboard using the BIRT reporting engine and then we
will host it in the Knowage server. The final dashboard we will be creating will be similar to the
one below.

NOTE: If you are not interested in following these steps, you can find the complete report file
under BIRT\non_performing_loans.rptdesign which you can deploy in your Knowage.

172
 Prepare Database.

The data for this chapter is in the table loan_payment. You can find this in the MySQL export
File bank.sql that came with this book. You can use the query below to look at the contents of this
table.

select * from loan_payment order by loan_year,month_no asc

Problem to be solved by dashboard.

Assume that the bank Shemma Global Limited gave out loans to individuals with the
account numbers 40187 to 40196. The loan was to be paid after duration of 48 months and was
taken on December 2010. The bank’s management would like a dashboard where they can:

1. The monthly loan arrears trends in a line chart.

2. The top 5 defaulters.
3. The total loan defaults per month.
4. Listing of all defaulters.

SOLUTION.

Before we can provide a solution for the above problem, we need to understand that the first
repayment period will be on 31st January 2011. Let us follow the payment for these individuals
for duration of one year.

January 2011 – On the month of January 2011, everybody made their loan repayment. From
the figures below, we can see that the column not_paid is zero for everyone for the
month of January. If this column have a figure, then the loan will be in arrears. You can check
this by running the statement:

“select * from loan_payment where loan_month='JAN';”

173
In the month of February, some of our clients had difficulty paying their loans as
illustrated below:

For subsequent months, we had several defaults. We need to create a dashboard using
the BIRT reporting engine and Knowage to solve the problem outlined at the beginning of this
chapter.

Follow these steps to create the BIRT dashboard outlined above.

Start your Knowage Report Designer and create a new report project. Call it Dashboard.

174
1. Click on File -> New -> Project.
2. Select Knowage Project under Business Intelligence and Reporting Tools.

3. Under “Resources”, create a connection to the Knowage server. We will use this
connection to publish the report to Knowage.

4. Enter the following data.

175
5. Ensure you test the connection and it is successful then finish.

6. Change perspective to report design.

176
7. Create a new report document as we did in the previous chapter. Click on File -> New ->
Report.
8. For the parent folder, select Dashboard and enter non_performing_loans.rptdesign as
the file name.

177
9. Now let us add a grid with four rows and two columns to our report. A grid is a
row/column layout that helps you organize items in your report. Under the pallete
tab,click on report items, click on the grid icon and drag it to your report.

10. We will insert the company logo on the first cell. Click on the image icon under pallete
and drag it to the first cell. Under “Select image from”, check the radio button next to
“Embedded Image” and click on “Add Image”. On the CD that came with this book, you
will find the folder images. Inside it you will get shemmalogo.jpg. Select this image and
click on insert.

178
11. Click on the Shift key as you drag the image to resize it proportionately. Now we will add
heading on the report. Click on the second cell on the right and drag the Text icon to it
from the Palette.

12. Click on the first cell of the second row then press down shift key and click on second
cell on second row. All the cells should be highlighted. With the cells in this state, right
click and select merge cells.

13. Click on background and change the background color of the merged cells and reduce
the size to five pixels.

179
14. Once we are done with the heading, it should look like this.

Now we will add the first item that pulls data from our table on the chart. This will be
the “total monthly loan repayments that have not been paid expressed as a line chart to
show trends for the entire year “.

15. First though we need to create a connection to the database.

a. Under Data Explorer tab, right click on Data Sources and select New Data source.
b. Under Data Source Type, select JDBC data source.
c. Under Data Source name insert “LocalMysql”

180
 d. Click Next.
e. Under Driver Class, insert “com.mysql.jdbc.Driver (v5.1)”
f. Under database URL, insert “jdbc:mysql://localhost:3306/bank”
g. Put a username and password and test your connection.

16. Next we need to create a data set. Right click on Data Sets then select New Dataset.

17. Under Data Source Connection, select the data source we created above.

181
18. For the Datasource name, enter “RepaymentTrend” and click Next.

19. Under Query Text, enter the following sql and click on Finish.

select sum(not_paid) total_monthly_unpaid,loan_month,month_no from

loan_payment group by loan_year,loan_month order by month_no asc

182
20. A dialog box should come up. Click on preview results.

183
21. We will create a chart item using this data set. Merge the cells on row three and drag
the chart icon from the pallete to the mergerd cells.
22. Select line chart and click Next.

23. Under Select Data, click on the radio button next to “Use Data From” and select
“RepaymentTrend” data set.

184
24. Click on loan_month, drag and drop it on category (X) series.
25. Click on total_monthly_unpaid, drag and drop it on value (Y) series.

26. Now if you check keenly, you will notice on the chart preview the chart is nor ordered
properly by month. To order click on “Edit Group and sorting button” next to “Category

185
 (X) series”

27. Under “Data sorting”, select Ascending.

28. Under “Sort On”, select row["month_no"] and click on OK.

29. Click on Next. Under format chart tab, click on series and remove the text “Series 1” and
type “Loan Arrears”.
30. Click on Title and replace the text “Line Chart Title” with “Monthly loan arrears”
31. Click on Finish and resize the chart accordingly.

186
32. Now click on Run -> View Report -> In Web Viewer, so that we can see how our
dashboard looks so far.

We can see from this that the month of SEP had the greatest amount of loan arrears.
Now let us add other components to our dashboard.

33. Next we will create a chart to show the top five defaulters. Us the query below.

select count(not_paid) months_defaulted, acctno from loan_payment where

not_paid>0 group by acctno order by 1 desc limit 0,5

187
34. Create a new data set using the query above and call it “Top5Defaulters”.

35. Create a new data set using the query above and call it “Top5Defaulters”.

188
 Expand the row below the one that contains the monthly loan arrears chart and insert a
bar chart on the cell labeled top 5 below.

36. Under use Data from, select Top5Defaulters. Drag the months_defaulted to Value (Y)
series and acctno to Category (X) Series a shown below. Click on Next.

189
37. On the format chart Tab under legend, uncheck the visible check box.
38. Under title, replace the text with “Top 5 Defaulters”
39. Under X-Axis, click on the icon below to invoke the font editor.

40. Change the rotation to -42 degrees.

190
41. Click on Y-Axis and select the check box under title. For the title insert the text “No of
defaults last 12 months”. For the title of the X axis, insert “Account No.”
42. Next we will add the the total loan defaults per month on our chart using the query
below.

select loan_year,loan_month,sum(not_paid) total_defaulted from loan_payment group by

loan_year,loan_month,month_no order by month_no
asc

43. Create a new data set and call it “Monthly Defaulters” using the query above.
44. Drag the data set “Monthly Defaulters “to the cell on the right of the one with the Top 5
defaulters chart. Modify it to look like the one shown below.

191
45. Create a new data set and call it “ArrearsList” using the sql below.

select loan_month "Loan Month",loan_amount "Disbursed

Amount",months_left "Months Left", not_paid "Arrears", acctno "Account No"
from loan_payment where not_paid>0 order by month_no

46. Drag the dataset “ArrearsList” just below the datagrid we used above.

47. Modify the List to look like the one below.

192
48. Our dashboard should now be complete. Click on Run -> View Report -> As PDF to
export your report to PDF.

49. Final non-performing loans dashboard.

193
50. To deploy report, change perspective back to Knowage, then right click and select
Deploy.

194
51. Select the folder, data source and deploy then execute.

195
 LESSON NINE

Report parameters

OBJECTIVES
After completing this chapter, you should be able to:

1. Create analytical drivers.

2. Create List of Values.
3. Use parameters

CONTENTS
 Introduction
 BIRT report parameters
 List of Values (LOV)
 Analytical drivers

196
Introduction

So far, we have created documents that do not have any parameter and where the data
returned to the user is not filtered in any way. In real life, this is normally not the case as
users normally require to filter the data returned by the report by various parameters
such as date, month or year. When designing reports therefore, we need to make it
flexible to suit the users query requirements. A value is generated by analytical driver
which is then send to the parameter.

Consider the report below which we created in lesson seven. The report returns all data
and does not have any parameters.

The query that is used to generate the report is “select distinct itemgroup from
admincosts2010” but we want to make a few modifications to it. What we want to do in
this chapter is to group the results returned by the report into two categories:

1. Staff Costs
2. Other Administrative Costs

We will make the report dynamic such that when a user selects “Staff Costs” as a
parameter, then the report will return only rows of items that are direct staff costs.
Secondly, we don’t want to hard code the two groups in the report. We will make it
197
dynamic such that in the future, when other categories are added by the company, then
there will be no changes that will need to be done by the report. To make this work,
there are several things that we will need to do:

1. We will need to create parameters in the BIRT report using the Knowage report
designer.
2. We will need to create a List of values to allow us select the various groups of
expenses e.g. Staff Costs.
3. We will need to create an analytical driver.

BIRT report parameter

Follow these steps to create a report parameter in BIRT.

1. Open the “Administrative Costs” report we created in chapter seven using
Knowage report designer. You can also get the report under
BIRT\Administrative Costs.rptdesign in the CD that came with this book.

2. In the “Data Explorer” tab, right click on “Report Parameters” and select “New
Parameter”.

3. Under name, use param_item_group and for data type, select string. Click on
OK.

4. Under “Data Sets”, right click on “AdminCost” and select Edit.

198
5. Change the query from “select * from admincosts2010” to “select
* from admincosts2010 where itemgroup=?”

The ? in the second query where clause is a place holder for a parameter which
we need to define and link with the param_item_group we created in step 3
above.

6. Under parameters, edit param_1.

199
7. Link it to param_item_group.

200
List of Values (LOV).

From the description we gave in the introduction, we had stated that we will want the
user to choose from a list the type of expense that he wants to view in the report. The
group of items is defined in the column itemgroup in the table admincosts2010 as
shown below.

Currently, only two groups exist but the report should be dynamic enough so that if
other groups are added, then it will display them. This means that the groups should not
be hard coded but should be read from a table. This is achieved by using a list of values
in Knowage. Follow these steps to create a list of values in Knowage:
1. Under “Behavioural model”, select “Lovs Management”.

2. Click on the plus icon to create a new LOV.

3. For the label and name, use “LOV_ITEM_GROUP” and for the description use
“LOV Item group”. Select “Query statement” for LOV type. Select your data
source and use the query “select distinct itemgroup from admincosts2010”.

201
4. Click on preview.

202
 5. Click on Test and select value, description and visible buttons then click on save.

Analytical Drivers
The last thing we need to create is an analytical driver which will enable us define the
data type our parameter will return and the roles of the users that will be allowed to use
it. Follow these steps to create an analytical driver:

1. Under “Behavioural model”, select “Analytical drivers management”.

2. Click on the plus icon to create a new analytical driver. For the label and name,
use AN_GROUP_ITEM and for the description, use “Analytical driver group
item”. For the type, select String then save.

203
3. Click on “Analytical Driver Use Mode Details” tab then select “New use mode”.
For name, label and description, use “ALL”. For input type, use “LOV” and select
the “LOV_ITEM_GROUP” we created previously. For modality, use “Select from
list”. For default value, select “None”. Under roles, select the role you want to
use this analytical driver, in my case admin. Then Save.

204
 4. Click on Save.

Now we need to modify the “Administrative Costs” document in SpagoBI to add the
analytical driver.

Under “Analytical driver”, click on the search button and select the analytical driver
AN_GROUP_ITEM we created previously and click on save.

205
For the Title, use “Item Group” and for the URL Name, we need to enter the name of the
parameter we had created in BIRT, that is param_item_group. Then ensure Required is
checked.

Lastly, under template, select the new Administrative Costs.rptdesign or deploy it from
the Knowage report designer. Now let us execute the document. The first thing you
notice is that you need to select the item group.

206
Then click on execute.

207
Now we need to modify the report so that the heading tells us which group we are
looking at. Follow these steps:

1. In Knowage report designer, delete the heading.

2. Drag the param_item_group to the report heading and change the color to gray
and size to 14.

208
3. Reload the template and run the report again selecting “Administrative Costs”.
Now the heading will be included in the report depending on what has been
selected.

209
 LESSON TEN

Cross Navigation with BIRT and Knowage

OBJECTIVES
After completing this chapter, you should be able to:
5. Explain what Cross Navigation is.
6. Explain the advantages of using Cross Navigation.
7. Create a document that has cross navigation.
CONTENTS

 Introduction to cross navigation.

 Master document
 Child document
 Output parameters
 Cross navigation definition

210
Introduction.

In this chapter we are going to see how to build a cross navigation report using BIRT. This
means that we will have a master report and we will navigate to a child report by clicking on
some data in the master report. For example, when we click on February in the Figure 1 below,
it opens a child report with data for February as shown in Figure 2.

Figure 1 – Master Document.

211
Figure 2 – Child Document
If we click any month in the report above, we get a child report with data for the month selected
as shown below.

The Master Document.

The first step in creating a cross navigation document with BIRT is to create a master
document. It is from the master document that we will navigate to the child document hence the
name cross navigation.

Problem to be solved by cross navigation.

Assume that the management of the Bank Shemma Global Limited are very impressed by the
dashboard you created in the previous chapter and they want a small modification as outlined in
the image below. What they want is that if they click on any month highlighted by the yellow
cycle, it will open a detailed report with data for that particular month only.

212
SOLUTION.
The first thing we need to do is to modify the dashboard we created previously and make it our
master document. Follow these steps.

1. Open the report and format the arrears figures to have a thousand separator and
currency symbol. Click on the value for “Total Arrears”, then under properties editor
select Format Number. Then check on 1000s separator. See highlighted below in yellow.
What this will do is that if you have an arrears figure of say 145680 dollars, it will format
it as 145,680 which is easier to read.

213
2. We will go a step further and put the currency symbol to amount. Under symbol select $,
so now our figure above will be formatted as $145,680 in Knowage report.

3. And now for the most important part. We need to create a link between the master report
and the child report. We will put this link on the month such that when someone clicks on
the month, it will open a child report with arrears for that particular month. So click on
month (Red arrow) then under properties editor window select Hyperlink (Blue arrow).

214
4. Under select hyperlink type, chose “URI”.
5. For target, select “self”.
6. For tool tip, use “Arrears for month”

215
7. Under location, select JavaScript syntax.

8. It will open the JavaScript editor where we need to write the function that will be used for
cross navigation. The function we will use is execExternalCrossNavigation.

216
If you look at the complete expression, you notice that we need to define:

a. The output parameter. In the expression, the output parameter is called

LMONTH. So what does an output parameter do? In the master document, when
you click on the month, the value for that month will be stored in the master
documents output parameter and this value will then be transferred to the child
document. The value will then be used to filter data in the child document.
Therefore, in the query below, LMONTH will hold the value of the month
selected. It is therefore our output parameter.

"javascript:parent.execExternalCrossNavigation({LMONTH:'"+row["loan_month"]+"'}
,null,'LOAN_ARREARS');"

Later, we will see how to define this variable in Knowage server.

b. In Knowage, you need to define the relationship between the master document
and the child document. You need to give this relationship a name. This
relationship is what is called cross navigation. The name of our cross navigation
is called LOAN_ARREARS. We will show later in this chapter how to define cross

217
 navigation in Knowage server.

9. Now transfer your report to Knowage and call it “Loans”.

You can see that the link has been created but when you click on any month, nothing
happens. This is because though we have created the link, we have not yet created the
cross navigation definition, the out parameter and the child report itself. Congratulations
if you have come this far. In the next section, we will create the child report.

218
Child Report.
The child report will contain the transactions for the month selected in the master report. For
example, if you click on the month of August in the master report, you get the child report
shown below which has all the arrears for that month.

Since you already know how to create a BIRT document, we will not go over all the gory details
of creating it but rather will highlight what you need to do to make your report
work.

Here are the steps:

Create a child report using BIRT as shown below. This report is also available under the BIRT
folder in the CD that came with this book. It is called all_arrears.rptdesign.

The data should come from the query below.

219
 select loan_month "Loan Month",loan_amount "Disbursed Amount",months_left "Months
Left", not_paid "Arrears", acctno "Account No" from loan_payment where not_paid>0 and
loan_month=?

Note that in the SQL, we have included a where clause loan_month=? and what
this means is that the month will come from a parameter. Remember the value that will be used
to populate this parameter will come from the parent report we created previously when
someone clicks on the month link. We have two types of parameters in BIRT, a report
parameter and a data set parameter. First, create a report parameter called pmonth as shown
below.

Give it the name pmonth.

220
Next we need to create a data set parameter which needs to be linked to the report parameter
we created above. So create a data set parameter as shown below.

Give it the name param_month and link it to the pmonth report parameter.

221
Now we need to deploy the report to the Knowage server with the name Arrears.

222
Analytical Driver.
Remember when you click on any link in the master report, it will send to the child report the
value you have clicked, i.e. the month you have selected. This value is send to the child report
as a parameter. For you to use parameters in Knowage server, you need to create what is
called an analytical driver. To create one, follow these steps.

1. Under “Behavioural model”, select “Analytical drivers management”.

2. Click on the “Plus” icon. For the label and name of the analytical document, enter
AN_MONTH. Leave the description field blank and for the type, select String. Save.

223
3. Click on “New Use Mode”.

4. For name and label, use “MANUAL_MODE”. Select “Manual Input”. Note that the
contents of a parameter apart from being input manually, can also come from a list of
values or “LOV”. In our case, we will use manual input. For default value, select none. If
you wanted the report to default to a certain month, then you can put it here. Then for
the roles that can use this analytical value, select “admin”. Save.

5. Now modify the Arrears report and select the analytical driver we just created. For the title, use
“Month” and Url name should be pmonth as it needed to match the name of the report
parameter we created in BIRT.

224
Now that we have the two reports, the master and child report, we need to define the out
parameter that will send the value of the month selected from master document to the child
document. Follow these steps:

1. Edit the Loans report and select “Manage output parameters”. See below highlighted in
yellow.

225
2. Create a parameter called LMONTH of type string.

3. Remember this is the parameter name we had put in the JavaScript code in the BIRT
document.

"javascript:parent.execExternalCrossNavigation({LMONTH:'"+row["loan_month"]+"'}
,null,'LOAN_ARREARS');"

226
Cross Navigation Definition

Now all the pieces are in place. The only thing remaining is defining the cross navigation and we
will be done. To define cross navigation, proceed as follows:

1. Under Tools, select “Cross Navigation Definition”.

2. In the Navigation name, use “LOAN_ARREARS”. Remember this is the name we had
used in the JavaScript code in the BIRT document.

"javascript:parent.execExternalCrossNavigation({LMONTH:'"+row["loan_month"]+"'}
,null,'LOAN_ARREARS');"

3. For Modality, use normal.

4. Now we need to select the master document. So under Origin Doc, select Loans.
5. Under Target Doc, select Arrears.
6. To create the relationship between the two documents, drag the output parameter to the
input parameter.

7. Once the link is created, it will be as shown below.

8. Save the navigation definition.

9. Now execute the master document and click on February.

227
10. It should open a child document with data for February.

228
ABOUT THE AUTHOR

Stephen Ogutu is an experienced IT Administrator who has a love for creativity and enjoys
experimenting with various technologies. He has vast experience in business intelligence
technologies, Oracle and Unix. He is certified in Unix, Oracle and Business Intelligence (CBIP).

You can reach him at xogutu@gmail.com

229