search
Try Pentaho! - Start your 30 day evaluation today

Manage the Pentaho system

After installation and configuration, use these procedures to manage Pentaho products.

hashtag
In this topic

hashtag
Manage the Pentaho Server

Manage the Pentaho Server by changing User Console behavior, removing sample content, importing email addresses for scheduling, and applying advanced configuration changes.

In this section

hashtag
Hide User Console Home perspective widgets

The User Console default Home perspective contains the Getting Started widget, which has easy instructions and tutorials for evaluators.

Perform the following steps to hide not only the Getting Started widget, but also other Home perspective widgets, as needed:

  1. Shut down the Pentaho Server if it is currently running.

  2. Choose one of the following options depending on your deployment status:

    • If you have not yet deployed, navigate to the /pentaho-platform/user-console/source/org/pentaho/mantle/home/properties/config.properties file.

    • If you have manually deployed and want to hide widgets later, navigate to the /pentaho-server/tomcat/webapps/pentaho/mantle/home/properties/config.properties file.

  3. Find the line that starts with disabled-widgets= and type in the ID of the widget getting-started, as shown in the following example:

    You can also hide the Recents and Favorites widgets using the same method, as shown here. Save and close the file.

  4. Save and close the file.

  5. Locate the /pentaho-server/tomcat/webapps/pentaho/mantle/home directory and open the index.jsp file with any text editor.

  6. Find the following line of code and comment it out, then save and close the file.

  7. Start the Pentaho Server and log in to the User Console.

You now have a Home page without the specified widgets.

hashtag
Turn off autocompletion of User Console sign-in credentials

The User Console sign-in settings have autocomplete turned on by default.

Perform the following steps to manually turn off the autocompletion functionality:

  1. Stop the Pentaho Server.

  2. Navigate to the /pentaho-server/tomcat/webapps/pentaho/jsp directory and open the PUCLogin.jsp file with any text editor.

  3. Find the following two sections of code and change the autocomplete entry to off, as shown:

  4. Save and close the PUCLogin.jsp file.

  5. Restart the Pentaho Server.

Autocompletion of usernames and passwords is now turned off for the User Console sign-in screen.

hashtag
Remove sample data from the Pentaho Server

By default, you have access to a sample data source and a solution directory filled with example content. These samples are provided for testing with sample data. When you are ready to move from a testing scenario to development or production, you can remove the sample content.

Perform the following steps to completely remove the sample data and content:

  1. Stop the Pentaho Server.

  2. Delete the samples.zip file from the /pentaho-server/pentaho-solutions/system/default-content directory.

    If you performed a manual WAR build and deployment, then the file path is: /pentaho-server/pentaho-solutions/system.

  3. Edit the /pentaho/WEB-INF/web.xml file inside of the deployed pentaho.war.

    If you used an archive installation method, the path to the WAR file should be /pentaho-server/tomcat/webapps/pentaho/WEB-INF/web.xml. If you performed a manual WAR build and deployment, you must adjust the path to fit your specific configuration.

  4. Remove the hsqldb-databases section from the /pentaho/WEB-INF/web.xml file:

  5. Remove the hsqldb-starter section from the /pentaho/WEB-INF/web.xml file:

  6. Remove the SystemStatusFilter:

    Note: The SystemStatusFilter filter is not part of the samples. The filter shows error status messages that are only useful for development and testing purposes, and should be removed from a production system.

  7. Remove the filter mapping for the SystemStatusFilter:

  8. Save and close the web.xml file.

  9. Delete the /pentaho-server/data/ directory.

    The /pentaho-server/data/ directory contains a sample database, control scripts for that database, the environment settings it needs to run, and SQL scripts to initialize a new repository.

  10. Restart the Pentaho Server, then sign into the Pentaho User Console with the administrator username and password, go to the Browse Files page, and perform the following steps:

    1. In the Folders pane, expand the Public folder and click to highlight the folder containing the Steel Wheels sample data. Click Move to Trash in the Folder Actions pane and confirm the deletion.

    2. Highlight the folder containing the Pentaho Operations Mart sample data. Click Move to Trash in the Folder Actions pane and confirm the deletion.

The Pentaho Server instance is now cleaned of sample data and content.

hashtag
Importing and updating email addresses used for scheduling from data sources

You can adjust and run sample transformations to import email addresses from LDAP or JDBC sources to be used for scheduling notifications from the Pentaho Server via the Pentaho User Console (PUC). Once you have initially imported the data, you can schedule the transformations to run periodically to update the email addresses based on the LDAP or JDBC sources.

You can find the following sample transformations in the server/pentaho-server/pentaho-solutions/email-import-samples directory:

  • For LDAP sources: LDAPEmailImportV3.ktr

  • For JDBC sources: JDBCEmailImportV3.ktr

You can also use an optional parameter defined for these transformations and a related column in the Pentaho email Hibernate database table to manage multiple sources. Using the parameter and related column helps to keep emails from different sources from interfering with each other. The transformations are designed to only act upon rows in the Hibernate table that match this optional parameter. Any inserts, deletions, or update only apply to those rows with the column that matches the parameter. For example, if you have multiple LDAP servers for different local or business units, such as LDAP-US, LDAP-EU, and LDAP-ASIA. You can adjust the transformation parameter for each one of these sources to import and maintain email addresses from each server without affecting the others.

Import and update email addresses

Perform the following steps in the Pentaho Data Integration (PDI) client to adjust the sample JDBC transformation, then run the transformation to import the email addresses:

  1. Open the sample JDBCEmailImportV3.ktr transformation in the PDI client.

    See the Open a transformation section in the Pentaho Data Integration document for details.

  2. Select Properties from the menu that appears when you right-click in an empty area of the PDI client canvas.

    The Transformation properties dialog box opens.

  3. Click the Parameters tab to access the MANAGED_SOURCE and PENTAHO_BASE_URL transformation parameters.

  4. Specify a source of the email address data for the MANAGED_SOURCE parameter.

    As a best practice, you should use and maintain separate transformations for each source. For example, if you have multiple JDBC databases for different local or business units (such as JDBC-US and JDBC-ASIA), you should save a version of the JDBCEmailImportV3 transformation per each source with MANAGED_SOURCE set to JDBC-US for one transformation and MANAGED_SOURCE set to JDBC-ASIA for the other transformation.

  5. Specify the URL of your Pentaho User Console (PUC) for the PENTAHO_BASE_URL parameter.

    By default, in a standard installation, the URL for PUC is http://localhost:8080/pentaho, yet your Pentaho administrator can and may have configured it to be different from the default. Check with your Pentaho administrator if you are not sure of the URL used for your instance of PUC.

  6. Click OK to close the Transformation properties dialog box.

    With the transformation parameters, you need to specify the related Pentaho email Hibernate database table columns before running the transformation.

  7. Double click on the JDBC Input step in the transformation.

    The Table input step properties dialog box opens.

  8. Specify the column names used for the email source, last names, and first names in your JDBC source with the SQL statements shown in the SQL text box.

    The column name specified for the email source should match the value you specified for the MANAGED_SOURCE parameter.

  9. Click OK to save your specified values and close the Table input step properties dialog box.

  10. Save the transformation as a filename specific to your JDBC source (JDBCEmailImportForJDBC-US.ktr for the JDBC-US managed source for example), then run the transformation.

    See the Run your transformation section in the Pentaho Data Integration document for details.

The email addresses from your JDBC source should now appear on the Email Groups page under the Administration perspective in your PUC instance. You can now use this same transformation to update the email addresses periodically by setting it up to run on a schedule. See the Schedule a transformation or job section in the Pentaho Data Integration document for details.

hashtag
Advanced topics

Set up a cluster

A Pentaho node consists of a Tomcat Web App server and the Pentaho Server. Multiple nodes that are joined make up a cluster. You can create a cluster using any version of Pentaho Suite 6.x or later.

Step 1: Address prerequisites for clustering

Before you begin the process of clustering your servers, a few tasks need to be preformed and some specific requirements must be met to successfully implement a Pentaho deployment on a Tomcat cluster. The following table describes these tasks and requirements:

Requirement
Description

Make sure that all of your application nodes are set up with identical configurations and Pentaho deployments.

Your application nodes all need the same configurations and Pentaho deployments installed already in order for clustering to work.

Establish a load balancer.

This will make sure that computing resources are spread evenly among the nodes.

Each node and the load balancer must be time-synchronized via NTP.

All machines that make up the cluster have to have the same system time. If they do not, execution times of objects will be effected.

You must run only one node per machine (or NIC).

It is possible to run multiple application servers on each node with a modified configuration, but this scenario does not offer any benefit for load balancing (performance) or hardware failover (redundancy), and therefore is not covered in this guide. Refer to your application server's clustering documentation for more information.

You must use the supported version of Tomcat (either default archive installation or manual installation). See the Components reference in the Try Pentaho Data Integration and Analytics document for more information.

You may be able to use this guide as a basic blueprint for configuring other application servers or versions of Tomcat for a clustered environment, but Pentaho support will not be able to assist you if you run into any problems with the Pentaho Server.

You must have permission to install software and modify service configurations.

If you do not have permissions, you must have access to someone at your company who does have the correct permission levels, typically root access.

Only the Pentaho Server will be deployed to the cluster.

It is possible to modify the configuration to deploy other WARs or EARs. However, for ease of testing and support, Pentaho only supports deployment of the pentaho and pentaho-style WARs to the cluster.

You must use a single repository location.

Most people use a database-based solution repository. Keep in mind that you are not clustering the database server in this procedure, only the application server.

You must have sticky sessions enabled.

This will tie your session to a single node.

Step 2: Initialize and configure repository

After you have determined that your systems meet all of the requirements listed in the checklist, you need to first initialize and then configure the repository for clustering. Finally, you need to verify your clustering setup, before you move on to setting up the Jackrabbit journal:

  1. Initialize your database using the appliable steps for your type of installation and database found in the Install Pentaho Data Integration and Analytics document.

  2. After you have initialized your database, configure the data connections to the Pentaho Repository. Define data connections in the Install Pentaho Data Integration and Analytics document walks you through the steps for JDBC and JNDI connections for PostgreSQL, MySQL, and Oracle.

  3. Configure your repository using the appliable steps for your type of installation and database found in the Install Pentaho Data Integration and Analytics document.

  4. After you have initialized and configured your repository, you should clean up these files by following these steps.

    • Locate the pentaho-server/tomcat directory and remove all files and folders from the temp folder.

    • Locate the pentaho-server/tomcat directory and remove all files and folders from the work folder.

    • Locate the pentaho-server/pentaho-solutions/system/jackrabbit/repository directory and remove all files and folders from the final repository folder.

    • Locate the pentaho-server/pentaho-solutions/system/jackrabbit/repository directory and remove all files and folders from the workspaces folder.

You now have a configured repository and are ready to move to the next step for clustering.

Step 3: Configure Jackrabbit Journal

These following steps show how to set up the Jackrabbit journal for your cluster (make sure that each node has a unique ID):

  1. Locate the repository.xml file in the pentaho-server/pentaho-solutions/system/jackrabbit directory and open it with any text editor.

  2. Scroll to the bottom of the file and replace the section that begins with <!-- Run with a cluster journal --> with the correct code for your type of database repository.

    For PostgreSQL only:

    For MySQL only:

    For Oracle only:

    For MS SQL Server only:

  3. Save and close the file.

Jackrabbit journaling is now set up for your cluster. The Jackrabbit Wikiarrow-up-right has additional information about journaling.

Next, you need to cluster the quartz tables to avoid duplicate scheduling on each node.

Step 4: Configure Quartz

You now need to make a few edits in the quartz.properties file to configure Quartz to work with your cluster.

  1. Locate the quartz.properties file in the pentaho-server/pentaho-solutions/system/scheduler-plugin/quartz directory and open it with any text editor.

  2. Find the org.quartz.scheduler.instanceId = INSTANCE_ID line and change INSTANCE_ID to AUTO.

  3. Find the #_replace_jobstore_properties section and change the default value of org.quartz.jobStore.isClustered to true as shown:

  4. Add this line just after the org.quartz.jobStore.isClustered = true line:

Quartz is now configured for your cluster. The Quartz Configuration Referencearrow-up-right has additional information about clustering with Quartz.

Step 5: Start and test the cluster

Start the cluster and verify that it is working properly with the following steps:

  1. Start the solution database.

  2. Start the application server on each node.

  3. Make sure that the load balancer is able to ping each node.

  4. Repeat for each node that you have set up.

  5. Test the cluster by accessing the Pentaho Server through the load balancer's IP address, hostname, or domain name.

Begin whatever test procedure you have designed for this scenario.

Customize the Pentaho Server

Activate view-only mode for Interactive reports

In the Pentaho User Console, you can create a view-only user that does not have access to edit Interactive reports. This requires you to remove the edit icon in the report view for view-only users.

Perform the following steps to remove the edit icon:

  1. Stop the Pentaho Server.

  2. Locate the server\\pentaho-solutions\\system directory.

  3. Open the Pentaho.xml file with any text editor.

  4. Locate the <edit-permission> tag and uncomment the following line:

  5. Save and close the Pentaho.xml file.

  6. Start the Pentaho Server.

Change Ports and URLs

The Pentaho Server has associated default port numbers. You can change these port numbers to adjust the Pentaho Server to your system. Since the port number of the Pentaho Server is a part of its URL, you will also have to change that address.

List of server ports used by PDI

The following port numbers must be available internally on the machine that runs the Pentaho Server:

Service
Port Number

Pentaho Server

8080

H2 (SampleData)

9092

Embedded Pentaho Server (Jetty)

10000

The SampleData database is an exception. It is only for evaluation and demonstration purposes and is not necessary for production systems.

Note: The Embedded Pentaho Server (Jetty) server port is hard-coded in Pentaho Data Integration and cannot be changed. If port 10000 is unavailable, the system will increment by 1 until an available port is found.

Change Pentaho Server (Tomcat) port numbers

Edit the /pentaho/server/pentaho-server/tomcat/conf/server.xml file and change the port numbers as shown in the following example code:

Note: You may also have to change the SSL and SHUTDOWN ports in this file, depending on your configuration.

Change the Pentaho Server URL

You can change the Pentaho Server hostname from localhost to a specific IP address, hostname, or domain name by following these instructions. This procedure is also a requirement if you are changing the Pentaho Server port number.

  1. Stop the Pentaho Server.

  2. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the server.properties file with any text editor.

  3. Modify the value of the fully-qualified-server-url element appropriately.

  4. Save and close the file.

  5. Start the Pentaho Server.

The Pentaho Server is now configured to reference itself at the specified URL.

Note: If you recently upgraded to Pentaho 6.x or higher from a version earlier than 6.0, you may need to remove the <context-param> entry for the fully-qualified-server-url from the /tomcat/webapps/pentaho/WEB-INF/web.xml. If so, restart the Pentaho Server after removing it.

Change the Karaf startup timeout setting

Upon start up, the system waits for Karaf to install all of its features before timing out. If you modify Karaf and it now takes longer to install during start up, you may need to extend the default timeout setting to allow Karaf more time to install. The current default timeout is: 120000 (milliseconds - about 2 minutes).

You can change this default timeout by editing the server.properties file.

  1. Stop the Pentaho Server.

  2. Navigate to the /pentaho-server/pentaho-solutions/system directory.

  3. Open the server.properties file with any text editor, and search for the karafWaitForBoot parameter.

  4. Uncomment the line containing the parameter and set it to your desired wait time in milliseconds

  5. Save and close the file.

  6. Restart the Pentaho Server

Change the PDI home directory location

The default location for the Pentaho Data Integration home directory is the .kettle directory in your system user's home directory.

  • Windows: C:\\Documents and Settings\\example_user\\.kettle

  • Linux: ~/.kettle)

There will be a different .kettle directory, and therefore a different set of configuration files, for each system user that runs PDI.

The contents of this directory are listed in the following table:

File
Purpose

kettle.properties

Main PDI properties file; contains global variables for low-level PDI settings

shared.xml

Shared objects file

db.cache

The database cache for metadata

repositories.xml

Connection details for PDI database or solution repositories

.spoonrc

User interface settings, including the last opened transformation/job

.languageChoice

Default language for the PDI client tool

Standalone PDI client tool deployments

You can specify a single, universal .kettle directory for all users by declaring a KETTLE_HOME environment variable in your operating system. When declaring the variable, leave out the .kettle portion of it; this is automatically added by PDI.

export KETTLE_HOME=/home/pentaho/examplepath/pdi

Pentaho Server deployments that run PDI content

If you followed a manual deployment or archive package installation path, you can set a system environment variable as explained above, but it must be declared before the Pentaho Server service starts. You can alternatively change the CATALINA_OPTS system variable to include the -D flag for KETTLE_HOME, or you can edit the script that runs the Pentaho Server and set the flag inline, as in this example from the start-pentaho.sh script:

export CATALINA_OPTS="--Xms2048m -Xmx2048m -XX:MaxPermSize=256m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000" -DKETTLE_HOME=/home/pentaho/examplepath/pdi

Windows service modification

If you used the graphical utility to install the Pentaho Server, then you must modify the Java options flag that runs the Pentaho Server Tomcat service. Here is an example command that will change the value of KETTLE_HOME to C:\\<examplepath>\\pdi\\.kettle:

tomcat8.exe //US//pentahobiserver ++JvmOptions -DKETTLE_HOME=C:\\examplepath\\pdi

Change the Quartz misfire threshold

With Quartz, sometimes scheduled jobs, transformations, or reports might try to run several times when they are manually stopped and restarted, instead of running only once. This is typically caused by the misfireThreshold property in Quartz being set at too high of a number.

These steps show how to reset the misfireThresholdto a lower numerical value.

  1. Stop the Pentaho Server.

  2. Locate the /pentaho-server/pentaho-solutions/system/scheduler-plugin/quartz directory.

  3. Open the quartz.properties file with any text editor.

  4. Find the property shown below and change the default to a smaller number, such as 5000. The default value represents the number of milliseconds.

  5. Save and close the quartz.properties file.

  6. Start the Pentaho Server.

Change the location of the server log file

Windows server log file location

To change the location of the pentaho.log file, edit log4j2.xml in /pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes/.

Modify the location as shown in the following sample, using the appropriate path to your installation:

Linux server log file location

If you are using Linux, the log4j2.xml file is in /pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes/.

Modify the location as shown in the following sample, using the appropriate path to your installation:

Change the port numbers for the Pentaho Server

Follow the instructions below to change the port through which the Pentaho Server runs:

  1. Stop the Pentaho Server.

  2. Navigate to the /pentaho-server/tomcat/conf/ directory.

  3. Open the server.xml file with any text editor, and search for the value for Define a non-SSL HTTP/1.1 Connector.

    Change the port number in the connector port element below from 8080 to your preferred port number.

  4. Save and close the server.xml file.

  5. Navigate to the /pentaho-server/pentaho-solutions/system directory and open the server.properties file with any text editor.

  6. Change the fully-qualified-server-url entry to match the new port number you specified in server.xml.

  7. Save and close the file.

  8. Restart the Pentaho Server.

If you recently upgraded to Pentaho 6.0, you may need to remove the <context-param> entry for the fully-qualified-server-url from the /tomcat/webapps/pentaho/WEB-INF/web.xml. If so, restart the Pentaho Server after removing it.

Change the staging database for CSV files

Hibernate is the default staging database for CSV files. Follow these instructions if you want to change the staging database.

  1. Go to /pentaho-solutions/system/data-access and open the settings.xml file with any text editor.

  2. Edit the settings.xml file as needed.

    The default value is shown in the sample below:

    This value can be a JNDI name or the name of a Pentaho database connection. See the Install Pentaho Data Integration and Analytics document for more information on database connections.

  3. Save and close the file.

  4. Restart the User Console

Change the web application name or port

The Pentaho Server and web application default port number is 8080. The default web application name is pentaho, which is the name of the WAR file archive, the name of the directory that your application server creates, and also part of the URL structure for all content in the User Console.

If you need to change the User Console application name to something else, or if your Web application server is running on a port other than 8080, follow these instructions.

Change the web application name on Tomcat

These instructions only work on Tomcat servers that are configured to accept context.xml overrides built into deployed WAR files. Some Tomcat deployments may not have this feature turned on. You can change the Tomcat configuration on your own, or consult your Tomcat documentation to learn about other methods of changing a web application context. Use the XML snippet in these instructions in whichever configuration file you end up creating or modifying.

Follow these instructions to change the web application context for a pentaho.war file that you deployed to a Tomcat server. While the example below uses sample as the context name, you can use whatever context name you choose.

  1. Stop the server.

  2. Open the pentaho/server/pentaho-server/tomcat/webapps/pentaho/META-INF/context.xml file in a text editor, and change the pentaho references in the context path tag to your preferred context name.

    For example, to specify a context name of sample, modify context path as follows.

  3. Save and close the file.

  4. Navigate to the pentaho/server/pentaho-server/tomcat/webapps folder, and rename the pentaho folder to your preferred context name. In this example, rename the pentaho folder to sample.

  5. Edit the pentaho/server/pentaho-server/tomcat/webapps/ROOT/index.jsp file to change the pentaho reference in the URL property to your preferred context name.

    In this example, use the following line of code to specify 'sample' as the new context name:

  6. Edit the pentaho/server/pentaho-server/pentaho-solutions/system/server.properties file to change pentaho in the value of the fully-qualified-server-url setting to your preferred context name.

    In this example, set the fully-qualified-server-url as follows.

  7. Start the server.

Increase the CSV file upload limit

You may find that you need to increase the size of the upload limit for your CSV files. These steps guide you through this process.

  1. Go to /pentaho-server/pentaho-solutions/system and open the pentaho.xml file.

  2. Edit the XML as needed (sizes are measured in bytes):

  3. Save your changes to the file.

  4. In the User Console, go to Tools > Refresh System Settings to ensure that the change is implemented.

  5. Restart the User Console.

Manage config files for the Scheduler plugin

The following configuration files for using the Scheduler plugin with LDBC and LDAP should only be customized by someone with the necessary qualifications and experience.

settings.xml

This file is located in the pentaho-server/pentaho-solutions/system/scheduler-plugin directory and contains properties that you can use to control the plugin cache for development purposes. In most cases, it is best not to modify any of the properties for cache-messages, max-age, or cache elements.

It also contains a section for defining the data source to be used for email group administration purposes in order to import existing emails and groups under the email-source element.

Example:

Valid value for the email-source element:

Valid values
Description

jdbc

Uses a JDBC data source to import emails and groups.

ldap

Uses an LDAP data source to import emails and groups.

pentaho

Does not import emails and groups. Instead, you can create emails and groups using the email group administration module in PUC.

The configuration properties for the JDBC and LDAP data sources are located in the applicationContext-email-import.properties file.

applicationContext-email-import.properties

This file is located in the pentaho-server/pentaho-solutions/system/scheduler-plugin directory and contains the configuration properties for the JDBC and LDAP data sources. These data sources can be changed in the settings.xml file under the email-source element.

Note: Only someone with sufficient understanding of JDBC and LDAP should make changes to this file.

File location: pentaho-server/pentaho-solutions/system/scheduler-plugin

The password is encrypted using the Encr utility. The Encr.bat and Encr.sh files are located in the same directory as the startup script for Pentaho Server.

The emails-imported property defines whether emails have already been imported. If true, then no more emails are imported. After initial import, this property is automatically set to true. If more imports are done from a different data source, then this property needs to be set back to false.

Example based on a JDBC data source.

The actual query depends on the source RDBMS.

Prerequisites:

  • The correct JDBC driver must be in the classpath for the JDBC configuration to work.

  • In the example, the <datasource>.emails-query must return first name, last name, and email in that order. Field names in the output are dependent on the table columns that are imported.

JDBC example:

Example based on a LDAP data source.

Prerequisites:

  • Attributes required for LDAP must be in the following order: <firstName>,<lastName>,<email>.

LDAP example:

For more information about JDBC, see https://www.oracle.com/java/technologies/javase/javase-tech-database.htmlarrow-up-right

For more information about LDAP, see https://ldap.com/arrow-up-right

quartz.properties

This file is located in the pentaho-server/pentaho-solutions/system/scheduler-plugin/quartz directory and is the properties file for the open source job scheduling framework, Quartz. Refer to the official Quartz documentation at http://www.quartz-scheduler.org/documentation/arrow-up-right.

Set default SELECT DISTINCT for Interactive Reports

By default, Interactive Reports queries data with the SQL SELECT DISTINCT statement to return only distinct (different) data values, which may require an extensive sorting operation in the database. If you want to reduce the cost of a system-wide sorting operation, you can set new reports to open with the Select Distinct option cleared.

Perform the following steps to change the default setting of the Select Distinct option in the Query Setting dialog box of new Interactive Reports:

  1. Stop the Pentaho Server.

  2. Locate the server/pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting directory.

  3. Open the settings.xml file with any text editor.

  4. Find the <default-select-distinct> tag and change it to the desired setting.

    If you want the Select Distinct option cleared as the default, set the <default-select-distinct> tag to false as shown in the following example code:

  5. Save and close the settings.xml file.

  6. Start the Pentaho Server.

Set system max row limit for Interactive Reports

You can prevent too many resources from hitting your database server at once by setting a system-wide maximum row-limit for Pentaho Interactive Reports. Your users can still define their own design-time row limits in Interactive Reports, but they will never be able to go over the maximum number of rows that you have specified while designing their reports.

  1. Shut down the Pentaho Server.

  2. Locate the /pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting directory.

  3. Open the settings.xml file with any text editor.

  4. Find the <query-limit> tag and change the default number of 100000 within the tags to the maximum number of rows desired.

  5. Save and close the file.

  6. Start the Pentaho Server.

If you are migrating content from a previous version, you will need to add the <query-limit> tag to your settings.xml for Interactive Reports.

Roll back system max row limit

These instructions show you how to return the system maximum row limit to the Pentaho 5.3 settings.

  1. Shut down the Pentaho Server.

  2. Locate the /pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting directory.

  3. Open the settings.xml file with any text editor.

    1. To change the maximum number of rows that will be rendered in Pentaho Interactive Reports in edit or view mode, find the <design-query-limit> tag and change the default number of 500 back to 25.

      FROM:

      TO:

    2. To turn the design-query-limit to be OFF by default, find the <design-query-limit-enabled> tags and change the value to false.

  4. Save and close the settings.xml file.

  5. Restart the server.

hashtag
Manage the Pentaho Repository

You can use the Pentaho Repository to share files and folders across teams and products.

The Pentaho Repository is an environment for collaborative analysis and ETL (extract, transform, and load) development.

In this section

hashtag
Upload and download from the Pentaho Repository

You can upload and download from the Pentaho Repository with the Pentaho User Console (PUC) or the command line interface. The ability to upload and download assumes that you have already created a data source, that data content exists to be pushed, and defines permissions for the repository.

For uploading, any starting location can be selected. Permission settings are inherited through the folder structure if the destination location has existing permission settings. It is advisable to keep existing security settings as defaults for the upload.

For downloading, you are able to select the destination location for the downloaded file or folder. The download process always creates a ZIP file that includes a manifest file along with the downloaded content. The manifest file contains the collection of permissions settings for the downloaded files and folders and is found in the root directory of the ZIP file.

Supported File Types
Hidden File Types

The following file types and artifacts are supported for uploading and downloading from the Pentaho Repository.

The following file types are hidden by default in the Pentaho Repository.

  • Reporting (.prpt, .prpti; .xml)

  • Analyzer (.xanalyzer)

  • Dashboards (.xdash)

  • Solution Files (.xaction; .locale)

  • Web (.html; .htm)

  • Reporting (.xml)

  • Solution Files (.properties)

  • Graphics (.png; .jpg, .gif; .svg)

Upload folders and files

The User Console can be used to upload files and folders to the Pentaho Repository. To upload files, a user must have a role with the Publish Content operation permission and Write permission for the target folder (Browse Files > Properties > Share > Users and Roles > Permissions), where permissions can be held through a user name or a role that the user holds (Power User for example). See the Pentaho Business Analytics document for details on publish and write permissions.

For Retain permission on upload file, the file permission contained in the uploaded ZIP (exportManifest.xml) will be the permission applied the repository. If the file doesn't have an entry in the exportManifest.xml for the permission, then it will use the default permission, which is inherit. This is equivalent to the command line switch: --permission=true

For Set Owner based on uploaded file, the owner found in the uploaded ZIP (exportManifest.xml) will be the owner of the file in the repository. If the file does not have an entry in the exportManifest.xml for the Owner, then it will set the Owner to the user who is uploading the zip. This equivalent to the command line switch: --retainOwnership=true

Complete the following steps to upload one or more files to the repository with the User Console.

  1. From the User Console Home, click Browse Files.

    The Browse Files page appears.

  2. From the Browse pane on the left, click to choose the destination folder for the upload.

  3. With the destination folder highlighted, click Upload in the Folder Actions pane on the right.

    The Upload dialog box appears.

  4. Browse to the files or zipped folders to be uploaded by clicking Browse.

  5. Select one or more files or zipped folders to upload.

  6. Click OK to begin upload using the default settings.

  7. Choose preferences for the upload by clicking to expand the Advanced Options menu.

    1. Choose Replace the Existing File or Do Not Upload from the first menu.

    2. Choose File Permissions from the second menu.

      The choices are Do Not Change Permissions or RetainPermissions on the Uploaded File.

    3. If you selected Retain Permissions on the Uploaded File, choose File Ownership by selecting Do Not Change Owner or Set Owner Based on Uploaded File from the third menu.

    4. Choose None, Short, or Verbose from the Logging menu.

  8. Click OK.

The upload runs and the files or folders are uploaded to the repository. If the upload fails, an error log window opens with specific information.

Upload from the command line

  1. Open the command line interface by clicking Start and typing cmd. Press Enter.

  2. From the command line interface, go to the location where you have a local copy of the Pentaho Server installed, such as: C:/dev/pentaho/pentaho-server

  3. Enter a space, then type the arguments for upload into the command line interface. A completed upload argument would look something like this:

    import-export.bat --import --url=http://localhost:8080/pentaho --username=dvader --password=password --charset=UTF-8 --path=/public --file-path=C:/Users/dvader/Downloads/pentaho-solutions.zip --overwrite=true --permission=true --retainOwnership=true

  4. Press Enter after the arguments are typed.

The upload process runs and the results are displayed in the command interface. If an argument is required for successful upload and has not been provided, the missing requirement is displayed in the command interface. The Command line arguments reference has a list of available command line arguments for uploading.

Download folders and files

Downloading folders and files can be done through the User Console or through the command line interface. The download process always creates a ZIP file that includes a manifest file along with the downloaded content. The manifest file is a collection of the permissions settings for the downloaded files and folders and is found in the root directory of the ZIP file.

Download action permissions

Only the Administrator role has downloading permissions, by default. The roles that have download action permissions are defined in the in the pentaho.xml configuration file. To add downloading permissions for a user, add that user to a role that has download permissions as shown below:

CAUTION:

Providing the download action permissions to non-admin users can expose sensitive data.

  1. Stop the Pentaho Server.

  2. Navigate to the pentaho.xml file, located at: /server/pentaho-server/pentaho-solutions/system/pentaho.xml

  3. Open the file with any text editor and locate the download-roles node in the file.

  4. Add additional roles as needed.

    To create a Power User, type:

    Note: Use a comma between roles; not spaces.

  5. Save and close the pentaho.xml file.

  6. Restart the Pentaho Server.

  7. Restart the User Console. Log on as a user with that role.

    You will now see the Download option in the File Actions pane in the Browse Files perspective of the User Console.

See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server.

Download a folder

  1. From the User Console Home, click Browse Files.

    The Browse Files page appears.

  2. From the Browse pane on the left, browse to the location of the folder to be downloaded.

  3. With the folder highlighted, click Download in the Folder Actions pane on the right.

  4. Choose Save File in the window that appears, and click OK.

The folder is saved as a ZIP file with the manifest located in the top level of the file.

Download a file

  1. From the User Console Home, click Browse Files.

    The Browse Files page appears.

  2. Browse to the location of the file by clicking through the folders in the Browse pane on the left.

    The Files pane in the center populates with a list of reports.

  3. Click to select the file in the Files pane and choose Download in the Folder Actions pane on the right.

  4. Choose Save File in the window that appears, and click OK.

The file is saved as a ZIP file with the manifest located in the top level of the file.

Download from the command line

  1. Open the command line interface by clicking Start and typing cmd. Press Enter.

  2. From the command line interface, go to the location where you have a local copy of the Pentaho Server installed, such as: C:/dev/pentaho/pentaho-server

  3. Enter a space, then type the arguments for download into the command line interface

    A completed download argument would look something like this: import-export.bat --export --url=http://localhost:8080/pentaho --username=dvader --password=password --charset=UTF-8 --path=/public --file-path=C:/Users/dvader/Downloads/pentaho-solutions.zip --overwrite=true --permission=true --retainOwnership=true

  4. Press Enter after typing the arguments.

The download process runs and the results are displayed in the command interface. The file is saved as a ZIP file with the download manifest located in the top level of the file. If an argument is required for successful download and has not been provided, the missing requirement is displayed in the command interface. The Command line arguments reference has a list of available command line arguments for downloading.

Response code definitions

Here is a list of response codes for the import-export.bat script:

Response Code
Definition

1

Publish to server failed.

2

General publish error.

3

Publish successful.

5

Authentication to the publish server failed. Username or password is incorrect.

6

Datasource publish failed.

7

XMLA catalog already exists.

8

Schema already exists.

9

Content about to be published already exists.

10

Error publishing to the server due to prohibited symbols in the name of the content.

Command line arguments reference

You can use the command line to manage the Pentaho Repository. The following tables list the command arguments, descriptions, values, and whether a specific argument is required.

Upload

The following arguments are for uploading to the Pentaho Repository:

Command
Description
Values
Required

-i, --import

Upload Command

n/a

Yes

-x, --source <arg>

External system type

legacy-db or file-system (default)

Yes

-o, --overwrite <arg>

Overwrites file(s) on upload. Default value is: True

Boolean

No

-m, --permission <arg>

Applies ACL using manifest file. Default value is: True

Boolean

No

-r, --retainOwnership

Replaces the file ownership upon upload with the ownership of the original download. Default value is: True

Boolean

No

-t, --type <arg>

The type of content being uploaded- files (default), metadata.

File type

No

Download

The following arguments are for downloading from the Pentaho Repository:

Command
Description
Values
Required

-e, --export

Download command

n/a

Yes

-fp, --filepath <arg>

Location that the ZIP file is downloaded to

File path

Yes

-w, --withManifest <arg>

If true, includes Manifest.xml inside ZIP. If false, download excludes this file.

Boolean

No

Backup and restore

The following arguments are for backing up or restoring the Pentaho Repository:

Command
Description
Values
Required

--backup

Backup command

n/a

Yes

--restore

Restore command

n/a

Yes

-a, --url <arg>

URL of Pentaho Repository (for example: http://localhost:8080/pentahoarrow-up-right)

URL

Yes

-u, --username <arg>

Pentaho Repository username

Alphanumeric

Yes

-p, --password <arg>

Pentaho Repository password

Alphanumeric

Yes

-fp, --filepath <arg>

Location that the ZIP file is downloaded to

File path

Yes

-o, --overwrite <arg>

Overwrites file(s) on upload. Default value is: True

Boolean

No

--logfile

Specifies the location for writing the log file.

File path

No

--logLevel

Specifies log detail level.

File path

No

Common arguments

The following arguments apply to uploading, downloading, backing up and restoring the Pentaho Repository:

Command
Description
Values
Required

-a, --url <arg>

URL of Pentaho Repository (for example: http://localhost:8080/pentahoarrow-up-right)

URL

Yes

-c, --charset <arg>

Charset to use for the repository. Characters from external systems are converted to this charset.

UTF-8 (default)

No

-h, --help

Prints this message.

n/a

No

-f, --path <arg>

Pentaho Repository path to which the uploaded files are added (for example: /public)

File path

Yes

-p, --password <arg>

Pentaho Repository password

Alphanumeric

Yes

-u, --username <arg>

Pentaho Repository username

Alphanumeric

Yes

-l, --logfile <arg>

Path to local file system with name of file to write

File path

No

-a_ds, --analysis-datasource <arg>

Analysis datasource type.

Alphanumeric

No

-a_xmla, --xmla-enabled <arg>

Analysis XMLA enabled flag.

Boolean

No

-cat, --catalog <arg>

Catalog description.

Alphanumeric

No

-ds, --datasource-type <arg>

Datasource type.

Alphanumeric

No

-m_id, --metadata-domain-id <arg>

Metadata domain ID.

Alphanumeric

No

-params, --params <arg>

Parameters to pass to REST service call.

Alphanumeric

No

-res, --resource-type <arg>

Import/Export resource type.

Alphanumeric

No

-rest, --rest

Use the REST (default) version (not local to the Pentaho Server).

Alphanumeric

No

-v, --service <arg>

This is the REST Service call, for example: ACL, children, properties

URL

No

hashtag
Import and export PDI content

You can import and export PDI content from and to a repository by using PDI's built-in functions, explained in these subsections.

Among other purposes, these procedures are useful for backing up and restoring content in the solution repository. However, users, roles, permissions, and schedules are not included in import/export operations. If you want to back up these items, you should follow the procedure in Backup and restore Pentaho repositories instead.

Note: If you are on Pentaho version 8.0 or earlier, as a best practice to avoid errors when exporting and importing repository contents, select specific content and not the entire repository. For more information, see Importing and exporting PDI content with Pentaho 8.0 and earlierarrow-up-right.

Import content into a repository

Follow the instructions below to import the repository. You must already be logged into the repository in the PDI client before you perform this task.

  1. In the PDI client, go to Tools > Repository > Import Repository.

  2. Locate the export (XML) file that contains the solution repository contents.

  3. Click Open.

    The Directory Selection dialog box appears.

  4. Select the directory in which you want to import the repository.

  5. Click OK.

  6. Enter a comment, if applicable.

  7. Wait for the import process to complete.

  8. Click Close.

The full contents of the repository are now in the directory you specified.

Import content from the command line

The import script is a command-line utility that pulls content into an enterprise or database repository from an individual .kjb or .ktr file, or from complete repository export XML files.

You must also declare a rules file that defines certain parameters for the data integration content you are importing. We provide a sample file called import-rules.xml, which is included with the standard Data Integration client tool distribution. It contains all the potential rules, along with comments that describe what each rule does. You can either modify the import-rules.xml file or copy its contents to another file, and then declare the rules file as a command-line parameter.

The table below defines command-line options for the import script, which are declared using the syntax specific to the operating system type:

  • Linux

    Options are declared using a dash (-) followed by the option name, then an equals sign (=) and the value, where applicable. For example: -option=value

  • Windows

    Options are declared using a forward slash (/) followed by the option name, then a colon (:) and the value, where applicable. For example: /option:value

Note: For options requiring no value entry (replace, coe, and version), a dash or slash (depending on your OS) followed by the option is the equivalent of selecting ‘Yes’; otherwise, the option is ignored.

Options
Definition / Value

rep

The name of the enterprise or database repository to import into.

user

The repository username you will use for authentication.

pass

The password for the username you specified with user.

dir

The directory in the repository that you want to copy the content to.

limitdir

Optional. A list of comma-separated source directories to include (excluding those directories not explicitly declared).

file

The path to the repository export file that you will import from.

rules

The path to the rules file, as explained above.

comment

The comment that will be set for the new revisions of the imported transformations and jobs.

replace

Replace existing transformations and jobs in the repository. (The default is: No)

coe

Continue on error, ignoring all validation errors. (The default is: No)

version

Show the version, revision, and build date of the PDI instance that the import script interfaces with. (The default is: No)

  • Linux

    Import.sh -rep= Archive71 -user=admin -pass=password -coe -replace -dir=/home/admin -file= /Downloads/imagitasDemoEnclosure.ktr -rules=/Downloads/import-rules.xml -comment="New version upload from UAT"

  • Windows

    Import.bat /rep:Archive71 /user:admin /pass:password /coe /replace /dir:\home\admin /file:C:\Downloads\imagitasDemoEnclosure.ktr /rules:C:\Downloads/import-rules.xml /comment:"New version upload from UAT"

Export content from the repository

Follow the instructions below to export the repository. You must already be logged into the repository through the PDI client to complete this task.

  1. In the PDI client, go to Tools > Repository > Export Repository.

  2. In the Save As dialog box, browse to the location where you want to save the export file.

  3. Type a name for your export file in the File Name text box.

  4. Click Save.

The export file is created in the location you specified. This XML file is a concatenation of all of the data integration content you selected. It is possible to break it up into individual KTR and KJB files by hand or through a transformation.

Export content from the command line

To export repository objects into XML format, using command-line tools instead of exporting repository configurations from within Spoon, use named parameters and command-line options when calling Kitchen or Pan from a command-line prompt.

The following is an example command-line entry to execute an export job using Kitchen:

Parameter
Description

rep_folder

Repository Folder

rep_name

Repository Name

rep_password

Repository Password

rep_user

Repository Username

target_filename

Target Filename

It is also possible to use obfuscated passwords with Encr, the command line tool for encrypting strings for storage/use by PDI. The following is an example command-line entry to execute a complete command-line call for the export in addition to checking for errors:

hashtag
Set PDI version control and comment tracking options

Pentaho Data Integration (PDI) can track versions and comments for jobs, transformations, and connection information when you save them. You can turn version control and comment tracking on or off by modifying their related statements in the repository.spring.properties text file.

Note: By default, version control and comment tracking are disabled (set to false).

Editing the version control statement

  1. Exit from the PDI client (also called Spoon).

  2. Stop the Pentaho Server.

    See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server..

  3. Open the pentaho-server/pentaho-solution/system/repository.spring.properties file in a text editor.

    • To enable version control: Edit the versioningEnabled statement and set it to: true

    • To disable version control: Edit the versioningEnabled statement and set it to: false

      Note: If you disable version control, comment tracking is also disabled.

  4. Save and close the file.

  5. Start the Pentaho Server.

    See the Install Pentaho Data Integration and Analytics document for instructions on starting and stopping the Pentaho Server..

  6. Start the PDI client.

  7. Verify that version control is set as you intended.

Verifying the version control option

  1. Connect to the Pentaho Repository.

  2. In the PDI client, click Tools > Explore.

  3. In the Repository Explorer window, click on the Browse tab, then click on a file name.

  4. Verify that version control is enabled or disabled:

    • Enabled

      You can see the Access Control tab, and the Version History tab is visible.

      Version History tab in the PDI client

    • Disabled

      You can see the Access Control tab, but the Version History tab is hidden.

      Access Control tab in the PDI client

Editing the comment tracking statement

  1. Exit from the PDI client (also called Spoon).

  2. Stop the Pentaho Server.

  3. Open the pentaho-server/pentaho-solution/system/repository.spring.properties file in a text editor.

    • To enable comment tracking: Edit the versionCommentsEnabled statement and set it to true.

    • To disable comment tracking: If you want version control, but not comment tracking:

      • Edit the versioningEnabled statement and set it to true.

      • Edit the versionCommentsEnabled statement and set it to false.

  4. Save and close the file.

  5. Start the Pentaho Server.

  6. Start the PDI client.

  7. Verify that Version Control and Comment Tracking are set as you intended.

Verifying the comment tracking option

  1. Connect to the Pentaho Repository.

  2. In the PDI client, click Tools > Explore.

  3. In the Repository Explorer window, click on the Browse tab, then click on a file name.

  4. Verify that comment tracking is enabled or disabled:

    • Enabled

      The Version History tab appears with the Comments field. When you save a transformation, job, or connection information, you are prompted to enter a comment.

      Version History tab showing the Comments column in the PDI client

    • Disabled

      The Version History tab appears and the Comment field is hidden. When you save a transformation, job, or connection information, you are no longer prompted to enter a comment.

      Version History tab with the Comments column hidden in the PDI client

hashtag
Purge transformations, jobs, and shared objects from the Pentaho Repository

The Purge Utility allows you to permanently delete shared objects (servers, clusters, and databases) stored in the Pentaho Repository as well as content (transformations and jobs). You can also delete revision information for content and shared objects.

CAUTION:

Purging is permanent. Purged items cannot be restored.

To use the Purge Utility, complete these steps.

  1. Make sure the Pentaho Repository is running.

  2. Open a shell tool, command prompt window, or terminal window, and navigate to the pentaho/design-tools/data-integration directory.

  3. At the prompt enter the purge utility command.

    The format for the command, a table that describes each parameter, and parameter examples follow.

    Note: The command must contain the url, user, and password parameters, as well as one of these parameters: versionCount, purgeBeforeDate, purgeFiles, or purgeRevisions.

    • Windows

      purge-utility.bat [-url] [-user] [-password] [-purgeSharedObjects][-versionCount] [-purgeBeforeDate] [-purgeFiles] [-purgeRevisions] [-logFileName] [-logLevel]

    • Linux

      purge-utility.sh [-url] [-user] [-password] [-purgeSharedObjects] [-versionCount] [-purgeBeforeDate] [-purgeFiles] [-purgeRevisions] [-logFileName] [-logLevel]

    Option
    Required?
    Description

    -url

    Y

    URL address for the Pentaho Repository. This is a required parameter. By default, the Pentaho Server is installed at this URL: http://localhost:8080/pentahoarrow-up-right

    -user

    Y

    Username for an account that can access the Pentaho Server as an administrator. This is a required parameter.

    -password

    Y

    Password for the account used to access the Pentaho Server. This is a required parameter.

    -purgeSharedObjects

    N

    When set to TRUE, the parameter purges shared objects from the repository. This parameter must be used with the purgefile parameter. If you try to purge shared objects without including the purgefile parameter in the command line, an error occurs. If you set the purgeSharedObjects parameter to FALSE, it does not purge shared objects. If you include the purgeSharedObjects parameter in the command, but you don't set it to TRUE or FALSE, the Purge Utility will assume that it is set to TRUE.

    -versionCount

    You must include only one of these: versionCount, purgeBeforeDate, purgeFiles, or purgeRevisions

    Deletes entire version history except the for last versionCount versions. Set this value to an integer.

    -purgeBeforeDate

    Deletes all versions before purgeBeforeDate. The format for the date must be: mm/dd/yyyy

    -purgeFiles

    When set to TRUE, transformations and jobs are permanently and physically removed. Shared objects (such as database connections) are NOT removed. If you want to also remove shared objects, include the purgeSharedObject parameter as well. If you set the purgeFiles parameter to FALSE, it does not purge files. If you include the purgeFiles parameter in the command, but you don't set it to TRUE or FALSE, the Purge Utility will assume that it is set to TRUE.

    -purgeRevisions

    When set to TRUE, all revisions are purged, but the current file remains unchanged. If you set the purgeRevisions parameter to FALSE, it does not purge revisions. If you include the purgeRevisions parameter in the command, but you do not set it to TRUE or FALSE, the Purge Utility will assume that it is set to TRUE.

    -logFileName

    N

    Allows you to specify the file name for the log file. If this parameter is not present, the log is written to a file that has this name format: purge-utility-log-YYYYMMdd-HHmmss.txt YYYYMMdd-HHmmss indicates the date and time that the log file was created (e.g., purge-utility-log-20140313-154741.txt).

    -logLevel

    N

    Indicates the types and levels of detail the logs should contain. Values are: ALL, DEBUG, ERROR, FATAL, TRACE, INFO, OFF, and WARN. By default the log is set to INFO. Check the Log4J documentation for more details on the logging framework definitions: https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/Level.htmlarrow-up-right.

    • In this example, only the last five revisions of transformations and jobs are NOT deleted. All previous revisions are deleted.

      purge-utility.bat -url=http://localhost:8080/pentaho -user=jdoe -password=mypassword -versionCount=5

    • In the example that follows all revisions before 01/11/2009 are deleted. Logging is set to the WARN level.

      purge-utility.bat -url=http://localhost:8080/pentaho -user=jdoe -password=mypassword -purgeBeforeDate=01/11/2009 -logLevel=WARN

    • In this example, all transformations, jobs, and shared objects are deleted. You do not need to set the purgeFiles and purgeSharedObjects parameters to TRUE for this command to work. Logging is turned OFF.

      purge-utility.bat -url=http://localhost:8080/pentaho -user=jdoe -password=mypassword -purgeFiles -purgeSharedObjects -logLevel=OFF

  4. When finished, examine the logs to see if there were any issues or problems with the purge.

  5. To see the results of the purge process, disconnect, then reconnect to the Pentaho Repository. In the Repository Explorer, in the Browse tab, verify that the items you specified in your purge utility command were purged.

hashtag
Backup and restore Pentaho repositories

A complete backup and restore of your Pentaho repositories can be done through either the command (cmd) window or with the File Resource service in the Pentaho Rest APIs.

Note: If you are on Pentaho version 8.0 or earlier, as a best practice to avoid errors when exporting and importing repository contents, select specific content and not the entire repository. For more information, see Importing and exporting PDI content with Pentaho 8.0 and earlierarrow-up-right.

The backup process exports all content from the Pentaho Repository and creates a ZIP file, which includes:

  • Users and roles

  • All files (dashboards, reports, etc.)

  • Schedules

  • Data connections

  • Mondrian schemas

  • Metadata entries

  • A manifest file

All of your content is pulled from this ZIP file when you restore the Pentaho Repository.

You must have appropriate administrator permissions on the server in order to perform a repository backup or restore.

Step 1: Backup the Pentaho Repository

Backing up your Pentaho Repository is done through the use of command line arguments. You can customize the provided examples for your server.

If an argument is required for successful backup and has not been provided, the missing requirement is displayed in the cmd window. Backup results are also displayed in the window.

  1. Open a cmd window and point the directory to the install location of your running Pentaho Server.

  2. Use the import-export script with your arguments for backing up the repository.

  3. Press Enter.

For example,

  • Windows

    import-export.bat --backup --url=http://localhost:8080/pentaho --username=admin --password=password --file-path=c:/home/Downloads/backup.zip --logfile=c:/temp/logfile.log --logLevel=DEBUG

  • Linux

    ./import-export.sh --backup --url=http://localhost:8080/pentaho --username=admin --password=password --file-path=/home/Downloads/backup.zip --logfile=/temp/logfile.log

Step 2: Restore the Pentaho Repository

Restoring your Pentaho Repository is also done through the use of command line arguments. The process for restoring both repositories is similar to the backup process, except for the differences shown in the provided examples. These examples can be customized for your particular server.

If an argument is required for successful restore and has not been provided, the missing requirement is displayed in the cmd window. Restore results are also displayed in the window.

  1. Open a cmd window and point the directory to the install location of your running Pentaho Server.

  2. Use the import-export script with your arguments for backing up the repository.

  3. Press Enter.

For example,

  • Windows

    import-export.bat --restore --url=http://localhost:8080/pentaho --username=admin --password=password --file-path=c:/home/Downloads/backup.zip --overwrite=true --logfile=c:/temp/logfile.log --logLevel=DEBUG

  • Linux

    ./import-export.sh --restore --url=http://localhost:8080/pentaho --username=admin --password=password --file-path=/home/Downloads/backup.zip --overwrite=true --logfile=/temp/logfile.log

hashtag
Localize folders and reports

You can localize the names and descriptions for reports and folders that appear in the User Console. Localization is helpful if your co-workers work in different countries and speak different languages, but use the console to access the same reports and folders. For example, localization allows German speakers to view report names in German and Americans to view the same report names in English.

Note: Localization language packs have been created through a community initiative that uses an installer built by Webdetails, a Pentaho company. The language packs apply to both EE and CE, and are maintained by community members. The packs are not officially supported by Pentaho.

Localization information is stored in the Pentaho Repository, along with other report and folder information. Typically, to localize names and descriptions of reports and folders you do three things:

  1. Download the report or folder from the Pentaho Repository. Localization information is stored in one or more text files that have the .locale extension.

  2. Add or edit the localization files downloaded with the reports or folders.

  3. Re-upload the report or folder, along with the localization files, into the Pentaho Repository.

hashtag
Localization file structure

When you download a report or folder from the Pentaho Repository, localization information is stored in a text file that has a .locale extension. You add or edit localization files, but must upload them to the Pentaho Repository for the changes to appear in the User Console.

Each report and folder that appears in the console should have a default localization file associated with it. The default localization file should indicate the name that appears when you view the name of the report or folder in the console. Optionally, the localization file can contain the report description. The report description appears when you hover the mouse pointer over the report or folder name in the console.

If multiple localization files are present, the User Console displays the localization information contained in them if you set the language indicated in the localization file as the default in the console or in your web browser. Otherwise, the information in the default localization file is displayed instead.

Localization information appears in two places in a localization file: in the file name and in variables inside the file.

Localization file names

Localization file names consist of several parts that are joined by underscores. This is an example of a localization file name for a folder: index_es_PA.locale

In folder localization, file names the word index appears first, as in the previous example. If the localization file is for a report, the name of the report appears instead of index, like this: Inventory Report_es_PA.prpt.locale

The second and third parts of the file name indicate the two-letter language code and the two-letter country code. Language codes adhere to ISO 639-1; country codes can be found in ISO-3166. In the previous example, es is the language code for Spanish and PA is the country code for Panama. A list of often-used language and country codes appears here.

Although rarely used, the dialect code can appear after the country code.

File extensions, which appear after the period, indicate the report type and end with: .locale In the previous example prpt indicates the report type.

Language, country, and dialect codes are optional parts of file names. The report type extension should not be included in folder localization file names. Only the report name (or the word index for folders) is required as is the .locale extension. But, if a country code is present, the language code must also be present, and if a dialect code is present, both the language and country codes must be present.

If a localization file name contains no language, country, or dialect code, the console assumes that the file is the default for a report or folder. A default localization file name for a folder looks like this: index.locale

Localization variables

Localization files have at least two variables that contain localization information.

  • file.title holds the name of the report or folder that appears in the User Console.

  • file.description holds the text for the Tool Tip that appears when you hover the mouse pointer over the report or folder name in the User Console.

Here is an example of a localization file for a report.

Note: In localization .properties files, file.name and file.url-name are sometimes used instead of file.title and url-description is sometimes used instead of the file.description variable.

Before variable values set in the localization file can be displayed, you must adjust either the User Console or your web browser’s language so that it matches the localization file’s language. You must also upload the localization file into the Pentaho Repository along with the other report files.

Using the previous example, the User Console displays the value of file.title (Inventario Region 23) when you open it. If you hover the mouse pointer over the report name in the console, a Tool Tip appears that displays the value of file.description (Lista del inventario de la region 23).

Note: Unicode can be used to display non-Latin languages, such as Chinese or Japanese.

Popularly used country and location codes

Language and country codes that are used to construct localization file names appear in standards ISO 639-1 and ISO 3166. Here is a list of popularly used language and country codes.

Lanuage
Language Code
Country
Country Code

Chinese

zh

China

CN

Dutch

nl

Netherlands

NL

French

fr

France

FR

German

de

Germany

DE

Italian

it

Italy

IT

Japanese

ja

Japan

JP

Korean

ko

Republic of Korea

KR

Portuguese

pt

Brazil

BR

Portuguese

pt

Portugal

PT

Spanish

es

Argentina

AR

Spanish

es

Spain

ES

hashtag
Set default localization for reports and folders

Complete these steps if you want to set up default localization information.

  1. Download the report or folder to which you want to add localization information.

    Instructions for how to do this appear in Download folders and files.

  2. Unzip the downloaded report or folder, then determine whether a default localization file already exists.

    Localization files have a .local extension and are named either index.locale (for folders) or <report name>.<report type>.locale for reports. If a default localization file exists you do not need to continue with these steps.

  3. To add new localization information, you must create a default localization file. Localization file names follow very specific naming conventions. To determine the name of the new localization file, do this.

    1. For folders, the default localization file name convention is: index.locale

    2. For reports, the default localization file name convention is: <report name>.<report type>.locale

      An example of a valid file name is: Inventory Report.prpt.locale

  4. Use a text editor to create a blank localization file that has the file name you constructed in the previous step, then save the file in the directory of the folder or report.

  5. Type the following in the blank file:

  6. Type the name of the report or folder that you want to appear in the User Console after the file.title= variable.

    Type the name of the report or folder exactly as you want it to appear.

    file.title=Inventario

  7. Type the description for the report or folder after the file.description variable.

    The value of the file.description= appears when you hover the mouse pointer over the report or folder name in the User Console. Type the description exactly as you want it to appear.

    file.description=Inventario para El Rey

  8. Save and close the file.

  9. Upload the localization file along with other report or folder files into the Pentaho Repository.

    Instructions for how to do this appear in Upload folders and files.

hashtag
Localize for additional languages

Complete these steps if you want to display report and folder names and descriptions in a language other than the default. If you want to change the default language displayed only, we recommend that you edit the default locale file.

  1. Download the report or folder to which you want to add localization information.

    Instructions for how to do this appear in Download folders and files.

  2. Unzip the downloaded report or folder.

  3. To add new localization information, you must create a new localization file.

    Localization file names follow very specific naming conventions. You can optionally specify country and language codes, as well as the report type. To determine the name of the new localization file, do this.

    1. For folders, the localization file name convention is: index_<language code>_<country code>.locale

      An example of a valid file name is: index_es_PA.locale

      Note: Language and country codes are optional.

    2. For reports, the localization file name convention is: <report name>_<language code>_<country code>.<report type>.locale

      An example of a valid file name is: Inventory Report_es_PA.prpt.locale

      Note: Language and country codes are optional.

  4. Use a text editor to create a blank localization file that has the file name you constructed in the previous step, then save the file in the directory of the folder or report.

  5. Type the following in the blank file.

  6. Type the name of the report or folder that you want to appear in the User Console after the file.title= variable.

    Type the name of the report or folder exactly as you want it to appear.

    file.title=Inventario

  7. Type the description for the report or folder after the file.description variable.

    The value of the file.description= appears when you hover the mouse pointer over the report or folder name in the User Console. Type the description exactly as you want it to appear.

    file.description=Inventario para El Rey

  8. Save and close the file.

  9. Upload the localization file along with other report or folder files into the Pentaho Repository.

    Instructions for how to do this appear in Upload folders and files.

hashtag
Edit existing localization information

Complete these steps if you want to edit localization information for report and folder names and descriptions that appear in the User Console.

  1. Download the report or folder for which you want to edit localization information.

    Instructions for how to do this appear in Download folders and files.

  2. Unzip the downloaded report or folder.

  3. Use a text editor to open the localization file you want to modify.

    Localization files have the .local extension. Localization files for folders begin with the word: index Localization files for reports begin with the report name.

  4. To change the report or folder name that appears in the User Console, edit the file.title= variable.

    file.title=Inventario

  5. To change the report or folder description Tool Tip that appears when you hover the mouse pointer over the report or folder name in the User Console, edit the value of the file.description= variable.

    file.description=Inventario para El Rey

  6. Save and close the file.

  7. Re-upload the localization file, along with the other report or folder files, into the Pentaho Repository.

    Instructions for how to do this appear in Upload folders and files.

PreviousAdminister Pentaho Data Integration and Analytics 11.0NextSecure the Pentaho system

Last updated

Was this helpful?