Configuration API

The Configuration API provides a means for types and instances to be configured by third-parties.

Types are known by their string identifier and are, for all other purposes, opaque entities — these may or may not exist as actual JavaScript classes; these may simply represent an interface type. In the same manner, instances are known only by their string identifier — it may or may not exist as an actual JavaScript variable or module.

Configurations are JavaScript objects that conform to the pentaho.config.spec.IRuleSet interface — essentially, a set of configuration rules, pentaho.config.spec.IRule. Typically, configurations are provided as the value returned by an AMD/RequireJS module. This module needs to be advertised to the configuration system by registering it with pentaho/instanceInfo, as an instance of type pentaho.config.spec.IRuleSet.

Configuration Rules are composed of the following parts:

1. The select object specifies the targeted type (or types), or instance (or instances), and the values of any Pentaho environment variables to which it applies. Alternative values for a variable can be specified using a JavaScript array. The most useful environment variable is application, as it allows creating rules that are only applied when a type or instance is being used by a certain application, like, for example, CDF or Analyzer. See also Known Values of Pentaho Environment Variables.

2. The apply object specifies the actual configuration properties and their values. You will need to consult the reference documentation of the target type or instance to know the list of available properties. For example, the Visualization API’s Model type, being a Complex type, can be configured with the properties of the IComplexTypeProto interface.

3. The priority allows fine-tuning the order by which rules that target the same type or instance are merged. Higher values have higher priority. It is optional and defaults to 0.

See Rule Specificity for more information on the the order by which configuration rules having the same target are merged.

Example Configuration Module

The following is an AMD/RequireJS configuration module that contains two configuration rules:

1. The first rule targets the type my.ICar, when used by the my-vehicle-editor application, and specifies the value of its tireSize and exteriorColor properties.

2. The second rule, has a higher-than-default priority, targets the type my.ICandy, whatever the application using it, and specifies the value of its cocoaPercentage and fillingFlavour properties.

3. The third rule targets the instance my.friend.john1, whatever the application using it, and specifies the value of its empathyFactor property. Note the use of a different property, instance, to identify the rule’s target.

define(function() {
  
  "use strict";
  
  // The value of the module is an IRuleSet.
  return {
    rules: [
      // IRule 1
      {
        select: {
          type: "my.ICar",
          application: "my-vehicle-editor"
        },
        apply: {
          tireSize: 18,
          exteriorColor: "caribbean-blue"
        }
      },
    
      // IRule 2
      {
        priority: 1,
        select: {
          type: "my.ICandy"
        },
        apply: {
          cocoaPercentage: 0.9,
          fillingFlavour: "orange"
        }
      },
      
      // IRule 3
      {
        select: {
          instance: "my.friend.john1"
        },
        apply: {
          empathyFactor: 0.6
        }
      }
    ]
  }
});

Global Configuration File

Ad hoc configuration rules can be added to the system, by system administrators, by placing these in the global configuration file — a configuration file conveniently registered for you.

The file is located within the Apache Karaf folder at: config/web-client/config.js. Depending on the product, the Karaf folder is located at:

• PDI: data-integration/system/karaf/.
• Pentaho Server: pentaho-server/pentaho-solutions/system/karaf/.

Editing and saving the file causes the system to refresh its configuration, without the need to restart the software.

The configuration file is shipped with a small set of illustrative (but commented-out) rules.

ATTENTION: server upgrades overwrite this file with an empty version of it, so you need to backup the file yourself before upgrading and restore it afterwards.

As an alternative to using the global configuration file, you can bundle and deploy your own Pentaho Web Package containing a registered configuration module.

Component authors may also wish to provide a default configuration beside the component, included and registered in the same Pentaho Web Package.

Known Values of Pentaho Platform Environment Variables

application

theme

locale

The possible values are those defined by RFC 5646.