01.

Applying Concepts and Properties in the Pentaho

Metadata Editor
04. Enriching Your Data - Understanding
Metadata Concepts and Properties

02. Metadata Properties Reference

As explained previously, there are three levels of concepts for the business objects in the business model, which provides great power and
flexibility in how you define your metadata. Since one of the levels is an inherited level, there are really only two concept application processes
you need to learn to work with - applying self concepts, and applying parent concepts.

Applying Self Concepts: Managing Properties on the Model

You may have noticed when you were creating your tables and columns, that the properties dialog for every business object had two additional
lists to the right of the Subject list. I intentionally skipped these earlier, as they are related to concept editing, which we are just now broaching.
The two additional lists are the Properties list, and the Property Editor application, and they operate the same no matter what object you are
applying metadata to.

The properties shown in the screenshot above are for a business table, and we will use the business table as a reference here.

The Properties List

The middle panel in the properties dialog is the Properties List. This is the list of currently applied metadata properties for the object that is
selected in the Subject list. The properties are sorted into their appropriate categories for organization.
At the top of the Properties List, you will notice two icons. The icon with the plus sign
is for adding new metadata properties to this business
table's self concept, and the icon with the red stop sign is for removing properties from the self concept. Note that the remove button is disabled
until a property is selected in the Property List.

Helpful Icon Color Coding

There are four ways a property can show up in the Property List:
1.
2.
3.
4.

The property is a default property for the associated business object, and thus cannot be removed.
The property was inherited from the business object's physical ancestor.
The property has been set as part of the self concept.
The proeprty has been set as part of the object's parent concept.

It is difficult/confusing to set properties without understanding the override hierarchy, so to help make the hierarchy a bit more
apparent in the Properties List, we color code the properties to alert you to what concept level is in play.
Yellow Icon = This property is inherited from the object's physical ancestor.
Blue Icon = We have set the property on the object's own concept. This could be overriding an inherited property.
Orange Icon = This property is set as a result of the parent concept applied to the object.
Purple Icon = This is a special icon resserved for security properties.

The Properties Editor

The Properties Editor shows the property name, and the associated value for that property in a scrolling list. The properties show up in the
Properties Editor in the same order they appear in the Properties list. If you click on a property in the Property List, the Property Editor will scroll to
find it in the editor.
In the Properties Editor, you can set or modify the values of the properties applied to the business object.

Under Construction
Note that the properties dialogs today work as a single transaction - you either accept all changes when you click OK, or roll
back all changes if you click Cancel. Therefore, there is no reset or undo that will take you partially out of a set of changes. We
have plans to make this dialog a bit friendlier than that in the future.

There are also icons in the upper right corner next to any property that is override-able. If you want to modify a property by overriding its inherited
value, you must first click the override button. And to stop overriding, you click the override button once again.

Adding New Properties

To add a new property to a business object, first make sure that the object you want to apply the new property to is selected in the Subject list.
1. Click the plus sign
above the Properties List.
2. You will be prompted with the list of property choices to apply.
3. Select one property, click OK, and the property is now available for you to modify in the Property Editor.

Removing Properties
To remove a property from the Property List:
1. Select the property you wish to remove.
2. Click the red stop sign above the Properties List.
Note that you can only remove overrides and self concept properties for the selected object. If you want to remove inherited or parent concept
properties, you need to edit the inherited business object, or the parent concept.

Applying Parent Concepts: Introducing the Concept Editor

Parent concepts are independent hierarchies of concpets that can be assigned to one or more business objects via the Tree Navigator. Before we
can assign a parent concept we must first learn how to create one.

Introducing the Concept Editor

The Concept Editor is an editor in the Pentaho Metadata Editor that facilitates building concepts to be used as parent concepts.
The ability to isolate the concepts, name them, then associate the named concept with one or more business objects gives us
flexibility and very good concept management.
Another feature of the Concept Editor is that we can define concepts that build upon other concepts. By nesting concepts this
way, we have minimized the number of properties you repeatly define, and create a nice inheritance hierarchy.

The Default Concept

Unknown macro: {multi-excerpt}
Every model includes a default concept called Base. This concept is applied as the parent concept to all physical columns created under a
connection. The default concept includes metadata properties that are commonly defined, and sets a base line set of metadata for all physical
columns in the metadata model. The purpose of the default concept is to provide legitimate values for common metadata properties that may not
be set in other places in your hierarchy.
You can update, add and delete metadata properties on the default concept, just like you can in any other concept. You can also remove the
default concept as the parent concept for any and all physical columns. You can not, however, delete the default concept from the list of concepts
in the Concept Editor.
Here's what the default concept Base looks like today:

Building Concepts
Building nested concept trees may take a bit more explanation, best done with an example walkthrough of the Concept Editor.
1. From the main menu's Tools menu, select the Concept Editor.
2.
3.
4.
5.
6.

With the Base concept selected in the Concepts List*, click the plus sign
to add a new, nested concept. Name this concept Number.
Make sure Number is selected in the Concepts List. Note that the properties from Base has been inherited by Number.
Add a Mask property to Number, with a value of $###,##0.00.
With Number selected in the Concept List, add another nested concept named ID.
Select ID in the Concepts List, find the inherited Mask property and click the Override button. Enter an override value of 0 for the mask.

Notice how we now have three defined concepts that can be used anywhere in our business model. Each concept serves a different type
of business object - Base for default, generic columns, Number for those columns we know contain numeric financial data, and ID for ID
columns.
Click OK to save your new concepts.

Applying Concepts to Your Business Objects

Now that you have some defined concepts, let's set a few as parent concepts in our business model.
1. Select any physical table in the Tree Navigator. I will use the Customers physical table as an example.
2. Expand the columns under the table in Tree Navigator. Select the column you want to apply the concept to. I am going to apply our ID
concept to the column Customernumber.
3. Right-click (or CTRL-click) on the column, and select the Set Parent Concept option from the popup menu.
4. A list of concepts will display. I am going to choose the ID concept and click OK.
5. You should see the concept in the right hand column of the Tree Navigator on all objects that it is applied to (remember, inherited
concepts will show up on all of the inherit-ees

).

Now, when the column Customernumber is used in a metadata-aware application, it will provide a font of Verdana, and default numeric
format of 0 - no decimals, no commas.

Clearing the Parent Concept

To remove a parent concept from an object in the business model, you clear the parent concept.
1. Select any physical table in the Tree Navigator.
2. Expand the columns under the table in Tree Navigator. Select the column you want to remove the concept from.
3. Right-click (or CTRL-click) on the column, and select the Clear Parent Concept option from the popup menu.
This removes the parent concept and its metadata properties from the object.

TODO

01. Metadata Concepts Technical Overview

Concepts
PME uses the term "concept." A concept is a collection of properties. A "property" has an identifier (a key into a map actually) and a value. In the
diagram below, a concept is depicted as a box containing simple, colored shapes. Each shape depicts an identifier and its color depicts a value. A
green square in one concept and a purple square in another concept represent the same identifier but with different values.
Concepts

Inheritance
PME uses object inheritance to maximize re-use of metadata definitions. As you will see, inheritance is used in multiple ways within the PME
allowing for powerful re-use. However that re-use comes at the cost of complexity. For example, if one concept has an ancestor, it can be difficult
to identify where a property in the descendant concept came from, since the property could have come from the descendant concept, its parent,
the parent concept's parent, etc.
In the diagram below, the parent-child concept relationship is shown. A child concept inherits the properties of its parent while still being able to
either override the value of the parent properties or add additional properties of its own.

Inheritance

The next diagram is the same as above but with each property further classified.

Inheritance

PME defines "subjects." Subjects are objects that have exactly one associated concept. Examples are physical tables and business columns. In
the diagram below, new objects are introduced. Every concept can have a security parent object. A security parent only contributes a security
property--nothing else. Note also the default properties. Default properties are coded into PME and are not true concepts. Finally, a subject is
introduced. Notice how the subject wraps the concept, and the concept wraps the properties. You can always ask a subject for its concept and
ask the returned concept what its ancestors are.

Inheritance

The final diagram shows a complete relationship--one where a concept gets its properties from (1) a parent concept, (2) an inherited concept, (3)
default properties, and (4) child properties. Let's look at each:
1.
2.
3.
4.

The parent of the concept within Subject N is Concept C.

The inherited concept of the concept within Subject N is the concept with Subject M.
The default property of subjects of type Y is a circle (with a default value of orange).
The security parent concept of the concept with Subject N is Security Concept G.

The list below is the precedence

1.
2.
3.
4.

Child (overrides all)

Security (overrides parent and inherited)
Parent (overrides inherited)
Inherited

Inheritance

01. Setting Up Your Database Connections

03. Building a Pentaho Metadata Domain

02. Importing Physical Tables and Columns

Connections
The Pentaho Metadata Editor (and the Pentaho metadata architecture) supports a vast and rich set of data sources. Before you begin defining
your [business model], you must first describe the database or data source that you would like to model. You do this by defining one or more
[connections] in the editor.

One Connection Per Business Model

While the current implementation of metadata supports multiple connections and multiple business models in the same domain,
each business model can use physical objects (columns and tables) from only a single connection. We hope to expand this
functionality so one model can use two or more connections' tables and columns, but for now, it's important to understand this
limitation.

Creating a New Connection

To create a new connection:
1. Right-click (or CTRL-click) on the Connections branch of the Tree Navigator on the left side of the editor screen.
2. Select the New Connection... option from the popup menu.
3. The Connection Information dialog will be displayed. This dialog allows you a rich set of options for defining your database connection in
detail.

The Connection Information Dialog

This dialog deserves a bit of explanation before we continue.

Connection Types
First, note the Connection Type list on the General tab of the dialog. This is the list of database connections that the Pentaho Metadata Editor
and metadata models can support. The list is quite extensive. If you do not see your database in the Connection Type list, you may be able to add
it. To add a new database type, you will have to copy the JDBC driver archive for your database into the [studio:PME install directory]/libext/JDBC
directory. Restart the Pentaho Metadata Editor, and you will see your database in the Connection Type list.

Method of Access
Under Connection Type, you will see the Method of Access list. Defining a JDBC or OBDC connection typically requires all of the remaining
fields on the general tab have the correct information. But if you are into abstracting those details from your metadata domain, then using the
JNDI method of access is for you. The JNDI access method keeps your server implementation cleaner as well; once you publish your domain to
the server, as long as you have defined the JNDI connections with the same names, you still have a nice implementation where your database
information is only described to the JNDI layer.
To take advantage of the JNDI method of access in the Pentaho Metadata Editor, you will need to define your database connection information in
a properties file for the editor. We walk through a JNDI connection studio:later in this page.

An Example Connection: A JDBC Connection to a MySQL Database

This example uses the Steels Wheels sample data provided with the Pentaho Open BI Suite (aka the "pre-configured installation" or "PCI"),
available from our downloads site.
To connect to a MySQL database using JDBC:
1.
2.
3.
4.
5.
6.
7.
8.
9.

Name your connection. For this example, we will name this connection MySQLSampleData .
Select MySQL as the connection type.
Select Native(JDBC) as the access method.
Enter localhost as the server host name. This assumes you have a local Pentaho BI Server running. If your server (or your sample
database) is hosted elsewhere, enter the name of that host here instead.
Enter the name of the database, in our example, sampledata.
Our example requires the default port for MySQL. Adjust the port as necessary for your setup.
And last, the username and password for the Steel Wheels sample data is pentaho_user, password, respectively.
You should now click the Test button at the bottom of the dialog. If all the information is entered properly, you should receive a "Test OK"
message. If something is wrong, you should receive a message that is specific enough to help you determine the problem.
Click OK when you are satisfied with your connection information.

An Example Connection: A JNDI Connection to a Hypersonic Database

Our second example starts out much like the first, but requires a few different steps.
1.
2.
3.
4.

Name your connection. For this example, we will name this connection HySampleData .
Select Hypersonic as the connection type.
Select JNDI as the access method.
Once you've selected JNDI, notice that the only remaining piece of information that you need to enter on the General tab is the database
name. Enter SampleData here.

This name is actually the JNDI name that you will specify to map to the JNDI connection properties. In order for the Pentaho Metadata Editor to
know what this name really means, you need to set up a simple JNDI properties file.
1. Navigate to [studio:PME install directory]/simple-jndi/jdbc.properties file. Open this file in your favorite text editor.
2. Enter the following text into the jdbc.properties file:
SampleData/type=javax.sql.DataSource
SampleData/driver=org.hsqldb.jdbcDriver
SampleData/url=jdbc:hsqldb:hsql://localhost/sampledata
SampleData/user=pentaho_user
SampleData/password=password
3. Save the file and close it.
4. Go back to the Connection Information dialog, and click the Test button. If all goes well, you should get a "Test OK" message. If not try
saving your connection, exiting the Pentaho Metadata Editor, restarting the editor and trying the Test button again.

More on the Connection Information Dialog

See the studio:Database Connection Guide for more information about this dialog.

TODO

02. Importing Physical Tables and Columns

01. Setting Up Your Database Connections

03. Building a Pentaho Metadata Domain

03. Creating a Business Model

Now that we have a few database connections (see [Setting Up Your Database Connections]), the next step is to describe the physical database
tables and columns that we will want to include in our [business model].

Importing Physical Tables

Fortunately, when you import a physical table, all of the table's columns come with it, so the import is a one step exercise instead of two. You can
later remove those columns that you do not want in the connection or the model.

An Example Import: Importing Tables into a MySQL Connection

1. Right-click (or <CTRl+click>) on the MySQLSampleData node in the Tree Navigator. Select the Import Tables... option from the pop-up
menu.
2. You will be prompted by a dialog with list of physical tables available in the database. Select the tables you want to include, and click OK.

Drill down on your physical tables in the Tree Navigator. Notice that all of the physical columns have been imported with each table.

Trimming the Physical Columns

If you would like to remove extraneous columns from your physical tables, from here it's easy to do:
1. Right-click (or <CTRl+click>) on the physical table node you wish to edit in the Tree Navigator. Select the Edit option from the popup
menu. (Note: you can also get to the Physical Table Properties dialog by double-clicking the physical table node.)
2. The Physical Table Properties dialog displays. In the dialog's Tree Navigator, select a column you wish to remove.
3. Click the delete icon (the one with the red circle), to the right of the word Subject above the dialog's Tree Navigator.
4. Repeat with any remaining columns that you want to remove. Click OK when you are done.

Defining the Physical Column Aggregations

Note: This functionality will not be available until the CITRUS release (date pending).
You are no longer limited to defining only one aggregation rule in a model. You can define multiple aggregation rules from which users can
choose when they are working in the Chart Designer or other tool.
Note: This feature will not be supported for users of Ad Hoc Reporting.
In the example below, the model designer has designated three optional aggregations for PRICEEACH: Sum, Average, and Count. In the Chart
Designer, (or other tool), users can decide whether they want to see the total price, average price, or the number of prices available. Metatada
Editor displays a default aggregation type for a numeric column. You can choose to designate additional aggregations, when applicable.

To define aggregations in Metadata Editor...

1.
2.
3.
4.

Select the column for which an aggregation must be defined.

Under Model Descriptors, select Default Aggregation.
Under Aggregation rule, select an Aggregation Type from the list.
If applicable, select multiple aggregation types from the Optional Aggregations. Use <CTRL+click> to make your selections.
Note: There is no need to explicitly place the aggregation type in the formula definition; Metadata Editor uses your selections to
generate the SQL query. See Second Use: Physical Table Column Formulas and Support for Multiple Aggregate Types for more
information.

02. Metadata Properties Reference

01. Applying Concepts and Properties in the
Pentaho Metadata Editor

04. Enriching Your Data - Understanding

Metadata Concepts and Properties

Out-of-the-Box Properties
The table below shows the properties that are provided with Pentaho Metadata Editor.
Unknown macro: {table-plus}
Id

Description

Category

Values

Name *

This property describes the display name for the business object.

General

Alphanumeric

Description

A descriptive text entry describing the business object.

General

Alphanumeric

Additional comments regarding the business object.

General

Alphanumeric

Security
Information

Security rules for granting/restricting access to the business object.

General

Determined by
security widget; see
Adding Security.

Font

The font properties to apply to this business object.

Formatting

Determined by font
dialog

Color of
Text

The foreground or text color for the business object.

Formatting

Determined by color
dialog

Text
Alignment

The text alignment for the business object.

Formatting

( Left | Right |
Centered | Justified )

Color of
Background

The background color for the business object.

Formatting

Determined by color
dialog

Relative
Size

This property is normally associated with business tables and is used to calculate join
paths. The sum of all table relative sizes in a path are calculated when deciding on a
multi-table join, and the multi-table join with the smallest summed value is used for the
join path.

Formatting

Numeric

Aggregation
Rule

Determines the method of aggregating the data from this business object.

Model
Descriptors

( None | Sum | Count |

Distinct Count |
Minimum | Maximum )

Data Type

Data type for this business object.

Model
Descriptors

( Unknown | String |
Date | Boolean |
Numeric | Binary |
Image | URL ) +
Length and Precision
(Integers)

Field Type

What type or relationship purpose this field serves.

Model
Descriptors

( Other | Dimension |
Fact | Key | Attribute )

Table Type

Table type is used to automatically determine relationship types with other tables. For
instance, if a Fact table is joined with a Dimension table, this is normally an N to 1
relationship

Model
Descriptors

( Other | Dimension |
Fact )

Formula

This property allows you to create a calculation defining the business object. See
Pentaho Metadata Formulas for more information.

Calculation

Alphanumeric

Is the
Formula
Exact?

Determines whether the formula should be parsed as a Metadata Formula. If false, this
field is treated as a database column name .

Calculation

Boolean

Comments
*

Column
Width

The width of the column as represented for display.

Miscellaneous

( Pixels | Percent of
Page Width | Inches |
Centimeters | Points )
+ Integer

Hidden For
the User?

This hides the object from being displayed in the Business View of the model.

Miscellaneous

Boolean

Mask for
Number or
Date

The format mask that should be used when the data for this object is displayed. For
dates, the format follows the date/time patterns for a Java SimpleDateFormat format
mask. For numbers, the pattern should follow the Java DecimalFormat format mask.

Miscellaneous

Alphanumeric

Target
Schema

This property defines the database schema to use when querying the business object.

Miscellaneous

Alphanumeric

Target
Table

This property defines the physical database table from which the business object is
defined.

Miscellaneous

Alphanumeric

Localized properties.

Custom Properties
You can define any number of custom properties. You must give your property an id and set its type.
The available types are:
String
Date
Numeric Value
Color
Font
Type of Field
Type of Aggregation
Boolean
Field Data Type
Localized String
Type of Table
URL
Security
Text Alignment
Column Width

Required Properties per Business Object

The table below shows required properties for given business objects. Required properties cannot be deleted.
Unknown macro: {table-plus}
Id
Name
Description
Security Information
Table Type
Relative Size
Formula
Field Type
Data Type

PhysicalTable

PhysicalColumn

BusinessCategory

BusinessModel

Aggregation rule
Is the Formula Exact?
Hidden for the User?
Font
Mask for Number or Date
Color of Text
Color of Background

TODO

02. Pentaho Metadata Formulas

Formula Overview
Formulas have multiple uses in Pentaho Metadata.
The first use of formulas within Pentaho Metadata is in the constraint definition of a Metadata Query, also known as MQL. A constraint function
references business table columns and uses various comparison operators to determine which subset of data the business user is interested in.
The second use is in the definition of Physical Table Columns. In addition to Physical table columns mapping directly to a database table column,
physical table columns defined in Pentaho Metadata may also be defined as a formula. This allows for combining of multiple columns into a single
column, and also for doing more advanced aggregate calculations within aggregate table definitions.
The third use is in the definition of complex joins within business model relationships. This allows for multiple key joins as well as other logic
when joining tables.
The fourth use is row level security.
Under the covers, Pentaho Metadata uses JFreeReport's libFormula package for interpreting formulas. The goal is to support OpenFormula
syntax within the Metadata environment. Formulas are first interpreted by libFormula, and then within the Metadata system are converted to
native SQL depending on the type of database used.

First Use: MQL Constraints

Here is an example of an MQL Constraint formula:
OR([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME] = "EuroCars"; (([BT_CUSTOMERS.BC_CUSTOMERS_CREDITLIMIT] *
2) / 3 > 1000))

We'll walk through this example to help explain the core components of MQL formulas. First note the OR function. This is a boolean function
which has two parameters, separated by semi-colons. These parameters are boolean expressions.
The first boolean expression first references a business column from our Metadata model. All references appear with brackets around them [].
This reference first refers to the business table, and then to the business column. This boolean expression first does some arithmetic and checks
to see if the final value us larger than 1000.
In the second expression, we compare the business column BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME to EuroCars. Note that
we use double quotes when referring to text. Double quotes are required.

Second Use: Physical Table Column Formulas

Here is an example of a Physical Table Column Formula:
[QUANTITYORDERED]*[PRICEEACH]

The references here specifically refer to the database column, not derived physical column definitions. All operators and functions may be used in
the definition of the physical table column. One special note, in order for this formula to be recognized, the "isExact" property of the physical table
column must be set to true. Also note, the referenced physical column must be explicitly defined in the metadata model.

Recent Changes to Physical Table Column Formulas

In earlier versions of Pentaho Metadata Editor, (prior to the CITRUS release), aggregation functions had to be specified explicitly and the
aggregation rule had to be selected. This is no longer necessary; the query that is generated will use the selected aggregation rule during
execution. See Defining the Physical Column Aggregations for more information.

Multi-table expressions: Formulas can use any business column in the model
Since the latest versions (after 2008/03/14) it is possible to define formulas that use business columns from anywhere in the business model.

For example suppose we have two business tables:

Orders (fact table), ID=BT_ORDER_FACT
Product (dimension), ID=BT_PRODUCT
Suppose we want to calculate the turnover based on:
the number of products sold, from the Orders table, ID=BC_FACT_ORDER_NRPRODUCTS
the price of the product, from the Product table, ID=BC_DIM_PRODUCT_PRICE
To arrive there, we define a new business column, say in the Orders business table (although you could take Product too):
Table: Orders (BT_ORDER_FACT)
ID = BC_FACT_ORDER_TURNOVER
Name = Turnover
Formula = [BT_ORDER_FACT.BC_FACT_ORDER_NRPRODUCTS] * [BT_PRODUCT.BC_DIM_PRODUCT_PRICE]
Exact = Yes
Aggregation Rule = SUM
The SQL generator is now going to replace the 2 business columns by their respective SQL variants. As such, we have to make sure that the
business columns on which we base ourselves are resolving correctly. In this specific case, this means we want the 2 columns to be
non-aggregated. If we now select the single business column BT_FACT_ORDER_TURNOVER, this is the SQL that is generated:
SELECT
SUM( BT_ORDER_FACT.NRPRODUCTS

BT_PRODUCT.PRICE ) AS COL0

FROM
FACT_ORDER BT_ORDER_FACT
,DIM_PRODUCT BT_PRODUCT
WHERE
( BT_ORDER_FACT.PRODUCT_TK = BT_PRODUCT.PRODUCT_TK )

Now, suppose we want to generate the multiplication of the 2 sums (different use-case), we define the formula as
"[BT_ORDER_FACT.BC_FACT_ORDER_NRPRODUCTS] * [BT_PRODUCT.BC_DIM_PRODUCT_PRICE]" (without the SUM) and specify an
aggregation for the 2 used business columns. The generated SQL will then be:
SELECT
SUM( BT_ORDER_FACT.NRPRODUCTS )

SUM( BT_PRODUCT.PRICE ) AS COL0

FROM
FACT_ORDER BT_ORDER_FACT
,DIM_PRODUCT BT_PRODUCT
WHERE
( BT_ORDER_FACT.PRODUCT_TK = BT_PRODUCT.PRODUCT_TK )

It is obviously possible to create 2 versions of the used business columns, one aggregated (exposed to the users) and one non-aggregated
(hidden from the users) for example.
The SQL generator works recursively. That means that it is possible to create a formula that calculates 7% (taxes for example) of the turnover:
ID = BC_FACT_ORDER_TURNOVER_TAXES
Name = Turnover Taxes
Formula = [BT_ORDER_FACT.BC_FACT_ORDER_TURNOVER] * 7 / 100
Exact = Yes
If we add that column to the selection, we get one extra column like this:
(

SUM( BT_ORDER_FACT.NRPRODUCTS

Appendix
Formula Syntax
Function syntax

BT_PRODUCT.PRICE )

* 7 / 100) AS COL1

FUNCTION_NAME ( PARAM ; PARAM )

Text (requires double quotes)

"TEXT"

Parenthesis are used for formula precedence:

( 1 + 2) * 3

Metadata References
Business Column References:
[<BUSINESS_TABLE_ID>.<BUSINESS_COLUMN_ID>]

Physical Column References (only used in physical column formula definitons):

[<PHYSICAL_COLUMN_NAME>]

MQL Parameter References:

[param:PARAM_NAME]

Supported Functions
Function
Name

Parameters

Description

Example

OR

two or more
boolean
expression
parameters

Returns true if one or more parameters are true

OR(
[BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME] = "E
[BT_CUSTOMERS.BC_CUSTOMERS_CREDITLIMIT] > 1000
)

AND

two or more
boolean
expression
parameters

Returns true if all parameters are true

AND(
[BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME] = "E
[BT_CUSTOMERS.BC_CUSTOMERS_CREDITLIMIT] > 1000
)

LIKE

two parameters

Compares a column to a regular expression, using "%"

as wild cards

LIKE([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME
"%SMITH%")

CONTAINS

two parameters

Determines if a column contains a string.

CONTAINS([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMER
"SMITH")

BEGINSWITH

two parameters

Determines if a column begins with a string.

BEGINSWITH([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOM
"JOE")

ENDSWITH

two parameters

Determines if a column ends with a string.

ENDSWITH([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOME
"SMITH")

IN

two or more
parameters

Checks to see if the first parameter is in the following

list of parameters

IN([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME];
Smith"; "Brian Jones")

NOW

none

The current date

NOW()

DATE

three numeric
parameters,
year, month, and
day

A specified date

DATE(2008;4;15)

DATEVALUE

one text
parameter
"year-month-day"

A specified date

DATEVALUE("2008-04-15")

CASE

two or more
parameters

Evaluates the first, third, etc parameter, and returns the

second, fourth, etc parameter value
if there are an odd number of parameters, the last
parameter is returned if no other parameter evaluates
to true.
Note that when using this function, the formula needs
to be set on a new column, not on the
BT_CUSTOMER.BC_CUSTOMER_CUSTOMERNAME
(using the example to the right)

CASE(
[BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME] = "E
"European Cars";
[BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME] = "A
"Asian Cars";
"Unknown Cars"
)

COALESCE

one or more
parameters

returns the first non null parameter

COALESCE(
[BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERNAME];
[BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERID];
"Customer is Null"
)

DATEMATH

one expression
parameter

returns a date based on an expression. DateMath

Javadoc for full syntax

DATEMATH("0:ME -1:DS") - 00:00:00.000 of the day before the

the current month
DATEMATH("0:MS 0:WE") - 23:59:59.999 the last day of the firs
the month
DATEMATH("0:ME") - 23:59:59.999 of the last day of the curren
DATEMATH("5:Y") - the current month, day and time 5 years in
DATEMATH("5:YS") - 00:00:00.000 of the first day of the years 5
the future

ISNA

one parameter

returns true if the value is null

ISNA([BT_CUSTOMERS.BC_CUSTOMERS_CUSTOMERID])

NULL

none

returns the null value

NULL()

TRUE

none

returns true

TRUE()

FALSE

none

returns false

FALSE()

see below for aggregate functions

Supported Operators
Operator

Description

returns true if two expressions are equal

>

returns true if first expression is larger than the second

<

returns true if first expression is smaller than the second

>=

returns true if first expression is larger than or equal to the second

<=

returns true if first expression is smaller than or equal to the second

<>

returns true if two expressions are not equal

adds two values

subtracts two values

multiplies two values

divides two values

Supported Aggregate Functions

Aggregate functions may only be used in physical column definitions. In more recent versions of metadata editor, these functions are no longer
required. Instead, the query generator uses the Aggregation rule specified by the user.
Function Name

Description

SUM

sums a specific columns values determined by grouping

COUNT

counts a specific columns values determined by grouping

AVG

averages a specific columns values determined by grouping

MIN

selects the minimum column value determined by grouping

MAX

selects the maximum column value determined by grouping

03. Building a Pentaho Metadata Domain

02. Launching the Pentaho Metadata Editor

02. Pentaho Metadata Editor Getting

Started Guide

04. Enriching Your Data - Understanding

Metadata Concepts and Properties

The Pentaho Metadata Domain

A domain is defined as:
Unknown macro: {multi-excerpt-include}

This page gets you started creating your first domain in the Pentaho Metadata Editor. If you are not familiar with the Pentaho metadata
terminology or concepts, you may want to review the metadata model overview and metadata terminology pages.

Creating a New Domain

When you have first launched the Pentaho Metadata Editor, a new domain has been created for you by default. You can immediate begin adding
connections, tables, columns, etc.
If you wish to start fresh with a new domain, select File... | New... | Domain File... from the main menu.

Follow the links below to take the next steps, or read on for more details about domains.
01. Setting Up Your Database Connections
02. Importing Physical Tables and Columns
03. Creating a Business Model
04. Creating Business Tables and Columns
05. Creating Relationships Between Business Tables
06. Building a Business View

Saving Your Domain

Saving a domain results in storing the business models, connections and other metadata you've constructed, into a metadata repository. Pentaho

metadata is stored in a repository in a CWM compliant format.

To save your domain:
1. From the main menu, select File... | Save, or Save As...
2. You will be prompted to enter a name for your domain. Enter a suitable domain name. Since this guide will be demonstrating building a
model for the Pentaho Steel Wheels samples, I will name my domain "Steel Wheels".

3. You should see a few progress messages, and your domain is saved.

Opening a Domain
Once you have created more than one domain, you will want to be able to open a different domain. The Pentaho metadata Editor can have only
one domain active at a time.
To open a previously saved domain:
1. From the main menu, select File... | Open.
2. You will be prompted with the list of domains saved in the metadata repository. Select the name of the domain you wish to open and click
OK.

Deleting a Domain
To delete a previously saved domain from the metadata repository:
1. From the main menu, select File... | Delete Domain.
2. You will be prompted with the list of domains saved in the metadata repository. Select the name of the domain you wish to delete and
click OK.
3. You will be prompted with a dialog to confirm your choice to delete the domain. Click Yes, and the domain will be deleted.

Delete is Permanent
Once you delete a domain, your metadata is gone forever. So exercise caution when using delete!

03. Creating a Business Model

02. Importing Physical Tables and Columns

03. Building a Pentaho Metadata Domain

04. Creating Business Tables and Columns

The [business model] is where the logical mapping of business objects to the physical tables and columns we just set up happens. The model is
also the place where we define the relationships between our business tables, and organize the business view.
As mentioned before, a domain can have multiple business models.

Creating a Business Model

To create your first business model:
1. Right-click (or CTRL-click) the Business Models node in the Tree Navigator. Select New Business Model... option from the popup
menu.
2. The Model Properties dialog displays.
3. At the top of the dialog, there is an ID text field, pre-populated with a value. We recommend you accept the pre-populated value as this
value MUST be unique across all models that you define.
4. To name your new model, enter a new value in the Name property text box on the right.

Click the OK button to close the dialog.

Your business model will show up in the Navigator Tree. All business models by default are created with a place to hold business tables,
relationships and a business view. These are the next items you will want to define.
04. Creating Business Tables and Columns
05. Creating Relationships Between Business Tables
06. Building a Business View

TODO
Priority:

MEDIUM

Assigned To:
Created:

N/A

03. Pentaho Metadata MQL Schema

MQL is the syntax Pentaho Metadata uses for generating SQL queries based off of metadata. Normally a user would generate MQL via
Pentaho's Design Studio or Pentaho's Metadata Editor. Here is a description of the MQL XML format:
<mql> - top level element for mql query
<domain_type> - text element that contains the domain type, currently only "relational" is supported
<domain_id> - text element that contains the domain id to query
<model_id> - text element that contains the model id to query
<model_name> - not required - text element with the model name
<parameters> - not required - element that contains a list of parameters for the query
<parameter> - element that contains information about an individual parameter
<name> - the name of the parameter (parameters are referenced in constraints as [param:PARAM_NAME])
<type> - The data type of the parameter, valid values include boolean, numeric,
<defaultValue> - The default value of the parameter as a string
<selections>- element that contains a list of business column selections
<selection> - business column selection element
<view> - text element that contains the id of the business table to select
<column> - text element that contains the id of the business column to select
<aggregation> - text element that contains aggregate type (none, min, max, sum, avg, count, distinct_count)
<alias> - a local alternate name to refer to this selection. Aliases maybe referenced in <constraint> elements
just like you would do with a column id.
<formula> - Use this element instead of a <view> and <column> reference to specify a calculated field.
<constraints> - element that contains a list of constraints for the MQL query
<constraint> - constraint container element
<operator> - text element that describes how to join the constraint to the query. The first constraint operator is
ignored but required. Valid entries are "AND", "OR", "AND NOT", and "OR NOT"
<condition> - text element that contains an MQL formula as defined in 02. Pentaho Metadata Formulas.
<orders> - element that contains a list of business columns to order by
<order> - order container element
<direction> - text element containing either "asc" or "desc"
<table_id> - text element containing the id of the business table to order by
<column_id> - text element containing the id of the business column to order by
<aggregation> - text element that contains aggregate type

Example
For an example of a MQL query, check out the MQL_Datasource.xaction. This sample action sequence is shipped with the BI server and sits in
the datasources folder in the bi-developers solution. By way of example the MQL query used in that action sequence is shown below:
<mql>
<domain_type>relational</domain_type>
<domain_id>steel-wheels</domain_id>
<model_id>BV_ORDERS</model_id>
<model_name>Orders</model_name>
<selections>
<selection>
<view>CAT_ORDERS</view>
<column>BC_ORDERS_ORDERDATE</column>
</selection>
<selection>
<view>CAT_ORDERS</view>
<column>BC_ORDERS_ORDERNUMBER</column>
</selection>
<selection>
<view>CAT_ORDERS</view>
<column>BC_ORDER_DETAILS_QUANTITYORDERED</column>
</selection>
</selections>
<constraints>
<constraint>
<operator>AND</operator>
<condition>[CAT_ORDERS.BC_ORDERDETAILS_QUANTITYORDERED] >70</condition>
</constraint>
<constraint>
<operator>AND</operator>

<condition>[CAT_ORDERS.BC_ORDERS_ORDERDATE] > DATE(2003;12;31)</condition>

</constraint>
</constraints>
<orders/>
</mql>
Support for Multiple Aggregate Types
Note: The feature described in this section will not be available until the CITRUS release (date pending).
You can now modify their Physical Columns to include multiple aggregate types. These aggregate types are available in the MQL Editor dialog
boxes in Pentaho Metadata Editor, Report Designer, and Chart Designer.
The first change is the optional aggregation child element of selection, which may be one of the values selected in Pentaho Metadata Editor:
<selection>
<view>bc_example</view>
<column>BC_VALUE</column>
<aggregation>sum</aggregation>
</selection>

The second change is an extension to the formula syntax when referring to business columns. Before, the syntax to reference the model only
supported [<BUSINESS CATEGORY>.<BUSINESS COLUMN>], now we also have [<BUSINESS CATEGORY>.<BUSINESS
COLUMN>.<AGGREGATION>]:
[bc_example.BC_VALUE.sum] >= 100

The last change impacts the order portion of the MQL; it's an identical change to the selection XML, with an optional aggregation child element:
<order>
<direction>asc</direction>
<view_id>bc_example</view_id>
<column_id>BC_VALUE</column_id>
<aggregation>SUM</aggregation>
</order>

See Second Use: Physical Table Column Formulas and Defining the Physical Column Aggregations for additional details.

04. Creating Business Tables and Columns

03. Creating a Business Model

03. Building a Pentaho Metadata Domain

05. Creating Relationships Between

Business Tables

After creating the business model, the next step is to add the business tables and business columns, then create the relationships between our
business tables.

Introducing the Metadata Editor Graph

Up to this point, we have only used the Tree Navigator to construct the business objects. The big white canvas on the right side
of the screen is the Metadata Editor Graph, and we use the Graph to lay out our business tables and show the relationships
between them. While we can accomplish the rest of our tasks using only the Tree Navigator, from here forward I will describe
how to perform each operation using both the Tree Navigator and the Editor Graph, so you can decide which view suits you
better.

Tree Navigator: Creating a New Business Table

To add a new business table using the Tree Navigator, first make sure that the model you want to add this business table to is selected (in the
tree), and the Business Tables node is expanded.
1. Right-click (or ALT-click) on the Business Tables branch in the Navigator Tree.
2. Select the New Business Table... option from the popup menu.
3. You will be prompted with a list of physical tables, each prefixed by the connection name they belong to. Select the physical table you
want to associate with this new business table.

Under Construction Alert

The first business table you create determines what connection is linked to this model - the one connection that this
model can support. The connection is determined by interrogating the physical table that you associate in this step.
We will be building out the connection to business model UI functionality in the future, but realize for now (as of the M4
release) that this area is half-baked. If you change your mind and want to associate a different connection with this
model, you will have to delete all of your business tables. You could possibly hand-edit the exported XML and re-import
it to change the connection, but I haven't tried it so I won't guarantee that it will work.

4. Click OK on the prompt. The Business Table Properties dialog displays.

In the Business Table Properties dialog, you will notice the Name/ID field at the top of the dialog is pre-populated with a value. This is the
id of this business table, and MUST be unique. We recommend that you accept the default value for this field.
The table you chose in step 3 is listed next, then below the fields is another Tree Navigator, with the name of your business table and all the
columns inherited from the physical table included as business columns. The business columns are created for you when the new business table

is created, so no need for the extra steps of creating them separately.

Trimming the Business Columns

To trim unnecessary business columns at this time:
1. In the Business Table Properties dialog's Tree Navigator, select a column you wish to remove.
2. Click the delete icon (the one with the red circle), to the right of the word Subject above the dialog's Tree Navigator.
3. Repeat with any remaining columns that you wish to remove. Click OK when you are done.

Editor Graph: Creating a New Business Table

Creating a business table on the Editor Graph is much like using the Tree Navigator.
1. First, you must make sure you have the business model that you want to add this new business table to selected in the Tree Navigator.
You can be sure it is selected if you see the name of the model at the top of the Graph canvas.
2. Next, right-click on the Graph, and select the New Business Table... option from the popup menu.

Follow the instructions above (for creating the table from the Navigator Tree), starting at step 3.

Shortcut for Creating Business Tables

A nice shortcut! Drag the physical table from the Navigator Tree to the Editor Graph canvas to create a new business table
based on that physical table.
Another shortcut is to drag the physical table in the Navigator Tree to the Business Tables node in the tree, which will also
create a new business table based on that physical table. NOTE that in the M4 milestone, this shortcut is broken... sorry, soon
to be fixed!!

TODO

04. Enriching Your Data - Understanding Metadata

Concepts and Properties
03. Building a Pentaho Metadata Domain

02. Pentaho Metadata Editor Getting

Started Guide

05. Adding Security to Metadata Business

Objects

Presumably the end goal when creating a metadata domain is to have a model that is available to end-users and applications that allows them to
consistently and richly enhance the data they are working with. Whether that be through formatting, security metadata, or some other custom
metadata, it all should result in a more efficient, consistent, clearer and smarter view of the data.
So far, we have walked through modeling your database in a fashion that is more intuitive than its physical representation. The second half of the
metadata work is in, well, defining the metadata! The Pentaho metadata paradigm uses the term concept to mean a collection of metadata
properties that can be applied to a given business object (business table or column, for example).

Concept Defined
Here is the official definition of a concept:
Unknown macro: {multi-excerpt-include}

Concept Overview
This excerpt from the Metadata Business Model Overview describes some of the details regarding concepts and how they are used:
Unknown macro: {multi-excerpt-include}

Exceptions to the Rules - Required Properties and the Default Concept

Like all exceptions, the exceptions to the metadata inheritance logic is complex, but sound. There are two sets of properties that change how the
typical inheritance is realized - required properties and the default concept.

Required Properties
Required properties and the default concept are two very different things.
All physical and some business objects in the metadata model have a set of required properties. These properties are set automatically on
creation of the object, and are not removable (you can change their values though!). The purpose for required properties is to not allow the user to
get into a predicament where they have removed a property that is integral to the SQL generation process. For instance, if a physical table did not
have a Target Table property set, the SQL generator would complain loudly, since it would not know what physical table to query. So we make
Target Table required and do not allow the user to remove it, although the value is modifiable.
This has ramifications. Using our previous example, when you set a parent concept on the physical table, and the parent concept has a Target
Table property, the physical table will not recognize the parent concept's value for Target Table. This is because the physical table already has a
Target Table property as part of it's self concept, and the self concept always overrides the parent concept. And since you cannot remove a
required property, the parent concept's Target Table will never be recognized at the physical level.
So how do you override a physical object's required property? You set a parent concept at the business model or business view level. Since the
inherited properties are override-able, the parent concept at the business level wins.
All physical metadata objects, the business categories and the business model have required properties. You can see what's required for each
here.

The Default Concept

Unknown macro: {multi-excerpt-include}

Applying Concepts and Properties in the Pentaho Metadata Editor

Now that you have a better understanding of the terms and ideas regarding Pentaho metadata let's go about understanding how to apply
metadata to your business model using the Pentaho Metadata Editor.

05. Adding Security to Metadata Business Objects

04. Enriching Your Data - Understanding
Metadata Concepts and Properties

02. Pentaho Metadata Editor Getting

Started Guide

06. Adding Row Level Security to a Pentaho

Metadata Model

Pentaho metadata provides a Security Information property that allows you to define table or column level security that the Pentaho BI Server can
make use of. Before you can use this property, you need to tell the Pentaho Metadata Editor about your Pentaho BI Server, so that the program
can retrieve the list of Users, Roles and Access Control Lists needed.

Setting Up the Security Service

The security information used in the business model needs to be retrieved from a Pentaho BI Server, so make sure you have the following
information available before you attempt to configure security:
The base URL to the Pentaho BI Server, as well as the name of the service to execute security information retrieval. In the demo
server, the base URL is http://localhost:8080/pentaho, and the default name for the service is ServiceAction. Ask your server
administrator if changes were made to this service.
An admin set of credentials for the server.

Security Service Settings

1. From the main menu, select the Security Service option from the Tools menu.
2. The Security Service dialog displays.

3. On the Service tab, enter the Service URL for your server. This is a URL combining the base URL and the service name. The demo
server's Service URL is http://localhost:8080/pentaho/ServiceAction .
4. Next, select the level of detailed security information you want: All, Users or Roles. If you have hundreds of users in your system, you
probably only want to return the roles, and use roles for security information properties. The access control lists are returned with all three
options.
5. In the username field, provide an admin level username to authenticate with the server.
6. And last, enter the password for the user specified above.
You can click the Test button to be sure the settings are correct, and your server is accessible. You should see a message similar to the
following:

Working Offline
You will at times want to work on your model, and may not have access to your Pentaho BI Server. You can save your security information in a
file, and the Pentaho Metadata Editor will be just as happy to retrieve your settings from that file instead of making a trip to the server every time
you open this domain.
1.
2.
3.
4.
5.
6.
7.

Follow the steps above to configure your security settings.

Click the Test button, to show the security information from the server.
Copy all of the XML between the <content></content> tags, including content the tags themselves.
Paste the XML into your favorite text editor, and save the file as metadata_security.xml, in a location of your choosing.
Switch to the File tab in the Security Service dialog.
Browse to the file that you just saved.
Click OK when you are done.

Modifying Security Constraints

To add security constraints to a specific business table or column, first bring up the properties dialog, and then click the add property button:

Select the Security Information property and click OK

With the security property available, now add the individual role or user permissions to the business model, table, or column. These permissions
will then be enforced within Pentaho's BI Platform after publishing the new metadata model.

Configuring the Pentaho BI Server

Starting in version 2.0, the Pentaho BI Platform uses a security-aware metadata processor by default. In previous versions, the metadata
processor in the platform was not security aware. As a consequence, existing metadata model files that do not specify security
constraints must now specify security constraints to grant access to roles and/or users.

05. Creating Relationships Between Business Tables

04. Creating Business Tables and Columns

03. Building a Pentaho Metadata Domain

06. Building a Business View

Once you have all of your business tables created, you will need to create relationships between the tables, so that the query generators and SQL
generators that work with Pentaho metadata can create the data queries correctly.
This is very much like drawing a relational diagram to show primary and foreign key relationships. Although relational links are not the only
relationships that can be modeled. You can create a relationship between any two tables, link any two columns between them and dictate what
the relationship is (one to many, many to many , etc.).
So the important pieces of information to know before you try to create a relationship is:
1. what two business tables would you like to associate with this relationship,
2. what columns in the business tables identify the relationship,
3. and what kind of relationship is it - one to one, one to many, many to one, etc.

Tree Navigator: Creating a New Relationship

To create a new relationship between business tables using the Tree Navigator, first make sure that the model you want to add this relationship to
is selected, and the Relationships node is visible (lives under the business model name node).
1. Right-click (or ALT-click) on the Relationships branch in the Navigator Tree.
2. Select the New Relationship... option from the popup menu.
3. The *Relationship Properties" dialog displays.

4. Select from the From Table / Field list the business table that you would like to start the relationship from.
5. Select from the To Table / Field list the business table that you would like the relationship to go to.
6. You must also specify the business columns (from the adjacent lists) from each business table that identify this relationship. An
alternative, if the business column names are similar, is to click the Guess Matching Fields button, and let the dialog attempt to
determine the columns for you.
7. Next step, define the relationship from the Relationship drop down list.
8. If the relationship requires a complex join, select the complex join checkbox, and enter a formula in the text box provided.
9. Click OK to close the dialog.
10. You should see a new relationship line drawn between the two tables on the Editor Graph, and the relationship represented in the tree.

A Special Note on Complex Joins

Note that complex joins appear in the WHERE clause of the SQL statement, so currently any joining that takes place in the FROM
clause of the SQL statement is not supported. An example of a complex join might be
AND([BIZ_TABLE_A.BIZ_COL_A]=[BIZ_TABLE_B.BIZ_COL_A];[BIZ_TABLE_A.BIZ_COL_B]=[BIZ_TABLE_B.BIZ_COL_B]). This
represents a join of two tables based on two key columns vs. a single join column.
Also note, the complex join expression provided must utilize the names of the business tables and business columns, not phyiscal
tables and phyiscal column names.

Editor Graph: Creating a New Relationship

In the Editor Graph, creating a new relationship is simplified a bit, because you select the two business tables on the canvas, and the Relationship
Properties dialog is pre-populated with your selections.
To begin, make sure that the model you want to add this relationship to is selected, and the business tables are displayed in the Editor Graph.
1. Select the two business tables you want to include in the new relationship, either by click and dragging a marquee around the tables, or
by holding the SHIFT+CTRL keys, then clicking on the tables.
2. Once your business tables are selected in the Graph, right-click (or CTRL-click) on the selection. Click the New Relationship... option
from the popup menu.

Follow the instructions from step 4 above to fill in the relationship properties. Note that when the Relationship Properties dialog displays,
the To and From tables are selected for you.

TODO
Relationship Definitions
The relationships that can be chosen are defined with examples:
Link: A 0:0 optional relationship basically states that a person can occupy one parking space, that I don't need a person to have a space and I
don't need a space to have a person.
SubType: A 1:0 relationship; optional only on one side. This would indicate that a person might be a programmer, but a programmer must be a
person. It is assumed that the mandatory side of the relationship is the dominant.
Physical Segment: A 1:1 mandatory relationship and demonstrates a segmentation denormalization. A person must have one and only one DNA
pattern and that pattern must apply to one and only one person.
Possession: A 0:N (zero to many) optional relationship indicating that a person might have no phone, one phone or lots of phones, and that a
phone might be un-owned, but can only be owned by a maximum of one person.
Child: A 1:N mandatory relationship, the most common one seen in databases. A person might be a member or might not, but could be found
multiple times (if the member entity represents membership in multiple clubs, for instance).
Characteristic: A 0:N relationship that is mandatory on the many side. It indicates that a person must have at least one name, but possibly many
names, and that a name might be assigned to a person (might not) but at most to one person.
Paradox: A 1:N relationship mandatory on both sides. The "Chicken and the Egg" is involved since you have to have a person to have citizenship,
but citizenship to have a person.
Association: A N:N (many to many) optional relationship. Conceptually, it means that a person might or might not work for an employer, but could
certainly moonlight for multiple companies. An employer might have no employees, but could have any number of them. Again, not hard to
visualize, but hard to implement. Most solutions of this situation involve creating a third "Associative Entity" to resolve the M:M into two 0:M
relationships. This might be an entity called employee because it does link the person to the employer the person works for.

06. Adding Row Level Security to a Pentaho Metadata

Model
Adding Row Level Security to a Pentaho Metadata Model
Row Level Security allows you to control the results that are returned in a query based on a user's security level. You can specify which rows of
data each User Role or User ID is allowed to retrieve from the database, based on some column of data, or combination of columns of data.
Within the Metadata Editor, select the model to add Row Level Security to, right click on the Model, and select "Edit...".

WARNING: Row Level Security is only in effect at the Model level. Any data constraints defined below the Model Level, such in a
Business Table or Business Column, is ignored and not used.

From the Model Properties dialog, select the General -> Data Constraints Property:

By default, Row Level Security is not enabled. There are two forms of Row Level Security in Pentaho Metadata, Global Constraint and Role
Based Constraints.

Global Constraint
If using the Global Constraint, a single MQL Formula is used to define security for all users. In addition to the standard MQL Functions available,
there are also two additional functions available.
USER() - returns the name of the current user

ROLES() - returns a list of roles the current user has.

Example of Global Constraints

This example defines an MQL Formula that allows Admins full access, and everyone else no access
IN("Admin"; ROLES())

Role Based Constraints

If using Role Based Constraints, the Metadata engine determines which MQL constraints apply to the current user and apply them to the current
query. Constraints may be added for each Role and User within a system. If zero constraints match a user and their roles, no data is returned by
the MQL query. If more than one constraint applies to a user, then the constraints are OR'ed together to determine row visibility.

Example of Role Based Constraints

This example defines an MQL Formula for three different roles. The Admin Role has full row visibility, the Sales and Engineering Roles may only
see data that joins to rows with their particular department. (The syntax is [business_table.business_column] = value).
Role

Constraint

Admin

TRUE()

Sales

[BT_OFFICE.BC_DEPARTMENT]="Sales"

Engineering

[BT_OFFICE.BC_DEPARTMENT]="Engineering"

Important Note
Row Level Security Constraints are applied at the MQL Layer. The Business Columns referenced in the MQL Security Constraints will be
resolved down to SQL Table Columns. The Tables which contain column references included in security constraints will be joined to your query,
based on the relationships defined in the Business Model. It is recommended that you do not use outer joined business columns for the purposes
of security constraints.

06. Building a Business View

05. Creating Relationships Between Business
Tables

03. Building a Pentaho Metadata Domain

Congratulations! You are almost done building your business model! The last step is for you to define the business view for the model.
A business view is defined as
Unknown macro: {multi-excerpt-include}
A business category is just a named bucket for you to group and re-group your business columns in. They can mimic your business table names,
or be named after your favorite rock stars. Categories do not have metadata associated with them, have no tie back to any business table
(although our Editor will give you the impression this relationship exists - don't be fooled), and have the simple purpose of allowing you to bucket
the business columns in your model as intuitively as possibly for your data consumers.
Today, categories are a single level entity. We hope in the future to support nested categories.
Building a business view consists of creating your categories, then moving your business columns from the business tables into the categories.
You can move columns from different business tables into the same category, and even duplicate the same business column into two different
categories.
The Editor Graph only represents the business tables portion of the business model, so we use the Tree Navigator and the Category Editor to
create a business view.

Tree Navigator: Creating Categories

To create a new category using the Tree Navigator, first make sure that the model you want to add this category to is selected, and the Business
View node is visible (lives under the business model name node).
1.
2.
3.
4.
5.

Right-click (or ALT-click) on the Business View branch in the Navigator Tree.
Select the New Category... option from the popup menu.
The Category Properties dialog displays.
Give the category a name in the Name/ID field.
Select OK when you are done.

Under Construction
Note that the dialog that you are presented with at this point leads you to believe that you can set metadata properties
on a category. While technically possible, it makes no sense and is not going to be carried forward. So ignore the
properties features of the Category Properties dialog, and just set a name.

Tree Navigator: Arranging Business Columns in Categories

Now that you have a category, let's add some business columnsto that category.
1. In the Navigator Tree, make sure that the business tables branch and the business view branch of your model are both expanded.
2. Under business tables, expand the table whose columns you want to move.
3. Click on a column under the business table, and drag it to the category branch where you want it to reside.

Under Construction
Currently, there is a bug that prevents you from selecting muliple business columns and dragging them for category
placement. We know this makes building the view a bit cumbersome, but the Category Editor can relieve that
frustration. Read on!

Building a Business View Using the Category Editor

Building a business view in the Category Editor is much more efficent and streamlined.
Make sure that the model whose business view you want to create is selected, and the Business View node is visible (lives under the business
model name node).
1.

1. Either double-click on the Business View branch in the Navigator Tree, or choose the *Category Editor..." option from either the main
menu or the main toolbar.
2. The Category Editor dialog displays.

The Category Editor allows you to create categories directly from your business tables, move columns into categories, add new categories and
remove categories and columns.

Create a New Category From a Business Table

1. The list on the left in the Category Editor is a list of all of the business tables in your view. To create a category from one of those tables,
first select the table on the left.
2. Click the > button.
3. Notice that your category has the same name as your business table, and all of your business columns were added to the new category
by default.
If you would like to add all of your business tables as categories, select them all, and click the >> button.

Move Columns Into Categories

1. To move a column to an existing category, select the column from the list of available business tables. To view the columns under a
business table, click the plus sign
next to each table name.
2. Next, select the destination category from the list on the right.
3. Click the > button.

Add a New Category

1. If you would like to add a new category alone, click the plus sign
in the upper right corner of the Categories list.
2. The Category Properties dialog displays. Enter a name for your category, and click OK.
3. A neww category appears in the ategories list.

Remove Categories and/or Columns

1. To remove categories or columns, select the items you wish to remove in the categories list on the right.
2. Click the x button in the upper right corner of the categories list.
Click the Close button when you are finished working on your business view.

Managing Category Details

While you can't edit the category names while in the Category Editor, you can edit that information from the Tree Navigator,
after you have closed the Category Editor.

10. Publishing a Domain to a Pentaho BI Server

09. Domain Backup and Recovery

02. Pentaho Metadata Editor Getting Started

Guide

In order for the Pentaho BI Server to make use of your metadata domain, you must share an XML representation of the domain with a Pentaho
solution that your server knows about.

Metadata Domains and the Pentaho BI Server

Today's implementation of metadata within the Pentaho BI Server has some very clear rules you must follow to be sure it
operates correctly:
There can only be one metadata domain per Pentaho solution,
that metadata domain is associated with the solution by placing the XML format of the domain in the root directory of
the solution,
and the domain XML file must be metadata.xmi.

You can accomplish this by exporting your domain file, and copying it manually to the solution directory of your choice. Or, you can use the
Pentaho Metadata Editor's publish feature, if you know the credentials to your server.

Publish to the Pentaho BI Server

Before you attempt to publish, make sure you have the following information available:
Has your Pentaho BI Server's publish password been set? Ask your server administrator if you are not sure. This password must be set
in order to utilize the server's publish utilities.
Do you have a username and password to your Pentaho BI Server with admin access?
Do you know the base URL for your Pentaho BI server? This will consist of all URL info up to and includng the web application context.
For example, the base URL of the pentaho demo server is *http://localhost:8080/pentaho* .
For publishing, you will need to append to the base URL the name of the publish service. The default is RepositoryFilePublisher. This
will be the value you will use, unless your server admin has changed the service name.
You also need to know the name of the solution that you want to publish this domain to. For example, our demo server ships with two
different solutions, the samples solution and the Steel Wheels solution. No slashes are needed.

Publishing
1.
2.
3.
4.

From the main menu's File menu, select the Publish to Server option.
The Publish dialog displays.
Enter the publish location, which is your solution name.
Enter the web publish URL, which is your Pentaho BI Server's base URL followed by the publish service name.
RepositoryFilePublisher is the default.
5. Enter the publish password .
6. Enter the administrator username.
7. Enter the administrator password.

If the metadata.xmi file already exists on the server, you will be prompted to overwrite it.

Troubleshooting Publish
If publishing to the server fails, here are a few things you will want to verify to be sure your information and configuration is
correct:
Make sure that the publish password is set on the server. You cannoot use the server's publish utility if that password is
not set. The publish password is defined in publisher_config.xml in directory pentaho-solutions\system.
Verify that your server credentials have admin level responsibility.
Do not use a trailing or leading slashes on the server URL, solution name or domain file name.