Access session and environment variables in a PRPT

Reports need to interact with the outside world in many ways. To formalize this, we allow to pass values from the outside to the inside. Pentaho Reporting knows several classes of inputs:

• Environment variables
• Parameter: User supplied values usually coming from an interaction of the user with a user interface
• DataRow-Fields: part of the result-sets from the data-sources
• Expressions and Functions: Calculated values

Today, we will talk about environment variables. Environment variables are system level parameter. You can use them to configure reports based on where you deploy the report.

We provide several properties for use within the Pentaho BI-Server.

• serverBaseURL: the server URL, for example: "http://localhost:8080"
• pentahoBaseURL: the location of the Pentaho Web-application: "http://localhost:8080/pentaho"
• solutionRoot: The file-system location where the local copy of the solution repository can be found.
• requestContextPath: the servlet's request context path pointing to the local web-application: "/pentaho/"
• username: The current user's name
• roles: The roles as CSV-encoded list. The CSV string is quoted according to the Excel CSV quoting rules.

Inside the BI-Server, environment variables can also be used to interact with the server's environment to query session and global parameter information. The report environment allows you to access values stored on the current user's session or as global parameter by using a special prefix.

Requesting a environment property "session:name" will query the session context for an entry called "name" and returns the string representation of this object to the report.

Likewise, prefixing a environment property with "global:" will query the global parameter collection of the BI-Server. Therefore querying a environment variable "global:name" will look for a entry "name" in the Bi-Server's global parameters.

Accessing Environment variables with Formulas

The Pentaho Reporting Engine offers the formula function "ENV" to access the report environment properties.

Definition:

=ENV(String)

To access the variable called "example" as plain text, use

=ENV("example")

To access a value bound to the server-side session variable "example" use

=ENV("session:example")

If the variable is a CSV encoded string, you can use the CSVARRAY function to parse the string into a array of strings. This array is then suitable to use for multi-selection parameters or SQL-IN clauses.

=CSVARRAY(ENV("roles"))

You can now use these variables as part of other formulas, for instance to compute URLs pointing to documents on the server server.

=ENV("serverBaseURL") & "/myotherwebapp/downloads/pentaho-report-designer.zip"

Accessing Environment variables as predefined fields

When you open up the Pentaho Report Designer, you will see several of the well-known environment variables listed as fields on the report itself. Using the ENV function is flexible, but not very convenient. So we added a automatic mapping to the reporting engine.

The various env:* fields you see in a report are what I call "well-known" fields. As Pentaho Engineers we know knows that they exist on the server and are heavily used by our users. So we added a mapping to the system so that they automatically become fields without having to use a formula function to read their values.

The list of "well-known" fields is defined in the global report configuration. The global configuration can be edited by creating or editing a file called "classic-engine.properties" inside your Pentaho Report Designer and Pentaho BI-Server directories.

Inside the Pentaho Report Designer, this file resides in the "resources" directory in your Pentaho Report Designer installation directory. For the BI-Server you can find this file in the "pentaho/WEB-INF/classes" directory. To make your reports work consistently inside the Report Designer and the Server, make sure that both files have matching definitions.

For example: If you want to map your environment-property "value" into the field "env::value" then you would add the following line to your "classic-engine.properties" file:

org.pentaho.reporting.engine.classic.core.env-mapping.value=env\:\:value

In case value contains a comma separated list (using the Excel-CSV quoting rules for strings that need to be quoted), then you can make that list available as array by appending -array to its name.

org.pentaho.reporting.engine.classic.core.env-mapping.value-array=env\:\:value-array

The engine will recognize the "-array" suffix and will look for a "value" property instead, parses that into a string-array and returns you the array. The array then can be used in a SQL-IN clause.

The prefix "env::" is a convention inside the reporting engine to separate environment fields from other fields. If you omit this, you have to make sure that none of the fields returned by your data sources and none of your expressions or functions provide a value under the same name. This would overshadow your environment property and renders it inaccessible.