KNIME Report Designer

Quick Start Guide

Content
Introduction ..................................................................................................................... 1
Installation ...................................................................................................................... 2
Create a Report Workflow .............................................................................................. 2
Open the Report of a Workflow for Editing ................................................................... 4
Confirmation Dialog ................................................................................................... 5
Report Designer Perspective ...................................................................................... 6
Use Data Sets in the Report ........................................................................................ 7
Charts .............................................................................................................................. 9
Report Parameters .........................................................................................................12
FAQs.............................................................................................................................. 20

Introduction
With the KNIME Report Designer you can create reports from the data tables that are
available in a KNIME workflow. You can define a report template that is filled with
data, whenever the workflow is executed. Special nodes identify the data tables that
should be available in the report.

With the KNIME Report Designer the creation of reports consists of two clearly
separated tasks:

1) Select, transform, preprocess, filter and prepare the data you want to use in
the report. This step is carried out in a KNIME workflow.
2) Design, style and edit the presentation of this data with the report template
editor.

The KNIME workflow editor shows the workflow with all the preprocessing that is
performed on the data in a comprehensive way, while the report template editor
reveals how the data will be presented in the report.
Installation
Update your existing KNIME installation: Go to “File->"Install KNIME
Extensions…”. In the dialog that appears select in the "KNIME & Extensions"
category the “KNIME Report Designer”. Follow the instructions provided by the
wizard and restart KNIME.

Create a Report Workflow

The first time you open the KNIME Report Designer you will see the KNIME
perspective - similar to this screenshot:

Create a report by following these basic steps:

1. Create a KNIME workflow

2. Identify the data tables you want to use in the report
3. Design the report template and apply data from the automatically imported
KNIME data tables

The process beings by creating a KNIME workflow:

1) From the File menu select “New… -> New Knime Project…”, or
2) From the “Workflow Projects” view, right-click “New Knime workflow…”.
This opens the KNIME project wizard which enables you to enter the name of the
workflow, whereupon it is created and opened in the workflow editor.

Now build and configure the KNIME workflow as usual by dragging nodes from the
Node Repository onto the workflow editor. Subsequently connect, configure and
execute them.

Once you have finished creating the workflow and all tables are available in a format
that suits your intended use of them in the report, you can connect them to the “to
Report” nodes. They can be found in the Node Repository under “Reporting”:

It is highly recommended to give the reporting nodes significant names as the data
sets later on are named according to these names. Otherwise you will see some more
or less cryptic default node names.
Now that you have finished work with the workflow, it is time to create and design
your report by opening the report template.

Open the Report of a Workflow for Editing

There are two ways to switch from your workflow to the associated report.

- Either click the “Edit report” button at the top of your workflow:

- Or select the workflow in the Workflow Projects view: right-click it in order to

open the context menu and select “Edit Report”
Both of these procedures open the report associated with your workflow in the report
template editor. Switch to the reporting perspective, and import the data provided by
the “to Report” nodes within your workflow as data sets – providing that they are
available for the report.

Confirmation Dialog
None of these automatic additions, updates, and deletions are applied without your
consent, which is why a confirmation dialog opens, similar to the one shown below:

Click “Apply” to have these changes applied to the report; click “Skip” to have them
ignored for now and click “Cancel” to be returned to the workflow editor.

By default the confirmation dialog lists all changes and therefore also the addition of
data sets and the deletion of unused data sets, etc. Selecting “Only confirm critical
changes” will cause uncritical changes to be applied silently and only critical changes
have to be confirmed. Critical changes are changes that will likely mean that your
report template will have to be adapted.
Report Designer Perspective
Once you have applied the changes to the newly created report, the report template
editor opens within the report designer perspective:

The report designer perspective consists of the following elements:

- Workflow Projects View: displays the workflows currently in the current

workspace.
- Data Set View: displays the data sets (data provided by the “to Report”
nodes) within the workflow that corresponds to the opened report.
- Palette: provides tools and report items necessary to create and edit the
report template.
- Report Template Editor with 3 tabs:
o Layout: drag the data sets or report items onto the report template in
this editor tab. Use the -> Property Editor to change fonts, colors,
borders, etc.
o Master Page: this is where you can change the page size or orientation
of the template or add static images such as your company’s logo.
o Preview: click here in order to get an idea of what the resulting report
will look like.
 - Property Editor: depending on the selected report item the property
editor displays properties such as color, font, border, orientation, data
binding, to name but a few.

Use Data Sets in the Report

The simplest way to use a data set in the report is to drag it onto the report template
in the currently active editor. It appears as a placeholder for the entire table, showing
the table header, the table body and the table footer:

Select the table by clicking it. Now you can start to design the table. Select the table
header, table body, or table footer and set the referring properties in the property
editor below the template editor window.
In order to check the result of your design click the rightmost tab, “Preview”, at the
bottom of the report template. You are provided with a preview of the report to see
what it will look like once it has been rendered.

A simple table is not the only way to organize data from a KNIME workflow within a
report. There are many other options available, one of which is to use the BIRT Chart
Engine with the data from the underlying workflow. This is described in the next
section.
Charts
In order to create a chart in your report select the chart item from the palette view
and drag it onto the report template in the open report template editor:

This opens the chart wizard. On the first page select the type of chart you want to add
to the report:

In the following example we create a pie chart showing the number of customers per
country.
On the next page you can define which data you want to use for this chart from the
available dataset. Click next and then “Select Data” in the middle of the page. Now
select the “Use data from” radio button, which activates the drop-down box, in
which you can choose from the available datasets:

Once you have selected a data set you will see the available columns in the Data
Preview window. From here you can simply drag&drop them onto the referring
positions in the Chart Preview window, either as Category Definition or as Slice
Size Definition:
Different options are available depending on the type of chart that is selected. Once
you have finished selecting data and defining how it should be used by the graph,
continue to the next page in order to design and format the graph.

This is where you can define the appearance of the chart, change the title, adapt the
legend, and modify colors, outlines, etc.
By clicking “Finish” the chart is added to the report template where you can arrange it
until it fits your needs. As usual you can preview the chart by clicking on the
“Preview” tab at the bottom of the report template editor:

Report Parameters
It can be useful to add parameters to the report. For example if you want to issue a
report for a single customer, employee, product, or project but not for all customers,
employees, etc. In order to do so you have to define a workflow variable and select it
in the node you want to parameterize.

The report parameters are automatically added when you subsequently switch to the
report. During runtime (when the report is generated) the user is prompted to enter a
value for this variable. The value is inserted into the related node, in which the
variable is used. This concept is explained below in more detail:

1) When building the workflow, right-click the opened workflow in the window
“Workflow Projects” and select the context menu entry “Workflow Variables…”
2) If you cannot find this entry in the context menu, make sure you are in the
expert mode: in order to enable workflow variables for your Report Designer
edit the knime.ini file, which is located in your installation directory. Add the
following line at the end of this file:
-Dknime.expert.mode=true
A dialog opens that allows you to add, edit or remove workflow variables:

When adding a workflow variable you have to enter

o a unique name for the variable

o a type (either string, double, or integer)
o and a default value
Once the workflow variable has been added, the source nodes of the workflow
have to be reset in order to propagate the variable throughout the workflow.

Now the variable can be used in order to parameterize the nodes. Open the dialog
of the node you want to parameterize and select the “Flow Variables” tab,
where you can select the workflow variable:
This replaces the actual value of this setting with the value of the variable at
runtime (when the workflow is executed).

When you switch to the report, the workflow variable is automatically added as a
report parameter:

In order to edit this parameter,right-click it and choose “Edit”. A dialog opens in

which you can set, amongst others, the following properties of the report
parameter:

- the prompt text, displayed at runtime to the user

- the display type which can be
o a text field
o a combo box
o a list box
o or a radio button
- a help text
- whether the report parameter is required
- and a default value
When generating or previewing the report the user is subsequently prompted to enter
a value for this report parameter in a dialog similar to the one below:

If you do not want the user to enter free text but to choose from a provided set of
values, select the combo box as display type and define which values should
appear in the combo box.
You can define the selectable values statically and enter each of the values by
clicking the New… button:

However, it makes more sense to import the values once, i.e. select the Static
radio button and then click Import Values… which opens a wizard that enables
data to be selected from an existing data set:
Please note that there is a known issue related to the static import of values for report
parameters. If your report uses report parameters, in turn each data set also has data
set parameters, which makes it impossible for values to be imported. Trying to import
these values will raise an error dialog similar to this one:

The solution is to prepare the data you want to import within your workflow and to
remove the data set parameters from this data set once it has been imported. This is
accomplished by double-clicking it in the “Data Set View”, or by selecting “Edit” in
the context menu when the data set is selected in “Data Set View”. This opens the
data set edit dialog:
Remove every parameter, click OK and try to import the data again. Ignore the error
dialog: once you have selected the data set without data set parameters you will be
able to import the values. Once imported you can remove the related node in the
workflow and update the report – the values are retained.

In contrast to the dynamic option this data is imported only once at design time and
then kept in list.

Another option is to import the values dynamically, i.e. each time the report is
generated or previewed the values are retrieved from a data set.
 If a combo box is selected as the display type, a report parameter prompt dialog is
generated similar to the one below:

Once the user enters a value for the report parameter this value is inserted as a
workflow variable in the underlying workflow and the workflow is re-executed again
with this new value.
FAQs
I have a long-running workflow and want to cancel it. How do I do this?

If you preview a report that has a long-running, underlying workflow it is not enough
to cancel the generation of the report – you also have to switch to the workflow editor
and cancel execution.

I am used to BIRT/ I am an expert – how can I find the whole BIRT

functionality?

Choose “Window -> Open Perspective… -> Report Design”. This opens the BIRT
perspective you are familiar with, and from where you can add report parameters,
and data sources other than KNIME data sources, etc…

When I generate the report I encounter strange page breaks of longer

tables. Why? How can I change this behavior?

This is related to the page break properties of the table. In order to change it select
the table and switch to the “Page Break” tab of the property editor. Set the “Page
break interval” to “0” if you want that the table breaks to be set at the end of each
page.