Customize The Pentaho 5.x Look

To present a Pentaho BI demo to your company or client, you should upload relevant business data, develop reports, maybe OLAP models and MDX queries, even Dashboards. To take it to the next step, you can modify files to show their logo and text above Pentaho’s marketing messages.

What follows is a list of ‘quick and dirty’ tips to make that customization. It’s not the preferred way a programmer o designer go about it, but it works, so:

Login Screen Images

You will need two images:

  • Logo, 360×93 pixels in size. Transparency recommended. Replace at
  • Background, 1255×663 pixels in size. Edit it and add brightness to emulate original effect. Replace at

I have tested it with the Crystal (default) and Emerald (available on 5.2) theme.

Login Screen Text

To modify the text in the screen you can edit a file. I chose to replace the variables by fixed words. The file is:


To change user, password, login button text, copyright, first copy and paste each one of those lines, comment the original and type your text on the new ones, like this:

<!-- ...getString("UI.PUC.LOGIN.COPYRIGHT", ... -->

 Main Page

What I changed in the main page is the center panel text, leaving intact the navigation bar on the left and upper toolbars and menues. So I edited:


Its a regular html file, just check the divs as they are rendered as tabs or categories in case you want to keep them.

For CSS modifications, add rules to one of these:


I installed the new (in 5.2) Emerald Theme and added at the bottom of main.css:

/* Header fonts */
h1.large  { font-size: 2.5em; color: #3BA749; }
.header-navigation-item { font-size: 1.2em; color: #3BA749; }
.content h2 { color: #3BA749; }
/* To avoid Multilist height bug, and jpivot message, I edited  globalEmerald.css */
.parameter-container SELECT { height:auto; }
#deprecatedWarning { display:none; }

For other pages, themes have preference so in bootstrap-namespaced.css I added also at the bottom:

 /* Content width */
.bootstrap .row-fluid .span9  { width:71%; }
.bootstrap .container-fluid { padding-left: 10px; padding-right: 10px; }
 /* Main left sidebar headers */
.bootstrap .well h3 { color: #3BA749; }
/* Browse Files column width */
#fileBrowserFolders { width:28%;  }
#fileBrowserFiles { width:45%; margin-left:0px; }
#fileBrowserButtons { width:22%; margin-left:0px; }
.fileBrowserColumn .header { color: #3BA749; }

To make Tomcat to reload the .css, I had to delete the content of


Then restart the server and clean the browser cache at login screen.

Translation (i18n)

If you like to change words, you need to modify some text files, modify the text to the right of the equal sign and save them with UTF-8 encoding:

  • In 5.0 and 5.1:
    Main app mesages are located at:
  • In 5.0
    To edit the navigation text on the upper left selector, edit:
  • In 5.1:
    – One file contains login, navigation content and tools header text. It’s located at
    – Navigation text and right content of options like browse files are in:
  • Notes:
    – Use unicode, ie, \u00E1 instead of á, or otherwise your system may fail after login.
    – Copy each message file to a new one and add your locale, i.e, for spanish copy to and then edit you translation. You also need to add the line es=Español to the file on the same folder.

Restart your server, clear your browser cache and test it.


Other images were modified in older versions and havent verified if they are used today but they are listed if needed:

  • Logo. 185x50px. pentaho-solutions\system\common-ui\resources\themes\images\logo.png
  • Logo. 52x60px. tomcat\webapps\pentaho\mantle\themes\onyx\images\logo.png
  • Login. 224x94px. tomcat\webapps\pentaho-style\images\login\logo.png

About other text messages files:

  • There is a similar copy of the first file mentioned above but has no effect:
  • There are older translation files that are no longer needed. But they are listed:

Thanks to:

An evaluation post of 5.0 by nextCoder that suggested the login page straight modification in

There is a guide in your Pentaho installation, look into \biserver-ce\tomcat\webapps\pentaho\docs\customizing_pentaho_guide.pdf. I found it updated after making this notes, is consise and complete.

Pentaho CE 4.8 – BI Server Update

[This is the third edit -15th January 2013-on this post I think this is the final version so everything works]

On November 29, Pentaho (dmoran specifically) published on sourceforge the new versión of the Pentaho BI Server 4.8. That is just a few days behind the Enterprise Edition announcement, that is great news for us.

Also was made available the Data Integration, Pentaho Metadata, Report Designer applications that you should be able to update following the Tools Update post.

The most notorious inprovement in the PUC is a toolbar button to install, upgrade or delete the Saiku or C*Tools plug-ins, its called ‘The Pentaho Marketplace’. If you click on it you will see this dialog:


If you’re server is connected to the internet you just need to click on the buttons to upgrade or install plugins!, This is the success dialog:


The following instructions should work from upgrading the 3.5-3.10 server if you installed acording to this series, that’s the installation and MySql-DB post. If you made further modifications or want to do the things the ‘best practice way’ then you should do a ‘diff’ for the configuration files, at least the ones mentioned.

If you need details about the instructions refer to each post where it is explained in detail.

Part I: BI Server Demo Install

Just like in the first post:

  1. Download biserver-ce-4.8.0-stable.tar.gz [445.6.5 MB]
  2. Stop your server.
  3. Make a bakup of your /Pentaho/biserver-ce folder, a zip or gzip file should do it.
  4. Rename the folder to /Pentaho/biserver-ce-old.
  5. Move the dowloaded file into \Pentaho
    untar/gzip the two folders:  tar -zxvf biserver-ce-4.8.0-stable.tar.gz
  6. Change the .sh to exetutables [I didn’t have to do this but in case you need it]
    Antonio suggested (on first post comments) to use:
    find Pentaho/ -type f -name ‘*.sh’ -exec chmod +x {} \;
  7. Add the java variable to the start and stop .sh files, including the ones in the administration console folders:
    export JAVA_HOME=”/usr/lib/jvm/java-6-openjdk”
    [or java-7-openjdk]
  8. Start the Server and login with joe/password to check the demo at:
    Be patient it may take a few minutes

Part II: Update Plugins

[Edit: JP -in the comments- posted that this step avoids an error on dropdown parameters that happens on some systems. As it works, I suggest you follow his advice.]

If your server is without internet access, follow the C*Tools and Saiku manual install instrucctions.

  1. Click on the marketplace icon on the toolbar.
    Locate the Comunity Dashboard Framework line and click on the view details button. Click on uninstall. Close the dialog.
  2. Restart you server.
  3. Reload the settings on the browser using the menu ->Tools -> Refresh and execute all the options. Clear your browser’s cache.
  4. Click again on view details button from the CDF option, but this time Install the ‘stable’ version not the TRUNK).
  5. Go ahead click on upgrade Saiku Analytics, CDA, CDE.
  6. You need to install the Saiku Reporting add-in manually (as described on Post 3): download it and unpack it into Pentaho/biserver-ce/pentaho-solutions/system.
  7. Reboot the server.
    I hope that in the next version of the marketplace they use use checkboxes and let the thing reiterate so you don’t have to click and waif for each one.
  8. You can check that after the procedure, the plugin-samples->CDF->CDF-> Samples->Charts samples->Chart Samples: works!

Part III: Upgrade your DB and Connections

Lets update the database config files (the same ones that we modified on post 2). Open a file explorer with the biserver-ce-old and the biserver-ce, as we will be copying files from the first one to the second, here is the list.Be carefull not to overwrite the wrong ones.

  1. Shut down the server.
  2. Copy the Hibernate and Quartz DB config files:
  3. Copy the Hibernate security files:
  4. Copy the Datasources:
  5. Copy your drivers (files not in the new lib folder) from:
    In my case: mysql-connector-java-5.1.17.jar, ojdbc14.jar, orai18n.jar
  6. Disable the In Memory database from the demo, edit:
    search for: BEGIN HSQLDB in two places, and remove some coment so it will look like this:
    <context-param> <param-name>hsqldb-databases</param-name> <param-value>sampledata@../../data/hsqldb/sampledata,hibernate@../../data/hsqldb/hibernate,quartz@../../data/hsqldb/quartz</param-value> </context-param>
    and :
    <listener> <listener-class>org.pentaho.platform.web.http.context.HsqldbStartupListener</listener-class> </listener>
  7. If you jave generated metadata using tools or dowloading samples you shoud check
    and copy your ‘agile’ file to your new folder.

The following modifications may vary and are optional, they were mentioned in Post 5 – Your Server:

  1. Copy company logo, repace these files from your biserver-ce-old folder:
  2. Avoid tip on ‘demo users’ at login screen, edit:
    Set these properties to false:
  3. Increase Timeout, edit two files:
    Search for session-timeout and change it from 30 to the seconds you prefer:
    While you are editing you can add these at the bottom, just after:
    <!– insert additional resource-refs –>
       <description>security role</description>
    Its removes a warning on logs at startup, but there a re too many now.
  4. Add your publishing password. Edit:
    Set the property to your password
  5. Remove Jpivot and waqr warnings.
    Those tool are deprecated, you should be using the Saiku tools, but If you have reports running on those tool, its not nice for your clients, so get to:
    add at the bottom of these files: jpivot.css and jpivotIE6.css :
    #deprecatedWarning { display: none; }
    And add to (in the same folder): adhoc.css :
    #waqrDeprecatedAlert { display: none; }
  6. On a production system, I hide the .CDA files, its no use to the end user to see the datasource in the treeview so edit:
    And comment the lines between:

  7. If you need advanced guidelines on changing http server name and port, connection pools, config for database on other machine, modify the messages, email account setup, and automatic startup, pool connection, etc. Check Post 5 for config notes.

Part IV: Copy your Solution Folders

  1. Check for your work (solutions) in the old
    and copy them to your new folder. I have two solutions and a samples from old bi server installations.
  2. If you have kept your .xmi and other configuration files to each solution folder you can upgrade this easily.

That’s it, start your server, you’re on 4.8 now. Now you’ll need to use your own user-password.

PD. Remember to reload the settings on the browser with the menu ->Tools -> Refresh and execute all the options, and clean your browser cache.

Complete Pentaho Installation on Ubuntu, Part 5

Prepare your ‘Production’ Server

There are a few things we can do to our working server:

Usefull Changes

  1. Add your own logo
  2. Remove user selection login option
  3. Modify login screen text
  4. Increase connection timeout
  5. Increase memory limit for apache
  6. Set up a publishing password
  7. Change your passwords
  8. Remove warning messages.

Optional Activities

  1. Rename your Server and port if necesary
  2. Use a connection pool to avoid disconnection
  3. Move the database to other machine (not standard)
  4. Customize the BI server messages (rarely needed)
  5. Email account setup
  6. Automatic startup
  7. Additional notes

Not all of them are needed in your installation, choose which one you’ll use and which ones will be common in your developer and production server. Work up to that point and make a file system [folders] copy to deploy in your server machine. Continue the configuration on that server.

I come from a developer background where an additional quality server would be set up to test work in progress and deployment packages before releasing them into production but in BI I think that’s too much, the two environments are enough to avoid shooting yourself on the foot either by over-confidence, late hour distractions or human error.

In any case the backup policy of the servers should be independent. One for continuing operation depending on how fast a machine can be set up with the last data snapshot used. The other one is an incremental backup so you’ll won’t loose more than one or few day’s work.

To do the backup you shut down the DB and BI servers and copy the folders, just remember to set up the replacement machines with the same names. Or do a SQL backup with MySql Administrator or ‘Percona XtraBackup’ that can do a hot -operational- DB backup for your InnoDB tables (ISAM tables use a table locks). For the BI folder, copying the files are enough.

1. Add your own logo

To change the top-right image of ‘Pentaho’ overwrite the logo.png image in:

3.8 [152×60 pixels]: /Pentaho/biserver-ce/tomcat/webapps/pentaho/mantle/

3.9 [152×75 pixels]: /Pentaho/biserver-ce/tomcat/webapps/pentaho/mantle/themes/onyx/images and …/themes/slate/images

By the way, the login screen logo [224×94 pixels] in 3.9 is at:


2. Remove user selection login option

If you have tested your users and your admin user and password (for authorization you’ll need Admin, Authenticated and ceo roles) you can hide the user selector from the login dialog. Edit the following XML file:


and change the content from true to false:

3.8: <login-show-users-list>false</login-show-users-list> 
3.9 and 3.10: <login-show-sample-users-hint>false</login-show-sample-users-hint> 

3. Modify login screen text

Pentaho uses the first screen to present their product to new users. You might want to replace them with your project objectives, links for specific user manuals, tips, instructional videos*, news or local resources.

Specifically -I think- you’ll want to modify the scary text “Supplied free of charge with no support… no maintenance, no warranty” into something more conforting like “Pentaho Open Source Enterprise Quality Software supported by [use your contact data]”.

You can use the ‘Komposer’ editor to easily modify the text in:


* For screencast videos I recomend wink (windows freeware) it produces flash files. Or if you are adventurous, use services with text-to-speach characters like or, short videos are great for instructional guides.

This has been fixed, this is no longer needed

[Edit: In 3.9 4.0 this file should be edited to remove the demo users to apear if you click on the Evaluation Login link. Search for joe, and remove the following text (strikedthrough) and replace de text striked and bold like this:
<tr>    <td style=”font-size: .8em;”>  <strong>Administrator</strong><br>     User Name: joe<br>  Password: password</td>     <td style=”font-size: .8em;”>  <strong>Business User</strong><br>     User Name: suzy<br> Password: password</td>
</tr>  <tr>    <td colspan=”3″ style=”padding: 4px 20px 0 0; font-size: .8em;”>    <a href=”; target=”_blank”>Request free evaluation support.</a>    <img src=”/pentaho-style/images/login/help_link.png” width=”20″ height=”20″ align=”absbottom”>    </td>    <td style=”font-size: .8em;”>Contact [your data] for user accounts and support </td> </tr>

4. Increase connection timeout

The default browser session connection time out is 30 minutes, you can change that modifying the file:


The unit is in minutes so for 3 hours set it to:


and also with the same xml tag in:


5. Increase memory limit for apache

This activity was a must in previous versions, but now the parameters are ok. Anyway if you want to play with the variable -I havent found benchmarks on it- you can edit:


set memory minimum (Xms) and maximum (Xmx) in tomcat, for example: -Xms516m -Xmx1024m

CATALINA_OPTS="-Xms256m -Xmx768m -XX:MaxPermSize=256m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"

6. Set up a publishing password

On future articles we’ll be saving queries, metada or OLAP models into the production web server. But you need to set the ‘publishing password’. In the file:


type a password:


7. Change your passwords

There are several steps for this to work:

  • Set up a new user as administrator.
    – Start PAC (administrator console).
    – Add Admin and ceo roles to your selected user.
  • Stop PAC and the BI server.
  • Change the database passwords.
    – Enter theMySql  administrator
    – Change the passwords for: pentaho_admin, pentaho_user and hibuser.
  • Re-edit the following files with the new passwords:
    – hibuser password in:
    -All user’s passwords in:

    – hibuser password in:
    and (tanks to Raul Chavarría and mahamood notes):
    – hibuser and pentaho_user passwords in this identical files:
  • Edit the URL tag and change joe and password to your new user and password in
    <URL>…userid=joe&amp;password=password</URL> in the file:
  • There are some examples (.xaction files)… but check them as you click on them and they report errors.
  • Reset the server and test.
  • In the PAC delete the demo users: joe, pat, suzy, tiffany

8. Remove warning messages

In 3.9.stable and up the OLAP results of jpivot shows a warning about being deprecated in favor of the new PAT OLAP browser:

JPivot has been replaced by Pentaho Analyzer.
It is provided as a convenience but will no longer be enhanced or offically supported by Pentaho.

and I think it will not be appreciated by your users. As it is really not true that PAT has all jpivot needed functionallity, not yet you can eliminate it with a CSS tag in:


there are two files: jpivot.css y jpivotIE6.css.You need to add this at the bottom:

#deprecatedWarning { display: none; }

In the query tool WAQR, there is also a message to remove

Message Remove

In the file adhoc.css  at the bottom add:

#waqrDeprecatedAlert { display: none; }

9. Rename your Server (and Port if necesary)

Your ‘localhost’ url must be changed so it can be reached from any computer in your network. Use your machine name as its already mapped on the network.

The default port is 8080 that’s a port for web development so it is probably used on a server, check with your system administrator for a free port or take the next one available like the enterprise edition does. If its a new machine you can leave it as it is.

The same files and lines are used to change the server name and port. The most important one is the tomcat (or web application server) services definition file:


search for ‘localhost’ and modify [your server]:[your port] like BISERVER1:8086


now that we are in this file we’ll add the IP address from the machines will be connecting from the administration console, use a comma separated list:


save it and edit:


First change the port (On 3.9 4.0):

<Connector URIEncoding=”UTF-8″ port=”8086” protocol=”HTTP/1.1″  
           redirectPort=”8443″ />

then the server:

<Engine name=”Catalina” defaultHost=”BISERVER1“>

<Host name=”BISERVER1”  appBase=”webapps”
unpackWARs=”true” autoDeploy=”true”
xmlValidation=”false” xmlNamespaceAware=”false”>

Some other files may need to be edited depending if you’re puting services in diferent machines but if they remain in your server localhost will be ok, for example, the OLAP services will work with localhost in:


but if you changed the port you’ll need to change it to [your-server]:[your-port] like:


[Edit with the Saiku update this is no longer necesary]
If you installed saiku then edit also:


There are other files to modify if you change the localhost-port but depend on each service. Like the metadata.mxi from the schema editor, it will be mentiones on its own post.

10. Use a connection pool

For running an uninterrupted service or inclusive for more than 8 hours you might want to use a connection pool manager that adds more advantages than just maintaining an open connection to MySQL at all times.

In the Pentaho forum they recommended c3p0 as a connection pool. So download the file


and put it into library folders:


And add this lines:

<!– connection pool–>
<property name=”connection.provider_class”>org.hibernate.connection.C3P0ConnectionProvider</property>
<property name=”hibernate.cp3p0.acquire_increment”>3</property>
<property name=”hibernate.cp3p0.idle_test_period”>10</property>
<property name=”hibernate.cp3p0.min_size”>5</property>
<property name=”hibernate.cp3p0.max_size”>75</property>
<property name=”hibernate.cp3p0.max_statements”>0</property>
<property name=”hibernate.cp3p0.timeout”>25200</property>
<property name=”hibernate.cp3p0.preferredTestQuery”>Select 1</property>
<property name=”hibernate.cp3p0.testConnectionOnCheckout”>true</property>
<property name=”hibernate.c3p0.acquireRetryAttempts”>30</property>
<property name=”hibernate.c3p0.acquireIncrement”>5</property>
<property name=”hibernate.c3p0.idleConnectionTestPeriod”>300</property>

to your hibernate connection file in:


just at the top, after the tag <session-factory>. Restart your server.

11. If you’ll move the database to other machine

Update your server and ports, users and password on:


Change your strings [new-server]:[new-port]

12. If you’ll need to customize the BI server messages

Some messages in the BI server (console app) can be easily changed in case you’ll need more personalized texts. There is an excelent blog article from Prashant Raju.

The tooltip description of every program can be set with the .properties file:


Even if you’ll want to edit every message you can do it in:


Remember that every language has its sufix, for example the spanish files are ‘_es’ like And if you’re using special caracters you better make sure youre saving in UTF-8 coding (editor scren when you save).

13. Email account setup

The BI server can use a mail server if you have one set up already but in case you don’t get authorization to connect to it you can always send mail from the automated processes (ETL) using your mail acount. This is how I did it and we’ll review it with PDI.

The setup for the server is easy, if you know some parameters from your email server. Edit


Put your data in:


We’ll test it with the pentaho designer,

14. Automatic startup

The correct way to do this is adding a user and group with a perfect defined user account, make scripts and placing them on the correct folders.

The fast track is based on the pentaho wiki like:

  • Edit a file in a terminal/command window, type:
    sudo gedit /etc/init.d/pentaho
  • Add this text (Important: Don’t forget to use YOUR user folder):
    case “$1” in
    /home/[your-user]/Pentaho/biserver-ce/ > /tmp/pentaho.out
    exit 0
  • Save and exit. Then make the file executable:
    sudo chmod +x /etc/init.d/pentaho
  • update the boot scripts
    sudo update-rc.d pentaho defaults

You can restart your server.

Note: How to set up a tomcat pentaho windows service:

  1. Open a terminal window as administrator.
    Click on start on exec, type cmd, right click on list, select run as admin
  2. Change folder to your pentaho-tomcat excecutables:
  3. Register the service:
    tomcat6.exe //IS//Tomcat6 –DisplayName=”PentahoBIServer”
  4. Start the configuration application:
    tomcat6w //ES//PentahoBIServer
  5. On ‘Log On’ tab, select the windows user you used for the instalation or use another one that has ownership of the folder as some temporal files requires it.
  6. On ‘java’ tab tipe:
    1. Virtual machine:
      C:\Program Files\Java\jdk1.6.0_25\jre\bin\server\jvm.dll
      C:\Pentaho\biserver-ce\tomcat\bin\bootstrap.jar CD:\Pentaho\biserver-ce\tomcat\bin\tomcat-juli.jar
    2. On ‘java options’
      a. type (use your path):
      -Dcatalina.base=C:\Pentaho\biserver-ce\tomcat      -Dcatalina.home=C:\Pentaho\biserver-ce\tomcat      -Djava.endorsed.dirs=C:\Pentaho\biserver-ce\tomcat\endorsed      -XX:MaxPermSize=256m      -Dsun.rmi.dgc.client.gcInterval=3600000      -Dsun.rmi.dgc.server.gcInterval=3600000\Pentaho\biserver-ce\tomcat\temp      -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager      -Djava.util.logging.config.file=C:\Pentaho\biserver-ce\tomcat\conf\
      b. Initial memory pool:        512
      c. For max memory pool:  1024
      d. Thread stack size:          64
    3. On ‘startup’ tab:
      a. Class:           org.apache.catalina.startup.Bootstrap
      b. Arguments:  start
      c. Mode:           jvm
    4. On ‘shutdown’ tab:
      a. Class            org.apache.catalina.startup.Bootstrap
      b. Arguments   stop
      c. Mode           jvm
  7. Apply and close the application
  8. Use services.msc and change its properties to automatic start
  9. Restart your PC-Server

15. Additional Notes

A. There are some errors in the console or logs (/tomcat/logs/) that are not really important, but you can get rid of one (sooner or later someone is going to ask about them): To avoid the “WARNING: Security role name PENTAHO_ADMIN used in an <auth-constraint> without being defined in a <security-role>”. Add before the security-constraint tag in:



   <description>security role</description>

That’s it. If you know something else to add, please let me know.