The Pentaho BI Suite Technical Evaluator's Guide

This document is copyright 2011 Pentaho Corporation. No part may be reprinted without written permission from Pentaho Corporation. All trademarks are the property of their respective owners.

Help and Support Resources

If you have questions that are not covered in this guide, or if you would like to report errors in the documentation, please contact your Pentaho technical support representative. Support-related questions should be submitted through the Pentaho Customer Support Portal at http://support.pentaho.com. For information about how to purchase support or enable an additional named support contact, please contact your sales representative, or send an email to sales@pentaho.com. For information about instructor-led training on the topics covered in this guide, visit http://www.pentaho.com/training.

Limits of Liability and Disclaimer of Warranty

The author(s) of this document have used their best efforts in preparing the content and the programs contained in it. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. The author and publisher make no warranty of any kind, express or implied, with regard to these programs or the documentation contained in this book. The author(s) and Pentaho shall not be liable in the event of incidental or consequential damages in connection with, or arising out of, the furnishing, performance, or use of the programs, associated instructions, and/or claims.

Trademarks
Pentaho (TM) and the Pentaho logo are registered trademarks of Pentaho Corporation. All other trademarks are the property of their respective owners. Trademarked names may appear throughout this document. Rather than list the names and entities that own the trademarks or insert a trademark symbol with each mention of the trademarked name, Pentaho states that it is using the names for editorial purposes only and to the benefit of the trademark owner, with no intention of infringing upon that trademark.

Company Information
Pentaho Corporation Citadel International, Suite 340 5950 Hazeltine National Drive Orlando, FL 32822 Phone: +1 407 812-OPEN (6736) Fax: +1 407 517-4575 http://www.pentaho.com E-mail: communityconnection@pentaho.com Sales Inquiries: sales@pentaho.com Documentation Suggestions: documentation@pentaho.com Sign-up for our newsletter: http://community.pentaho.com/newsletter/

Contents
Introduction................................................................................................................................ 4
Is This Guide For You?.................................................................................................................................4 Prerequisites.................................................................................................................................................4 Hardware Requirements.................................................................................................................... 4 Software Requirements..................................................................................................................... 5 Evaluation Overview..................................................................................................................................... 6

Installation................................................................................................................................. 7
Using the Windows Installation Utility........................................................................................................... 7 Installing on Linux......................................................................................................................................... 8 Using the Linux Installation Utility...................................................................................................... 8 Starting the Servers At Boot Time On Linux.................................................................................... 10 Verifying the Installation..............................................................................................................................11

Create, Publish, and Share Reports........................................................................................ 12

Starting Report Designer............................................................................................................................ 12 Exploring the Report Designer Interface.....................................................................................................12 Creating a Basic Report..............................................................................................................................13 Refining Your Report.................................................................................................................................. 15 Adding a Parameter....................................................................................................................................18 Publishing Your Report to the Pentaho BI Platform....................................................................................18 Ad hoc Reporting Tutorial........................................................................................................................... 20 Analyzing Data with Pentaho Analyzer.......................................................................................................21 Creating a New Analyzer Report..................................................................................................... 22 Enhancing the Pentaho Analyzer Report.........................................................................................23 Adding Filters to an Analyzer Report............................................................................................... 23 Exporting the Analyzer Report......................................................................................................... 23

Dashboards............................................................................................................................. 25
Dashboard Designer Tutorial......................................................................................................................25

Advanced Concepts and Tasks............................................................................................... 28

The Pentaho Enterprise Console................................................................................................................28 Supported Data Source Types................................................................................................................... 28 Adding a Pentaho Database Connection....................................................................................................28 Adding a JDBC Driver......................................................................................................................29 Adding a JNDI Data Connection to Tomcat................................................................................................30 Appendix: List of JDBC Class Names..............................................................................................30 Creating a SQL Query in Report Designer................................................................................................. 31 Pentaho Software Technology....................................................................................................................33

| TOC | 3

Introduction
This guide walks technical users through the process of performing a critical evaluation of the Pentaho BI Suite Enterprise Edition version 3.6.0 Pentaho offers a low-cost open source alternative to traditional proprietary business intelligence software. Proprietary BI companies like to control the evaluation process in order to mask the overwhelming technical barriers in installing and configuring their software, so they typically charge prospective clients for a "proof-of-concept" implementation, integrated with the client's data, and that is essentially the only evaluation option they offer. Pentaho does not charge for software evaluations, even for its Enterprise Edition offerings -- anyone can download the Pentaho BI Suite and use a free 30-day evaluation license key. However, no charge means there's also no consultant to do all of the work for you, or to stand over your shoulder and personally walk you through using and evaluating these rather sophisticated products. This guide is essentially a free replacement for that consultant, meant to satisfy prospective Pentaho customers who want to save money by performing an initial evaluation on their own. There are still Pentaho consultants, salespeople, and pre-sales support specialists to help you with more advanced procedures, and if you still want that proof-of-concept after you've performed your initial evaluation, a Pentaho consultant can make that happen.

Is This Guide For You?

This guide's intended audience is relatively broad, but decidedly technically inclined. You might be anyone from a chief information officer, IT manager, BI administrator, or database administrator, to someone who reports to one of those positions. One thing is certain, however: You should be comfortable with technical details and complex tutorials. If you are not an IT professional, or if you otherwise require a simpler business intelligence evaluation experience that explains many of the related concepts along the way, you may be better suited to the Getting Started With Pentaho guide.

Prerequisites
At this point, you should have already outlined your business problems and commenced a project to solve them through business intelligence software. You should expect to budget an hour to perform the initial evaluation, which includes installing the Pentaho BI Suite Enterprise Edition 3.6.0, creating a data-driven report in Report Designer using the included sample data, and working with ad hoc reporting in the Pentaho User Console. If at any time you run into a technical problem that is not covered in this guide, contact your Pentaho sales representative for pre-sales support. The Pentaho BI Suite Enterprise Edition includes an application server, sample data in an HSQLDB database, and a pre-configured MySQL database instance that will hold sample reports, schedules, and program settings. This package is not functionally different from the Enterprise Edition version that you would likely deploy to a production environment. Pentaho Enterprise Edition customers also have access to a manual deployment package that enables sysadmins to build their own Pentaho BI Server Web application for an existing production application server and database. So if your company is purely an Oracle or PostgreSQL shop, you won't be forced to use MySQL. For evaluation purposes, you will be installing the application server, database, and client tools on the same machine. In a production installation, you would ordinarily install the client tools on workstation machines, and the BI Server on a dedicated server. The unified system requirements are explained below. Note: The BI Suite supports common enterprise authentication technologies such as LDAP, Active Directory, Central Authentication Service (single sign-on), and existing JDBC user account tables in other databases. However, configuring the BI Suite to work with third-party authentication services is beyond the scope of this guide. Contact your Pentaho sales representative if you need further assistance with more sophisticated evaluation scenarios.

Hardware Requirements
The Pentaho BI Suite software does not have strict limits on computer or network hardware. As long as you meet the minimum software requirements (note that your operating system will have its own minimum hardware requirements), Pentaho is hardware agnostic. There is, however, a recommended set of minimum system specifications: Server:

4 | Pentaho BI Suite Official Documentation | Introduction

RAM Hard drive space Processor Workstation: RAM Hard drive space Processor

At least 2GB At least 2GB for the software, and more for solution and content files Dual-core AMD64 or EM64T

At least 1GB At least 1GB for the software, and more for solution and content files Dual-core AMD64 or EM64T

It's possible to use less capable machines, but in most realistic scenarios, the too-limited system resources will result in an undesirable level of performance. Your environment does not have to be 64-bit, even if your processor architecture supports it; while all modern desktop, workstation, and server machines have 64-bit processors, they often ship by default with 32-bit operating systems. If you want to run the Pentaho BI Suite in a pure 64-bit environment, you will have to install a 64-bit operating system, ensure that your solution database and Java Runtime Environment are 64-bit, and install the BI Suite via the archivebased or manual deployment methods. Note: A 32-bit JRE has a hard memory limit of 2GB (1.5GB on Windows), so if you have 2GB or more of RAM, it pays to use a 64-bit JRE on a 64-bit operating system.

Software Requirements
Note: The system requirements listed below apply to the BI Suite. The BI Suite graphical installation utility, however, will only work on Windows or Linux. In terms of operating systems, Windows (XP SP2, 2003, Vista, 7) modern Linux distributions (SUSE Linux Enterprise Desktop and Server 10 and Red Hat Enterprise Linux 5 are officially supported, but most others should work), Solaris 10, and Mac OS X 10.5 are all officially supported. No matter which operating system you use, you must have the Sun Java Runtime Environment (JRE) version 1.5 or 1.6 (sometimes referenced as version 5.0 or 6.0, respectively) installed. 1.4.2 and previous versions will not work, and Pentaho does not officially support them. Note: The GNU Compiler for Java, or GCJ for short, interferes with the way many native Java programs work on Linux, including some of the components of the Pentaho BI Suite. If you are using a Linux distribution that installs GCJ by default (which includes all of the most popular distros), then before you begin installation you must remove, disable, or circumvent GCJ. If you cannot remove it, you can simply ensure that your PENTAHO_JAVA_HOME variable is properly set (instructions for this are below), and add the Java Runtime Environment's /bin/ directory to the beginning of your PATH variable in ~/.bashrc or /etc/environment, then relog before continuing. Workstations will need to have reasonably modern Web browsers to access Pentaho's Web interface. Internet Explorer 6 or higher; Firefox 3.6 or higher (or the Mozilla or Netscape equivalent); and Safari 2.0.3 or higher will all work. Your environment can be either 32-bit or 64-bit as long as it meets the above requirements. The aforementioned configurations are officially supported by Pentaho. Other operating systems such as FreeBSD and OpenBSD; other Java virtual machines like Blackdown; other application servers such as Liferay and Websphere; and other Web browsers like Opera may work without any problems. However, the Pentaho support team will probably not be able to help you if you have trouble installing or using the BI Suite under these conditions. Note: Some Pentaho client tools, such as Metadata Editor, Aggregation Designer, Pentaho Data Integration, and Design Studio, require that the Eclipse SWT JAR be in your Java classpath. This can be an issue in scenarios where standalone client tools are installed onto a machine that does not also have the BI Server installed, particularly on platforms other than Windows and Linux. Note: The Pentaho Reporting engine requires a graphical environment in order to create charts. If you are installing the BI Server onto a headless Linux, BSD, or Solaris server and do not have X11R6 on it, you should install the Xvfb package on your server to satisfy the charting dependency.

Pentaho BI Suite Official Documentation | Introduction | 5

Evaluation Overview
Note: You do not have to follow the suggested workflow. If you're focused on creating reports with your own data, feel free to skip directly to the sections that apply to your situation. This guide walks you through installing the reporting and analysis elements of the Pentaho BI Suite version 3.6.0, which includes Report Designer, Metadata Editor, Design Studio, and the BI Platform. Only the user-facing components are covered in this evaluation, so there are no instructions for data preparation tools here. There is a separate guide for evaluating Pentaho Data Integration, however. The bulk of this evaluation should take a little over an hour, during which time you will accomplish the following goals: 1. 2. 3. 4. 5. 6. 7. Download and install the Pentaho BI Suite Enterprise Edition installer: 15 minutes. Read and follow a walkthrough for creating a basic, data-driven report with the included sample data: 10 minutes. Refine the report to include conditional text formatting, user-controllable parameters, and a chart: 10 minutes. Publish your report to the Pentaho BI Platform and share it with others: 10 minutes. Create an ad hoc report with the wizard built into the Pentaho User Console: 5 minutes. Create an Analyzer Report in the Pentaho User Console: 10 minutes. Create a dashboard using the new Dashboard Designer utility in the Pentaho User Console: 20 minutes.

Once you've seen the power of the BI Suite's content creation tools, if you are technically inclined and have more time to spend on your evaluation, you can move onto more advanced concepts and tasks: 1. 2. 3. 4. Explore the Pentaho Enterprise Console: 15 minutes. Connect to your own database: 20 minutes. Create ad hoc reports and Pentaho Analyzer reports using your own data: Variable. Learn about the underlying technologies that drive Pentaho Reporting and Analysis Enterprise edition: 10 minutes

6 | Pentaho BI Suite Official Documentation | Introduction

Installation
The graphical installation utility is easy to use, so it requires little instruction on Windows. Linux users must execute some additional steps in order to install the BI Suite properly, however. Refer to the section below that applies to your operating system.

Using the Windows Installation Utility

These instructions are for Windows users only. Linux users should refer to the Linux installation instructions instead. Note: You must disable any anti-spyware software before installing the BI Suite. Some types of software firewalls and anti-virus scanners may also block the BI Server or prevent it from operating normally. Step-by-step instructions for using the installer are below. You may need to adjust the instructions for your specific situation. 1. Run the installation utility as you would any other program - double-click it. 2. When the installation utility starts, you'll see a Pentaho splash screen. Click Next.

3. Accept the license agreement to continue. 4. When prompted for which Pentaho applications you want to install, uncheck all options except BI Server and Data Integration Server. If you have a Pentaho Dashboards Enterprise Edition or Pentaho Analysis Enterprise Edition license key, select the checkboxes for the Dashboard Designer and Pentaho Analyzer options, respectively. If you do not have the requisite support entitlements, the Dashboard Designer and Pentaho Analyzer plugins will not work, and they will change your Pentaho User Console interface permanently. There is no direct harm in installing these plugins if you do not have support entitlements for them; however, you will have to ensure that your users are properly trained to avoid the disabled functions in the Pentaho User Console. If necessary, it is possible to install Dashboard Designer and Pentaho Analyzer later by using archive packages. Pentaho BI Suite Official Documentation | Installation | 7

Note: If you install Pentaho Analyzer, you must also install Dashboard Designer due to a software dependency. 5. When asked if you would like to install the Pentaho sample data, select No if this is a production install. The sample data is useful for evaluating the BI Suite, but tends to get in the way in a production environment. 6. Next, you'll be asked to choose a directory to install to. Feel free to select a new path, but for documentation continuity and support purposes, you should leave the actual directory name alone. The default directory is ~/ pentaho/ You cannot install into a directory that already exists. 7. In the next screen, type in a root password for the MySQL database. The BI Suite installer provides a MySQL database to store your reports and analysis views. The root password is for the internal database root user, not the global system root (administrator) user. This is the account that has total control over all MySQL databases. 8. The next step asks for a publish password, which controls access to the BI Server from Pentaho client tools such as Report Designer and Schema Workbench. If you do not set a publish password, you will not be able to publish from client tools to the BI Server. 9. Next, you'll be asked to supply account details for a Pentaho administrator account. This will be both your Pentaho User Console and Pentaho Enterprise Console login information. 10.Optional: If any of the default Pentaho BI and DI Server ports (8088, 8080, 8012, 9092, 9080, 8443, 8143, and 3306) are not available on your system, the default numbers will increment by one until an available port is found. 11.A summary screen will show you an overview of which BI Suite components you've chosen to install, and the ports that all of the necessary services will run on, . Click Next to leave this screen, then Next again to commence installation. Once the installation wizard is complete, the BI Server and DI Server should be up and running with default parameters. You have the option of starting the Pentaho Enterprise Console, Pentaho User Console, and Pentaho Data Integration during the last step of the installation process. You should choose the of these options so that you can properly test and configure your BI Server installation. If you choose them, your default Web browser will open and display tabs for the console pages that you selected. Note: Two terminal windows will remain open after installation. Closing them will terminate the BI Server and DI Server processes for this session. Note: The BI Server is now installed as a service in Windows, meaning it will start and stop when Windows starts up and shuts down. The Pentaho Enterprise Console and Data Integration Server must be manually run from the Start menu, however.

Installing on Linux
Because of Linux' more modular and secure design, the installation instructions are different than for Windows. The licensing technology in the BI Server requires that you take all of the steps below to ensure that all system users have access to content and tools through the Pentaho User Console. If you used the graphical installation utility to evaluate the Pentaho BI Suite on Linux before you purchased a subscription, you did not have to establish a new user account or worry much about licensing. However, the procedure is more involved on a production server, where more than one user will be accessing the Pentaho User Console or managing BI Server licenses. Note: Pentaho strongly discourages administrators from installing to the /opt/ directory due to its complicated permissions requirements and general isolation from the rest of the system.

Using the Linux Installation Utility

These instructions are for Linux users only. Windows users should refer to the Windows installation instructions instead. Important: If you do not have an X server installed, you can run the installation utility in text mode by invoking the --mode text switch. If you like, you can also perform the installation on a Linux workstation, then transfer over the /pentaho/ and ~/.pentaho/ directories to your server after installation.

8 | Pentaho BI Suite Official Documentation | Installation

Note: The installation utility's graphical mode defaults to the GTK graphics toolkit. If you do not have the requisite GTK libraries on your system, you can run the installer with the --mode xwindow switch to use OpenMotif instead. Step-by-step instructions for using the installer are below. You may need to adjust the instructions for your specific situation. 1. Open a terminal window. 2. If it is not already there, copy the installation utility to the pentaho home directory. cp /home/rwilco/Desktop/pentaho-bi-suite-3.6-linux-installer.bin /home/pentaho/ 3. Switch to the pentaho user account. su pentaho 4. Set execute permissions on the installation utility. chmod +x ./pentaho-bi-suite-3.6-linux-installer.bin 5. Run the installation utility. /home/rwilco/Desktop/pentaho-bi-suite-3.6-linux-installer.bin 6. When the installation utility starts, you'll see a Pentaho splash screen. Click Next.

7. Accept the license agreement to continue. 8. When prompted for which Pentaho applications you want to install, uncheck all options except BI Server and Data Integration Server. If you have a Pentaho Dashboards Enterprise Edition or Pentaho Analysis Enterprise Edition license key, select the checkboxes for the Dashboard Designer and Pentaho Analyzer options, respectively. If you do not have the requisite support entitlements, the Dashboard Designer and Pentaho Analyzer plugins will not work, and they will change your Pentaho User Console interface irreversibly. There is no direct harm in installing these plugins if you do not have support entitlements for them; however, you will have to ensure that your users are properly trained to avoid the disabled functions in the Pentaho User Console. If necessary, it is possible to install Dashboard Designer and Pentaho Analyzer later by using archive packages. Note: If you install Pentaho Analyzer, you must also install Dashboard Designer due to a software dependency. 9. When asked if you would like to install the Pentaho sample data, select No if this is a production install. The sample data is useful for evaluating the BI Suite, but tends to get in the way in a production environment. 10.Next, you'll be asked to choose a directory to install to. Feel free to select a new path, but for documentation continuity and support purposes, you should leave the actual directory name alone. The default directory is ~/ pentaho/ Pentaho BI Suite Official Documentation | Installation | 9

You cannot install into a directory that already exists. 11.In the next screen, type in a root password for the MySQL database. The BI Suite installer provides a MySQL database to store your reports and analysis views. The root password is for the internal database root user, not the global system root (administrator) user. This is the account that has total control over all MySQL databases. 12.The next step asks for a publish password, which controls access to the BI Server from Pentaho client tools such as Report Designer and Schema Workbench. If you do not set a publish password, you will not be able to publish from client tools to the BI Server. 13.Next, you'll be asked to supply account details for a Pentaho administrator account. This will be both your Pentaho User Console and Pentaho Enterprise Console login information. 14.Optional: If any of the default Pentaho BI and DI Server ports (8088, 8080, 8012, 9092, 9080, 8443, 8143, and 3306) are not available on your system, the default numbers will increment by one until an available port is found. 15.A summary screen will show you an overview of which BI Suite components you've chosen to install, and the ports that all of the necessary services will run on, . Click Next to leave this screen, then Next again to commence installation. Once the installation wizard is complete, the BI Server and DI Server should be up and running with default parameters. You have the option of starting Pentaho Enterprise Console, Pentaho Data Integration, and the Pentaho User Console during the last step of the installation process. You should de-select the Data Integration option, since it is not installed with the Data Integration Server, and choose both the User Console and Enterprise Console options so that you can properly test and configure your BI Server installation. If you choose them, your default Web browser will open and display tabs for the console pages that you selected.

Starting the Servers At Boot Time On Linux

This procedure assumes that you will be running your BI Server, DI Server, and Pentaho Enterprise Console server under the pentaho local user account, as recommended by Pentaho and explained earlier in this guide. If you are using a different account to start these services, use it in place of the pentaho user account in the script below. You can start and stop the BI and DI Servers at any time by running the start-pentaho.sh and stop-pentaho.sh scripts in the /pentaho/server/biserver-ee/ and /pentaho/server/data-integration-server/ directories, respectively, or you can start and stop the entire stack -- MySQL, Tomcat, DI Server, and the Pentaho Enterprise Console -- with the provided ctlscript.sh script in the /pentaho/ directory. To start the Tomcat server automatically at boot time, and stop automatically during shutdown, follow the below procedure. 1. With root permissions, create a file in /etc/init.d/ called pentaho. 2. Using a text editor, copy the following content into the new pentaho script, changing mysql to the name of the init script for your database if it is running on the remote machine, or remove mysql entirely if you are using a remote database. Secondly, you must adjust the paths to the BI Server, DI Server, and Pentaho Enterprise Console scripts to match your situation. #!/bin/sh -e ### BEGIN INIT INFO # Provides: pentaho # Required-Start: networking # Required-Stop: # Default-Start: 2 3 4 5 # Default-Stop: 0 1 6 # Description: Pentaho BI Server ### END INIT INFO case "$1" in "start") su - pentaho su - pentaho su - pentaho pentaho.sh" su - pentaho ;; "stop") su - pentaho su - pentaho su - pentaho

-c "/home/pentaho/pentaho/mysql/scripts/ctl.sh start" -c "/home/pentaho/pentaho/server/biserver-ee/start-pentaho.sh" -c "/home/pentaho/pentaho/server/data-integration-server/start-c "cd /home/pentaho/pentaho/server/enterprise-console && ./start-pec.sh" -c "/home/pentaho/pentaho/mysql/scripts/ctl.sh stop" -c "/home/pentaho/pentaho/server/biserver-ee/stop-pentaho.sh" -c "/home/pentaho/pentaho/server/data-integration-server/stop-pentaho.sh"

10 | Pentaho BI Suite Official Documentation | Installation

su - pentaho -c "cd /home/pentaho/pentaho/server/enterprise-console && ./stop-pec.sh" ;; *) echo "Usage: $0 { start | stop }" ;; esac exit 0 3. Save the file and close the text editor. 4. Make the init script executable. chmod +x /etc/init.d/pentaho 5. Add the pentaho init script to the standard runlevels so that it will run when the system starts, and stop when the system is shut down or rebooted, by using the update-rc.d command. This command may not exist on your computer if it is not Debian-based. If that is the case, consult your distribution documentation or contact your distribution's support department to determine how to add init scripts to the default runlevels. update-rc.d pentaho defaults The Pentaho BI Server will now start at boot time, and shut down when the system stops or restarts.

Verifying the Installation

Follow the below instructions to verify that your Pentaho BI Suite installation was successful. 1. Switch to the Web browser window that the graphical installer opened upon completing the installation process. 2. Log into the Pentaho User Console with the username Joe and the password password, then click Login 3. Go to the View menu, then click Browser. The file browser pane will appear on the left edge of the window. 4. Click the + next to Steel Wheels. 5. Open at least three items in the Analysis, Reporting, and/or Dashboards folders and verify that the content displays without errors. If you've completed the above steps without any errors or difficulties, then the BI Suite is properly installed and configured for evaluation purposes. If you've encountered any errors or unexpected behavior, contact your Pentaho sales representative for assistance.

Pentaho BI Suite Official Documentation | Installation | 11

Create, Publish, and Share Reports

Now that you've got the BI Suite installed and have verified that it is working, you're ready to start creating a basic report with the sample data. Once created, you'll publish the report to the output format of your choice, and to the Pentaho BI Server, where you will be able to share the report more directly. You'll start with Pentaho's most sophisticated reporting tool, Report Designer, and then move on to creating an ad hoc report through the BI Platform. Pentaho Report Designer is a pixel-perfect report creation tool that allows you to have total control over how your data is selected, refined, formatted, and displayed in a variety of useful output formats. The Pentaho BI Platform combines elements of Pentaho Reporting and Pentaho Analysis into an easy-to-use Web interface that enables report scheduling and sharing.

Starting Report Designer

Follow the process below to start Report Designer. 1. Click the Report Designer entry in the Pentaho folder in the Programs section of your Start menu, or navigate to the /pentaho/design-tools/report-designer/ directory and run report-designer.bat on Windows, or reportdesigner.sh on Linux. 2. Before the program starts, it runs a version checking utility. You can click either option in the version checker screen to start Report Designer if you just downloaded this file, it is assuredly the most current version, so you may not need to enable this feature right now. After the version check is complete (or skipped), Report Designer will start. Report Designer displays a Welcome screen and a default workspace at startup. The Welcome screen provides you with a brief introduction to the program, some instructions for getting started, and access to sample content and recently opened reports. For this walkthrough, you won't be following the instructions on the Welcome screen, though if you would like to experiment with Report Designer a little before continuing, feel free.

Exploring the Report Designer Interface

Report Designer's interface is similar to that of other graphic design and layout tools. A typical menu and button bar are at the top of the screen; a tool palette for adding design elements is on the left; and on the right are two panes that contain data and structure elements, and show the properties of a selected report element.

The palette on the left side of the main window is where most of your design tools are located:

12 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

The Structure, Data, Style, and Attribute panes show your report elements, data sources, and their configurable options:

Creating a Basic Report

Make sure the HQLDB (Hypersonic) Sample Database is running before you start this exercise. Go to Start -> Pentaho Enterprise Edition -> Server Management -> Start Sample Database. Alternatively, if you used the Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports | 13

installer, you can start HSQLDB by navigating to .../pentaho/server/hsql-sample-database and clicking start_hypersonic.bat (or .sh). If you installed the BI Suite from a .zip or .tar.gz file, navigate to .../biserveree/data and click start_hypersonic.bat (or .sh). As an introduction to Report Designer, follow this procedure to create a simple report that shows which products are associated with cancelled orders, sorted by product line and territory. 1. From the Welcome screen, click the Evaluation Blank Report under Samples. The report appears in the Design view. The Design view enables you to create and adjust the report layout manually. The sample report file you just opened was designed specifically for this evaluation guide. It comes with a predefined data source linked to the sample data included in the evaluation package. The only element in this report is a header at the top that says "Pentaho Report Designer Walkthrough Sample Report." You can remove this header if you like. Drag and drop a Label element from the Palette onto the Page Header band. The page header appears at the absolute top of every page in the report. Double-click the label to edit it, then type in Cancelled orders for all regions. Click the font size drop-down box in the formatting toolbar, and select 24 in the list. This increases the text size to 24 point, which is more appropriate for a page title than 12 point. Click and drag the horizontal resize handles on the Label element you just created until the field is as large as the page; drag the vertical resize handles until the text fits appropriately in the space. Expanding the field out to the size of the page will allow you to center the text more easily. With the label selected, click the Center Aligns the Element icon in the formatting toolbar. The text is now perfectly centered in the page header. Click the Data tab and click Data Sets. Click and expand the JDBC (SampleData) folder. Note: Click the small icon to the left of the JDBC (SampleData) folder. Click the icon next to the small icon to the left of the default folder. The TERRITORY, STATUS, PRODUCTNAME, PRODUCTLINE, and TOTALPRICE fields are listed. 9. Click TERRITORY to select it, then click and drag it into the left side of the Details band section of the grid. The Details band will repeat itself for as many iterations of the query elements as there are. So if TERRITORY contains five rows, there will be five item elements in the report, spread across as many pages as is necessary. 10.Repeat the previous step for the PRODUCTLINE column, but drop it into the center of the Details band instead. 11.Repeat the previous step for the PRODUCTNAME column, but drop it into the right side of the Details band instead. 12.Drag the TERRITORY field to the absolute top left of the Details band. 13.Drag the PRODUCTLINE to the absolute top center of the Details band, then click the Center Aligns the Element icon in the formatting toolbar. 14.Drag the PRODUCTNAME to the absolute top right of the Details band, then click the Center Aligns the Element icon in the formatting toolbar. 15.Drag the TOTALPRICE to the absolute top right of the Details band, then click the Right Aligns the Element icon in the formatting toolbar. 16.Drag the resize handles on the TERRITORY, PRODUCTLINE, PRODUCTNAME, and TOTALPRICE fields so that they fill all of the horizontal space in the grid. Don't change their vertical size just adjust their horizontal borders and orientations so that they are at the top of the Details band with their borders abutting to one another and the sides of the report, ensuring that none of them overlap. The three fields should appear to be one solid line when you're done resizing and repositioning them. Caution: Make sure elements do not overlap; if they do, they may not appear in the output. 17.Click Preview icon (it looks like an eye) in the upper left corner of the formatting toolbar. Preview is a good way to verify the effects of any changes you make to a report. 18.Go to File -> Save and save your report

2. 3. 4. 5.

6. 7. 8.

14 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

You now have a basic report that shows information that would be quite useful to the fictional company it belongs to. If you'd like to see some of Report Designer's more advanced functionality, continue on to the next section. Otherwise, skip ahead to the next portion of this guide that appeals to you.

Refining Your Report

To complete this process, you must have created a report according to the directions in the previous section. You should have the modified evaluation_blank.report file open in Report Designer at this time. Being able to view properly refined and constrained data is useful, but Report Designer is capable of much more than just collecting and printing data; it also has many formatting options to increase the readability and visual appeal of your reports. Follow the below process to enhance your report with conditional formatting, borders, a company logo, a dynamic report date in the footer, and a pie chart. Feel free to go to the Preview tab at any time to see your progress. 1. Click the Select Objects icon ( ) in the toolbar. 2. Click in the grid and drag a selection box (from right to left), around all four fields in the Details band. 3. Go to the Format menu and select Size & Border. The Format Element dialog box appears. 4. In the Format Element dialog box, click All.

Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports | 15

5. Under Style, click solid. 6. Next to Color, select black from the list. 7. Next to Width, click the up arrow to select 1. 8. Change the Paddings property to Left - 0; Right- 0; Top - 5; Bottom- 5. 9. Click OK to exit the Format Element dialog box and apply your formatting changes. 10.Click the PRODUCTLINE field to select it. 11.Click the Structure tab and click bg-color (backbround color) under the Style tab. 12. Click the Add Expression icon ( ) next to bg-color. The Expression dialog box appears. 13.Click the ellipsis (...) to open the Formula Editor dialog box. 14.Select Logical from the Category drop-down box. 15.Double-click the IF statement in the list on the left. 16.Click the Select Field icon, (on the far right), next to the Test line.

17.In the Select Field box, choose PRODUCTLINE and click OK to return to the Formula Editor. 18.Add ="Classic Cars" to the Test line. Your condition should look like this: [PRODUCTLINE]="Classic Cars" 19.In the Then_value line type red; in the Otherwise_value line, click white.

16 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

20.Click OK to exit the Formula Editor dialog box; click Close to exit the Expression dialog box. Click Preview ( ). Notice that all cancelled orders in the Classic Cars product line will now be highlighted in red. 21.Drag and drop an Image element from the palette into the Report Header band.

22.Double-click the image element to display the Resource dialog box. Click (...) to browse for the logo.png file located in the Legacy folder under samples (.../report-designer/samples/Legacy). This graphic is a Steel Wheels Inc. logo developed by Pentaho for demonstration purposes. 23.Click Embed in Report and click OK. 24.Reposition and resize the logo until it is the width of the report. Report Designer will downsize images proportionately according to the size of the element. You may not see the image until you resize it. 25.Drag and drop a Date field element in the right corner of the Page Footer. 26.Double-click the new date field, and type and select Report date for a field name. Note: Click Preview to see the date displayed at the bottom of the report. 27.Drag and drop a Chart element from the palette to the Report Footer band. 28.Use the resizing handles to center and stretch the chart. You can also adjust the width of the band. 29.Double-click the sample chart. The Edit Chart dialog box opens. 30.The type of chart most appropriate for your report is a pie chart. In the top portion of the Edit Chart dialog box, select the pie chart icon. Note: Notice that the pie chart properties that define its look-and-feel are listed in the left pane of the Edit Chart dialog box. Properties associated with the data in the chart are listed in the right pane. 31.In the chart-title text box, type, Highest Cancelled Order Costs. 32.On the right, next to value-column, select TOTALPRICE from the list. This column determines the numerical data that the pie chart will represent. 33.Next to series-by-field, click the ellipsis (...) to open the Edit Array dialog box. 34.Click Add and double-click in the white area under Value. 35.Select PRODUCTLINE from the list and click OK to exit the Edit Array dialog box. This determines how the TOTALPRICE data will be constrained in the pie chart. 36.Click OK to save the chart settings. Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports | 17

Your report is now branded for the fictional Steel Wheels company, easier to read, and specifically highlights cancelled orders relating to the Vintage Cars product line. This is still only the beginning, but you should now have a good impression of the power and flexibility of Pentaho Report Designer.

Adding a Parameter
In addition to locally executing a report directly from Report Designer, you can also publish it to the Pentaho BI Platform where it can then be viewed using the Pentaho User Console. If you've created a parameterized report (a report that requires user input through the BI Platform Web interface in order to run), you must publish to the BI Platform in order to take advantage of its interactive elements. Follow the instructions below to add parameterization to your report, publish it to the BI Platform, and run it from the solution repository. 1. Click the Data tab and double-click on default. The JDBC Data Source dialog box appears. 2. In the JDBC Data Source dialog box, click (the Edit icon on the right). 3. Under Choose Schema, select Public, and click OK to open the Query Designer. 4. Under the PRODUCTS table, right-click on PRODUCTLINE and select add where condition. 5. In the condition edit dialog box, type ${ENTER_PRODUCTLINE} and click OK. Important: Use {curly brackets} not (parentheses) around your parameter. 6. Click OK to exit the remaining dialog boxes and to save your query.

Publishing Your Report to the Pentaho BI Platform

You have created and formatted a report; now you are ready to share the report with your users. 1. Click File -> Publish. Alternatively, click .

18 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

2. 3. 4. 5. 6.

If you haven't saved the report, a warning message reminds you to save it. The Login dialog box appears, prepopulated with credentials valid for the evaluation. Click OK. The Publish to Server dialog box appears. In the Publish to Server dialog box, type in a report name and description into the appropriate fields. Under Location, save the report in the .../steel-wheels/reports folder. Select html as the Output Type. In the Publish Password text field, type the publish password and click OK. Note: If you followed the installation instructions in the Getting Started with Pentaho Guide, the default publish password is password.

A success message appears. 7. Click Yes to go directly to the Pentaho User Console to view the report you just published. If you want to access the report later, log into the BI Server by going to http:// localhost:8080 in your Web browser, then navigate to the Reporting Examples directory in the Solution Browser. You should see your published report in the list. If not, click Tools -> Refresh Repository. 8. Log in as Joe. Joe's password is password. 9. In the Select Line field, type in any of the product lines from the sample data: Classic Cars, Motorcycles, Vintage Cars, Ships, Trains, or Planes, then click Ok. You can use your browser's back button to revisit this page and enter a different product line if you choose. You now have a dynamic report that BI Platform users can run at any time, with updated data, that concentrates on specific product lines. The conditional formatting is still set to give Classic Cars a red background, and the pie chart is configured to compare cancelled order costs among all product lines, so there is still some adjustment to do to put this report into production. However, at this point in your evaluation, you've seen most of Report Designer's key features; if you'd like to go back into Report Designer and make more changes to the cancelled orders report, feel free. This guide, however, will proceed to a walk through of the BI Platform's ad-hoc reporting capabilities.

Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports | 19

Ad hoc Reporting Tutorial

You must be logged into the Pentaho User Console before continuing. This walkthrough shows you how to create a simple, template-based report that shows which territory generates the most sales. 1. Click the Create New Report button in the middle of the Pentaho User Console screen. The ad hoc query wizard will start. 2. In the first step of the wizard, select Orders in the Select a Data Source pane. As you become more familiar with Ad Hoc Reports features, you can add your own relational or flat file (CSV) data sources to ad hoc reports. See the Getting Started with Pentaho Guide for details. 3. In the Apply a Template field, select a predefined report template that appeals to you. A thumbnail preview of the template will appear in the Template Details field. A template specifies a variety of properties in the report that affect its appearance, like font size and background colors for various report elements.

4. Click Next. 5. In the Available Items list, click the Territory business column and drag it to the upper right into the Level 1 box. This will determine how the data is grouped. 6. Drag and drop the Amount and Buy Price into the Details box on the right. This determines which fields to display for the given groups. 7. Click Go to preview how these new items have affected the report, then close the preview tab when you're done. 8. Click Next. 9. Click the Territory item in the Groups list. A list of general options will appear on the right. 10.Click Center. This will center the territory name above each table, making it easier to read. 11.Click Amount, then click Add in the Sort Detail Columns area on the right. This will sort the sales amounts from lowest to highest. 12.Click Go to test the new change, or Next to continue to the next part of the wizard. 13.To set the header, footer, description, paper type, and page orientation, change the on-screen values for these elements accordingly. PDF is the only output type that has a concept of a page, so the Page portion of the Header and Footer sections only applies to PDFs. 14.Click the blue Save button in the top toolbar to save your report. In the ensuing file dialog, navigate to the location you want to save the report to, and type in a filename for the report. You can continue to modify your report after it's been saved; just click Save to update the report file after you've made changes. You now have a report that shows how much revenue is coming from each sales territory, and the itemized price of each purchased product. As you can see, ad hoc reporting is quicker and simpler than Report Designer, but doesn't

20 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

offer nearly the same level of design detail, nor does it have advanced reporting features like conditional formatting or parameterization.

Analyzing Data with Pentaho Analyzer

Pentaho Analyzer is the front-end interface of the Pentaho Analysis product line. Using Pentaho Analyzer, you can query the data in a database without having to understand how the database is structured. Pentaho Analyzer allows you to explore your data dynamically. You can drill down into the data to discover hidden details that may help you make important business decisions. Pentaho Analyzer also presents data multi-dimensionally and lets you select what dimensions and measures you want to explore. Pentaho Analyzer is an interactive analysis tool; it provides you with a rich drag-and-drop user interface that allows you to create reports quickly based on your exploration of your data. You can also display Pentaho Analyzer reports in a dashboard.

Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports | 21

Creating a New Analyzer Report

In this exercise of the Pentaho Analyzer you will be creating a report that displays the actual versus budgeted expenses by region for each department in the fictitious Steel Wheels company (SampleData). Follow the instructions below to start creating an Analyzer report. 1. In the Pentaho User Console menubar, go to File -> New and select Analyzer Report. Pentaho Analyzer opens. 2. Select your Schema and Cube from the corresponding lists. For the purposes of this exercise, select SampleData and Quadrant Analysis, respectively. Note: The list of available schemas and cubes are provided by your administrator. A schema is the structure of the relational database and includes tables, fields, views, and more. A cube is a data structure that allows information in a database to be analyzed quickly and from multiple perspectives. 3. Click OK. A blank report appears. 4. In the list of fields (on the right), click and drag Department to the Analyzer workspace in the left pane. The Department column appears in the workspace. 5. Click and drag the Budget and Actual fields to the workspace. The columns appear in the workspace in the order in which they were placed. 6. Right-click the Budget column to display the Edit Column dialog box. Select Column Name and Format -> Currency ($) from the Format list so that your values display as dollar amounts. Repeat this step for the Actual column. Note: If you need help to understand the options in any Pentaho Analyzer dialog box, click Help. 7. Click and drag the Region column to the report. (Read the note below.) Note: Notice that the Region column appears in the workspace; however, you want this column to be the first column in the report.

8. In the workspace, click and drag the Region column to the left of the Department column. Pentaho Analyzer is designed to provide you with great flexibility when designing the visual structure of your report.

9. At this point you have a functioning report and you can view your data in chart form. Click (Switch to Chart Format) to examine your report data in a chart format. The default display is a bar chart but if you click (Choose Another Chart Type) you can select a different chart type to display your data. 10. Save your report before continuing the exercise. In the Pentaho User Console, click (Save As). When the Save As dialog box appears, save your report as Regional Expense Report under /steel wheels/analysis and click OK.

22 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

Enhancing the Pentaho Analyzer Report

You have created a working Analyzer report; however you can make the data in the report more useful if you can show the difference, in dollar amounts, between the actual and budgeted expenses. Follow the instructions below to enhance your report. 1. In the Pentaho User Console menubar, go to File -> Open. 2. Browse to /steel wheels/analysis and select Regional Expense Report. 3. Click (Switch to Table Format) if you are in chart mode when the report appears. 4. Right-click the Actual column and select User Defined Number -> Calculated Number. The New Calculated Number dialog box appears. 5. In the Name field, type Difference. This step creates a new column in the report. 6. Select Currency ($) from the Format list so that the data in your report displays as dollar amounts. 7. In the right pane of the dialog box, click so that a minus sign appears next to [Actual]-. 8. Click Budget in the left pane and click to move it to the right pane so that you create a formula that subtracts the budgeted expenses from the actual expenses, [Actual]-[Budget]. Click OK. The Difference column appears in the report. 9. Right-click the Region column and select Show Subtotals. The subtotals for each region is displayed in the report. 10.Save the report.

Adding Filters to an Analyzer Report

Filters are used to restrict or limit the data that is presented in a report. For example, a report shows sales by product line. A filter on Quarter restricts the data so that sales for the fourth quarter in 2006 only are shown. If you were to add a regional filter of Europe, the report displays data pertaining to European sales in the fourth quarter of 2006, exclusively. If you were to add a filter on the Product Line field to exclude Surfing, the report displays data pertaining to European sales in the fourth quarter of 2006 that are not in the surfing product line, exclusively. Follow the steps below to add a filter to your sample report: 1. Open the Regional Expense Report. 2. Under the report name click Show/Hide Filters next to No Filter in Use. A workspace for filters appears at the top of the report. 3. Click and drag the Region field/column into the filter workspace. The Filter on Region dialog box appears. Notice that the values, (Central, Eastern, Southern, and Western), associated with the Region field are listed in the dialog box. You can choose one of these values or you can enable Match a specific string to filter the report on a specific string of data. 4. Select Eastern from the list of values and click (Add Selected) to move it into the right pane. Eastern appears with a green checkmark next to it in the right pane. 5. Select Western from the list of values and click (Add Selected) to move it into the right pane. Western appears with a green checkmark next to it in the right pane. 6. Click OK to exit the dialog box. Your sample report displays data for the Eastern and Western regions only. 7. Click Undo or Reset to to go back to the previous version of the report.

Exporting the Analyzer Report

Pentaho Analyzer allows you to export your report as a PDF, a Microsoft Excel spreadsheet, or a CSV file. Follow the instructions below to export your report: 1. In the Pentaho Analyzer toolbar, click More and select Export Report. The export options list appears. 2. Select Export to PDF. A PDF of the report appears. Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports | 23

3. Examine your report. Notice that Pentaho Analyzer appends metadata about the report itself in the PDF. Information about the report author, the location of the source file, fields used, filter summary, are included.

24 | Pentaho BI Suite Official Documentation | Create, Publish, and Share Reports

Dashboards
Reporting may only be the first step for you in terms of information delivery. When you have data that needs to be updated frequently or in real-time and delivered to a large number of people, static reports become cumbersome and bandwidth-intensive. In these situations, you may be better served by a Web portal that shows rich and interactive charts, graphs, and stoplight reporting dashboard elements. Pentaho offers a Dashboard Designer tool to create dashboards from existing content (charts, reports, Pentaho Analyzer reports, graphics, etc.) with a variety of interesting features, including: Stoplight alerting and conditional formatting Google Maps integration Adobe Flash widget support

To see some dashboards in action, click the plus sign next to Steel Wheels in the browser pane on the left to expand it. (If you don't see a browser pane, go to the View menu in the Pentaho User Console, then select Browser. The browser pane will appear on the left). A list of example files will appear in the lower left pane; in it, double-click on the Google Maps, Revenue Analysis, and Top 10 Customers items to see different interactive dashboard examples. These are similar in appearance and functionality to actual production dashboards used by Pentaho customers.

Pentaho offers a Dashboards Enterprise Edition support module that provides two service enhancements: A Dashboard Designer plugin for the Pentaho User Console, which makes simple dashboard creation capabilities available to business users; and Pentaho dashboard development consultative support and expertise available to your JSP developers.

Dashboard Designer Tutorial

You must be logged into the Pentaho User Console. Context for the current task Note: See the Getting Started with Pentaho Guide for details about new dashboard features.

Pentaho BI Suite Official Documentation | Dashboards | 25

1. Go to the File menu, then select Dashboard from the New sub-menu. A New Dashboard page will appear with the default 2 by 2 layout selected. 2. Click back to the Templates tab. then select the two-column dashboard layout from the horizontal list. The dashboard layout will change from four panes to two. 3. Click the Theme tab to switch to the Theme pane. 4. Select the Cool Blue theme. 5. In Objects list on the left, click the Untitled 1 item. The left panel in the two-column layout will be selected. 6. In the upper right corner of the Untitled 1 panel click the Insert Content down arrow and choose File. In the browser, navigate to /steel-wheels/Dashboards/Widget Library/KPIs/Sales Year /Year (Flash) and click Select. 7. In the Title field below, type Yearly Sales Trend. 8. Click Apply. 9. Click Untitled 2 in the Objects list to switch to the right panel. 10.In the upper right corner of the Untitled 2 panel click the Insert Content down arrow and choose File. In the browser, navigate to /steel-wheels/dashboards/Widget Library/KPIs/Productline Mix - Total Sales (flash) and click Select. 11.In the Title field in the lower portion of the screen, type Product Share. 12.Click Apply. 13.Click Filters in the Objects list. The Filter Editor will appear on the right. 14.Click the Show Filter Toolbar checkbox. This toolbar enables user-interactive controls at the top of the dashboard. 15.Click the + in the upper right corner of the Filter Editor. The Filter Properties dialog box appears. 16.In the Name field, type Territory. This is display name for the filter control label. 17.Enable Display Name as Control Label if you want users to see the display name in the filter toolbar. 18.In the Filter Properties dialog, click + The List Value dialog appears. 19.Type North America into the Label field, and NA in the Value field, then click Add. 20.Add two more list values for Europe/EMEA and Asia Pacific/APAC, then click Close. 21.Click Ok in the Filter Properties dialog to finish creating the filter list. A drop-down box will appear in the filter toolbar at the top. 22.In the Objects list, click Yearly Sales Trend. 23.In the Region line, click the down-arrow and select Territory. 24.Repeat the previous step for Product Share. You now have a functional dashboard that shows bar and pie chart data filtered by sales region. To switch to a different region, select it from the Territory drop-down box in the upper left corner of the dashboard. You can now save your dashboard and share it normally through the Pentaho User Console. Feel free to experiment further with Dashboard Designer.

26 | Pentaho BI Suite Official Documentation | Dashboards

Pentaho BI Suite Official Documentation | Dashboards | 27

Advanced Concepts and Tasks

Up till this point, you've been reading specific, easy-to-follow procedures for working with reports. From an enduser's perspective Pentaho's client tools and the Pentaho User Console are all easy to use, but the technologies that Report Designer and the BI Platform depend on are more technically sophisticated. This section contains advanced instructions, information, and tips for more technically savvy evaluators.

The Pentaho Enterprise Console

Among the most visible exclusive Enterprise Edition features is the central administration and configuration interface called Pentaho Enterprise Console. You can access this application by opening a Web browser and navigating to http://localhost:8088. Note: This application will be accessible only for as long as your 30-day evaluation license is active.

Through the Pentaho Enterprise Console, you can establish data sources, user accounts, user roles, and configure and control nearly every aspect of the Pentaho BI Platform.

Supported Data Source Types

In addition to the JNDI-based Pentaho database connections that are established through the Pentaho Enterprise Console, the BI Suite can connect to the following data source types: Spreadsheets Flat files with tab- or comma-separated values Any JNDI-compliant database Mondrian MDX files

You can access these directly through the data source configuration function of Report Designer.

Adding a Pentaho Database Connection

To define a Pentaho database connection: 1. In the Pentaho Enterprise Console go to Administration > Database Connections. 28 | Pentaho BI Suite Official Documentation | Advanced Concepts and Tasks

2. Click the General icon to display basic configuration options. 3. Click the plus sign (+) (add) if you cannot find your database in the default list. The Add Database Connection dialog box appears. 4. Type a connection name that concisely describes the data source. 5. Type or select the Driver Class from the list. The database driver name you select depends on the type of database you are accessing. For example, org.hsqldb.jdbcDriver is a sample driver name for a HSQLDB database. Note: If your JDBC driver is not available, see Adding a JDBC Driver. 6. Type the User Name and Password required to access your database. 7. Type or select the URL from the list. This is the URL of your database; for example, jdbc:hsqldb:hsql://localhost/ sampledata. JDBC establishes a connection to a SQL-based database and sends and processes SQL statements. 8. Click Test. A success message appears if the connection is established. 9. Click OK to save your entries.

Adding a JDBC Driver

Before you can connect to a data source in any Pentaho server or client tool, you must first install the appropriate database driver. Your database administrator, CIO, or IT manager should be able to provide you with the proper driver JAR. If not, you can download a JDBC driver JAR file from your database vendor or driver developer's Web site. Once you have the JAR, follow the instructions below to copy it to the driver directories for all of the BI Suite components that need to connect to this data source. Note: Microsoft SQL Server users frequently use an alternative, non-vendor-supported driver called JTDS. If you are adding an MSSQL data source, ensure that you are installing the correct driver. Backing up old drivers You must also ensure that there are no other versions of the same vendor's JDBC driver installed in these directories. If there are, you may have to back them up and remove them to avoid confusion and potential class loading problems. This is of particular concern when you are installing a driver JAR for a data source that is the same database type as your Pentaho solution repository. If you have any doubts as to how to proceed, contact your Pentaho support representative for guidance. Installing JDBC drivers Copy the driver JAR file to the following directories, depending on which servers and client tools you are using (Dashboard Designer, ad hoc reporting, and Analyzer are all part of the BI Server): Note: For the DI Server: before copying a new JDBC driver, ensure that there is not a different version of the same JAR in the destination directory. If there is, you must remove the old JAR to avoid version conflicts. BI Server: /pentaho/server/biserver-ee/tomcat/lib/ Enterprise Console: /pentaho/server/enterprise-console/jdbc/ Data Integration Server: /pentaho/server/data-integration-server/tomcat/webapps/pentaho-di/ WEB-INF/lib/ Data Integration client: /pentaho/design-tools/data-integration/libext/JDBC/ Report Designer: /pentaho/design-tools/report-designer/lib/jdbc/ Schema Workbench: /pentaho/design-tools/schema-workbench/drivers/ Aggregation Designer: /pentaho/design-tools/agg-designer/drivers/ Metadata Editor: /pentaho/design-tools/metadata-editor/libext/JDBC/ Note: To establish a data source in the Pentaho Enterprise Console, you must install the driver in both the Enterprise Console and the BI Server or Data Integration Server. If you are just adding a data source through the Pentaho User Console, you do not need to install the driver to Enterprise Console. Restarting Once the driver JAR is in place, you must restart the server or client tool that you added it to. Pentaho BI Suite Official Documentation | Advanced Concepts and Tasks | 29

Connecting to a Microsoft SQL Server using Integrated or Windows Authentication The JDBC driver supports Type 2 integrated authentication on Windows operating systems through the integratedSecurity connection string property. To use integrated authentication, copy the sqljdbc_auth.dll file to all the directories to which you copied the JDBC files. The sqljdbc_auth.dll files are installed in the following location: <installation directory>\sqljdbc_<version>\<language>\auth\ Note: Use the sqljdbc_auth.dll file, in the x86 folder, if you are running a 32-bit Java Virtual Machine (JVM) even if the operating system is version x64. Use the sqljdbc_auth.dll file in the x64 folder, if you are running a 64-bit JVM on a x64 processor. Use the sqljdbc_auth.dll file in the IA64 folder, you are running a 64-bit JVM on an Itanium processor.

Adding a JNDI Data Connection to Tomcat

If you would prefer to use a JNDI connection to your database instead of the standard Pentaho method, follow the instructions below: 1. 2. 3. 4. Consult the list of JDBC class names to determine the class name and connection string for your database. Stop the Tomcat server by running the stop-pentaho script. Edit the /pentaho/server/biserver-ee/tomcat/conf/server.xml with a text editor. Anywhere inside of the <host> element, add the XML snippet shown below: <Context path="/pentaho" docbase="webapps/pentaho/"> <Resource name="jdbc/myDataSource" auth="Container" type="javax.sql.DataSource" factory="org.apache.commons.dbcp.BasicDataSourceFactory" maxActive="20" maxIdle="5" maxWait="10000" username="dbuser" password="password" driverClassName="org.postgresql.Driver" url="jdbc:postgresql://127.0.0.1:5432/myDataSource" /> </Context> The above example shows a simple PostgreSQL configuration. Replace the Resource name, username, password, driverClassName, and url parameters (or any relevant connection settings) to match your connection information. 5. Save and close the server.xml file. 6. Start the Tomcat server by running the start-pentaho script. Tomcat can now properly connect to your database.

Appendix: List of JDBC Class Names

A comprehensive list of JDBC databases and their associated class names and connection strings. Note: The table below may have forced line breaks to improve readability in some formats.

Database name IBM DB2 JDBC-ODBC Bridge Microsoft SQL Server Sybase (jConnect 5.2) Sybase (jConnect 4.2 and earlier) PostgreSQL (v7.0 and later) PostgreSQL (v6.5 and earlier) Oracle OCI 9i Oracle OCI 8i

Connection string jdbc:db2://hostname:port/ databasename jdbc:odbc:databasename jdbc:weblogic:mssqlserver4: databasename@hostname:port jdbc:sybase:Tds:hostname:port jdbc:sybase:Tds:hostname:port jdbc:postgresql://hostname:port/ databasename jdbc:postgresql://hostname:port/ databasename jdbc:oracle:oci:@SID jdbc:oracle:oci8:@SID

Class name COM.ibm.db2.jdbc.app.DB2Driver sun.jdbc.odbc.JdbcOdbcDriver weblogic.jdbc.mssqlserver4.Driver com.sybase.jdbc2.jdbc.SybDriver com.sybase.jdbc.SybDriver org.postgresql.Driver postgresql.Driver oracle.jdbc.driver.OracleDriver oracle.jdbc.driver.OracleDriver

30 | Pentaho BI Suite Official Documentation | Advanced Concepts and Tasks

Database name MySQL (MM.MySQL Driver)

Connection string jdbc:mysql://hostname:port/ databasename Microsoft SQL Server 2000 (Microsoft jdbc:microsoft:sqlserver:// Driver) hostname:port[;DatabaseName =databasename] Microsoft SQL Server (Sprinta Driver) jdbc:inetdae:hostname:port? database=databasename Microsoft SQL Server (JTurbo Driver) jdbc:JTurbo://hostname:port/ databasename HSQLDB (v1.3 and later) jdbc:hsqldb:hsql://hostname:port/ databasename HSQLDB (v1.2 and earlier) jdbc:hsqldb:hsql://hostname:port/ databasename Interbase (InterClient Driver) jdbc:interbase://hostname/ databasename InstantDB (v3.14 and later) jdbc:idb:databasename InstantDB (v3.13 and earlier) jdbc:idb:databasename Informix Dynamic Server jdbc:informix-sqli:// hostname:port/databasename: INFORMIXSERVER=servername IDS Server jdbc:ids://hostname:port/conn? dsn='ODBC_DSN_NAME' Firebird (JCA/JDBC Driver) jdbc:firebirdsql:[// hostname[:port]/]databasename Cloudscape RMI jdbc:rmi://hostname:port/ jdbc:cloudscape:databasename Cloudscape jdbc:cloudscape:databasename PointBase Embedded Server jdbc:pointbase://embedded[:port]/ databasename Oracle Thin jdbc:oracle:thin:@hostname:port:SID

Class name org.gjt.mm.mysql.Driver com.microsoft.sqlserver. jdbc.SQLServerDriver com.inet.tds.TdsDriver com.ashna.jturbo.driver.Driver org.hsqldb.jdbcDriver hSql.hDriver interbase.interclient.Driver org.enhydra.instantdb.jdbc.idbDriver jdbc.idbDriver com.informix.jdbc.IfxDriver

ids.sql.IDSDriver org.firebirdsql.jdbc.FBDriver RmiJdbc.RJDriver COM.cloudscape.core.JDBCDriver com.pointbase.jdbc.jdbcUniversalDriver oracle.jdbc.driver.OracleDriver

Creating a SQL Query in Report Designer

In Report Designer, data sources are defined through SQL or MQL queries, or through a Mondrian MDX file. If you aren't an SQL guru, you can still form a good query through Report Designer's built-in SQL Query Builder. The reporting examples in this guide have thus far involved using a mostly blank report file that contains a predefined query. This was done to enable Pentaho Reporting evaluators to dive into Report Designer quickly without having to worry about forming a query. Follow the below process to establish a connection to the sample HSQLDB database and create the same query that came with the example report. This query will constrain the data so that it only reveals data pertaining to cancelled orders, sorted by sales territory, product line, total price, and product name. 1. Close the Report Designer Welcome screen. The Welcome screen is replaced by the Design view. 2. Go to File -> New to display an untitled report. 3. Right-click on Data Sets under the Data tab on the right, then selectJDBC... in the context menu. The JDBC Data Source configuration window appears. 4. Click on SampleData (Hypersonic) under Connections to select it. 5. Under Available Queries, click (Add). 6. You must now enter an SQL query to pull in information to use in the report, but since you aren't familiar with the sample data structure, you'll need some assistance. Click (the Edit icon on the far right). The Choose Schema dialog box appears. 7. Select Public and click OK. The SQL Query Designer appears. 8. Double-click the CUSTOMER_W_TER table in the lower left pane. Pentaho BI Suite Official Documentation | Advanced Concepts and Tasks | 31

All of the columns in that table will appear in a list in the right pane. 9. Double-click the ORDERFACT table. 10.Double-click the PRODUCTS table. 11.Right-click each table's name, then click deselect all from the context menu. By default, all columns in a table are selected. If you just want to select a few of them, it's easier to deselect all and then select only the relevant columns than it is to deselect unwanted columns by clicking checkboxes. 12.Create a SQL JOIN by clicking on the CUSTOMERNUMBER column in the CUSTOMER_W_TER field, then clicking and dragging it to the CUSTOMERNUMBER column in the ORDERFACT sub-window. A grey line with a red square in the middle will appear between the two sub-windows. If there is not already a JOIN between the ORDERFACT and PRODUCTS tables, create one now.

13.In the CUSTOMER_W_TER table, click the checkbox next to the TERRITORY column. 14.In the PRODUCTS table, click the checkboxes next to the PRODUCTLINE and PRODUCTNAME columns. 15.In the ORDERFACT table, click the checkboxes next to the STATUS and TOTALPRICE columns. 16.Right-click on the STATUS column in the ORDERFACT table, then select add where condition... in the context menu. A conditional statement window appears. 17.Type 'Cancelled' into the lower text field, then click ok. This will constrain the data in the STATUS column so that only the cancelled orders are displayed. 18.In the upper left pane, right-click on CUSTOMER_W_TER"."TERRITORY", then select add to order-by in the context menu. This will sort the results by territory. 19.Repeat the previous step for PRODUCTLINE, then PRODUCTNAME. This will sort the results by territory first (because it is first in the order-by list), and then by the product line, and then by product name within each product line. 20.Click Preview to make sure that the lists are sorted and grouped correctly. 21.When you're done looking at the basic query results, close the preview window, then click OK to save your query and exit the SQL Query Builder. 22.Click OK to exit the Configure window. You should now be back in the Design view of Report Designer. You are now ready to create a report using the data you just specified in the query.

32 | Pentaho BI Suite Official Documentation | Advanced Concepts and Tasks

Your query should look like this: SELECT "CUSTOMER_W_TER"."CUSTOMERNUMBER", "CUSTOMER_W_TER"."TERRITORY", "PRODUCTS"."PRODUCTLINE", "PRODUCTS"."PRODUCTNAME", "ORDERFACT"."STATUS", "ORDERFACT"."TOTALPRICE" FROM "PRODUCTS" INNER JOIN "ORDERFACT" ON "PRODUCTS"."PRODUCTCODE" = "ORDERFACT"."PRODUCTCODE" INNER JOIN "CUSTOMER_W_TER" ON "ORDERFACT"."CUSTOMERNUMBER" = "CUSTOMER_W_TER"."CUSTOMERNUMBER" WHERE "ORDERFACT"."STATUS" = 'Cancelled' ORDER BY "CUSTOMER_W_TER"."TERRITORY" ASC, "PRODUCTS"."PRODUCTLINE" ASC, "PRODUCTS"."PRODUCTNAME" ASC Note: The MQL Query Builder tool works almost identically to SQL Query Designer.

Pentaho Software Technology

Pentaho = options Commercial open source companies like Pentaho offer unique opportunities to customers who have atypical business intelligence needs. If you want to do something unusual with a proprietary BI product, you can't -- you're limited by a static design. Pentaho, however, provides access to the source code for its core components, including full API documentation. So if there is something unusual that you need to do with the Pentaho BI Suite (like completely rearranging the user interface, or adding new features, or building your own software with Pentaho's Reporting or Analysis engines), you are limited only by your own budget for in-house software development. If your programmers need help or advice, a Pentaho Enterprise Edition subscription includes developer assistance from Pentaho's engineering department. The Pentaho Reporting engine Report Designer is one possible implementation of the Pentaho Reporting engine, formerly known as JFreeReport. The engine can be integrated into existing Java applications, or you can build your own Report Designer-like user interface for it, or you can use it as sort of a reporting appliance that you send jobs to from other services. If you're looking for an embeddable reporting solution, the Pentaho Reporting engine is an excellent option because of its source code availability, its history of successful embedding projects, and Pentaho Reporting Enterprise Edition's developer assistance options. As an Enterprise Edition customer, your application developers can get assistance from the Pentaho engineers who created and maintain the Reporting engine code, and get a fast track for bug fixes. Preparing data for Report Designer In order for Report Designer to interface properly with your database, you must prepare the data so that it is easier to work with. The Pentaho Metadata Editor is designed specifically to prepare data for Report Designer and ad hoc reporting in the BI Platform by creating user-friendly names for tables and columns. If you extend your evaluation to include connecting to your own database, you should start with Metadata Editor, which is included in the Pentaho Reporting evaluation package. Hand-editing reports with Design Studio Reports published to the Pentaho BI Platform can also be accessed through other methods not covered in this guide. Design Studio enables XML experts to hand-edit an xaction to add complex parameterization and other highly advanced report functions that are not currently available through Report Designer.

Pentaho BI Suite Official Documentation | Advanced Concepts and Tasks | 33