Getting Started with BIRT in KNIME

The Basic Intelligence Reporting Tool (BIRT) is open source software used for reporting. KNIME has a built-in implementation of BIRT that allows you to create reports based on the results of your workflows. You can export your reports in PDF, Powerpoint, HTML, and many other formats. Below, we discuss the BIRT environment, and walk through the process of creating a simple report.

The BIRT Environment

The concept behind BIRT is fairly simple - in order to create a report, you need to define several elements. These are primarily arranged in two areas:

  • The Master Page, which contains information for headers, footers, and titles common to every page in the report.
  • The Layout, which details how tables, charts, images, text, and other items are arranged.

When you open BIRT for the first time, you should see an environment similar to the figure below. Note that only a single report is associated to a given workflow.

Above, you'll notice a few different panels:

  • the usual KNIME Explorer panel, which lists available workflows and groups.
  • the Data Set View panel, which lists all data sets that have been explicitly exported to BIRT from your KNIME workflow.
  • The Report Items panel, which lists available features that we can drag and drop into the report, such as text, tables, images, and so on.
  • The Report Editor panel, which is where we place, edit, and manipulate features we want to include in our report.
  • The Property Editor panel, which has a number of options for formatting and additional editing of our features. For example, you can change fonts, colors, page breaks, data references, and many other options here. The tabs available in this panel change dynamically, based on what we are currently working with in the Report Editor.

The easiest way to learn what the various panels do - and hence, what BIRT itself does - is to create a report! We'll do this momentarily. First, though, we need a dataset to work with. For our basic report, we will use a dataset of restaurant inspection scores.

Basic Report Workflow

The freely available restaurant scores dataset was obtained from data.austintexas.gov on April 16, 2018, and contains three years of information. It includes restaurant names, numeric IDs, addresses, and ZIP codes, along with associated inspection dates, scores, and descriptions.

Using this dataset, we created a workflow that reads in the data from an excel spreadsheet. The data is used to perform two tasks:

  1. identify the twenty lowest observed locations and produce a table containing their information
  2. create a scatter plot, by date, of all observed scores

The workflow is presented below. In it, you can see that the data is first read in. For the first task, the data is sorted and filtered to produce a table containing our desired data, and the table is passed to BIRT using a Data to Report node. For the second task, colors are added for inspection type, a scatter plot is produced, and the plot is passed to BIRT using an Image to Report node.

Note: By default, the Image to Report node sets the exported image size to 100x100 pixels. This is usually too small for reporting purposes. In this example, we reconfigured the node to output images of size 800x600.

The workflow and associated dataset is available at EXAMPLES/05_Reporting/01_BIRT/07_BIRT_Example_Basic . You should download the workflow from the EXAMPLES server and execute it in full before continuing with the report creation steps below.

To create a report in BIRT, we should first switch to the BIRT environment. This is done by clicking on the Report icon, shown here:

This brings up the interface shown above. Let's first click on the Master Page tab and set up our page orientation headers and footers in the Property Editor. You'll notice that by default, the footer already contains a grid with some text and images about KNIME. We'll leave that be, but go ahead and click the Orientation drop-down and change it to Landscape, like so:

Next, let's add something to spice up the header. It would be nice to have a title for each page, and maybe an image as well. If we want to have two separate items in the header, we should add a grid first. Grids help us to keep things organized in the editor. To do this, drag the Grid icon from the Report Items pane on the left side of the page into the header area at the top of the Report Editor. The header area is denoted by a dashed box colored in light blue. Once you drag over the Grid icon, you'll see an input box:

Set the grid size to 2 columns and 1 row, as shown, and click OK. The grid will appear inside the header box. Next, let's drag a Label icon from the Report Items panel into the rightmost grid cell. You can double click the Label to edit the text inside. Also, when the label has focus, you can edit the text properties in the Property Editor panel at the bottom of the screen. Let's enter the text "Austin Restaurants Report", change the font size to 24 points, and change the alignment to Center.

Let's also add an image to the header. In the leftmost grid cell, drag the Image icon from the Report Items panel. Select Embedded Image from the radio buttons shown, and add an image. I used a map of Texas highlighting the location of Austin.

If you need to resize your image, you can click-drag the corners to do so. Similarly, you can click drag the borders of the grid cells to move them as needed.

At this point, you might want to check and see how your Master Page looks outside of the editor. To see a preview, you can click on the View Report icon, which will generate the report in your web browser.The dropdown arrow next to the icon presents options for exporting to other common report formats.

Once you're happy with the arrangement of the Master Page, you can move on to editing the layout of the report.

Creating a Report Layout

Click on the Layout tab to switch to editing your layout. Let's first drag in a Grid, and set the dimensions to two rows and two columns. Add a label in the top left cell, using the text "Bottom 30 Austin Restaurant Scores ". Center the label, change the background color to blue, and the text to bold white.

Next, take a look at the items in the Data Set View panel. You should see icons for the Bottom 20 Locations table and Score plot generated from your workflow. Drag the Bottom 20 Locations icon into the bottom left grid cell. When you do, you'll be prompted to choose which fields in the dataset to include in the table. Select everything except for Row ID, and click OK.

 
Note: Always give the brown Report nodes in your workflow meaningful names! Otherwise, when you look in the Data Set View panel, you may have a hard time making out exactly what data you passed to BIRT.
 
Note that the inserted table consists of a header row, a data cell row, and an empty footer row. Center align the headers and data cells in the table by highlighting them, and clicking the associated button in the Properties panel at the bottom of the page.

Next, let's place our score plot inside the grid. Right click inside the bottom right grid cell, select Insert, then Image. A new dialogue will appear. Inside this dialog, select Dynamic image, and click the Select Image Data button.

This brings up another dialog. To choose the data that should be bound to this image, select the ScorePlot dataset, and check the box, next to Image. Click OK.

This produces a red X icon inside the cell, which can be disorienting. That's OK - the generated report is going to process the image you selected properly. At this point, the grid in the Layout editor should look something like this:

Highlighting and Mapping

Having completed the layout of our basic report, there are a few more things we can do. For example, what if we wanted to accentuate values in our table, to make them stand out more? This is called highlighting, and is done via the Highlights tab in the Property Editor. Click on the [Score] cell of your data table, and then on the Highlights tab. Click the Add... button to bring up the New Highlight dialog. In the Condition drop down, let's set Score less than or equal to 50, set the text color to bold white, and the background color to orange, as shown below. This will highlight low restaurant inspection scores in a different color scheme in our report.

What if we wanted to change the representation of values in the table to something else entirely? For example, perhaps we wanted to collapse several numeric values into bins to make them easier to interpret for the reader of our report. This is called mapping, and is done via the Map tab in the Property Editor. For our report, let's click on the [Zip Code] cell of the data table, and then on the Map tab. Click the Add... button to bring up the Edit Map Rule dialog. In the condition drop down, set the Zip Code equal to 78704 and enter a display value of Downtown, as shown below. In the report, values of 78704 will now be changed to the text string "Downtown".

Report Preview and Final Results

Now, take a look at your report in your web browser using the View Report button. You may also want to generate a PDF to see how that varies from the web preview. My report looks like this:

That's it! You've created your first report! Next up, we'll create another report that combines some advanced BIRT and KNIME features to dynamically generate tables and charts.