Configuration API

The Configuration API provides a means for modules to be configured by third-parties.

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/modules, as an instance of type pentaho/config/spec/IRuleSet.

Configuration Rules are composed of the following parts:

1. The select object specifies the targeted module, 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 module 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 module 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 IComplexType interface.

   The apply property can also be a function, in which case it is called to determine the actual configuration object, only when and if the selected module or modules are loaded. Read more about this, below, on the deps property section.

3. The deps array contains a list of additional module identifiers which are loaded only when and if the selected module or modules are loaded. When apply is a function, then the values of the specified modules are given as arguments to it.

4. The priority value allows fine-tuning the order by which rules that target the same module 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 module 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 module my/ICandy, whatever the application using it, and specifies the value of its cocoaPercentage and fillingFlavour properties.

3. The third rule targets the instance module my/friend/john1, whatever the application using it, and specifies the value of its empathyFactor property.

define(function() {
  
  "use strict";
  
  // The value of the module is an IRuleSet.
  return {
    rules: [
      // IRule 1
      {
        select: {
          module: "my/ICar",
          application: "my-vehicle-editor"
        },
        apply: {
          tireSize: 18,
          exteriorColor: "caribbean-blue"
        }
      },
    
      // IRule 2
      {
        priority: 1,
        select: {
          module: "my/ICandy"
        },
        apply: {
          cocoaPercentage: 0.9,
          fillingFlavour: "orange"
        }
      },
      
      // IRule 3
      {
        select: {
          module: [
            "my/friend/john", 
            "my/friend/marie"
          ]
        },
        apply: {
          empathyFactor: 0.6
        }
      },
      
      // IRule 4
      {
        select: {
          module: "my/house/main"
        },
        deps: [
          "lodash", 
          "./baseHouseSchematics"
        ],
        apply: function(_, baseHouseSchematics) {
          return _.merge(baseHouseSchematics, {
            averageSummerTemperature: 23
          });
        }
      }
    ]
  }
});

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.