Configuration API

The Configuration API provides a means for JavaScript 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. The configuration module needs to be registered 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 arguably 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, below, 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 four configuration rules:

1. The first rule targets the type module my/Car, when used by the my/vehicleEditor 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/Candy, whatever the application using it, and specifies the value of its cocoaPercentage and fillingFlavour properties.

3. The third rule targets the instance modules my/friends/john1 and my/friends/marie, whatever the application using it, and specifies the value of their empathyLevel property.

4. The fourth rule targets the instance module my/houses/main, whatever the application using it, and configures it; the configuration is based on a configuration obtained as a dependency from the sibling module baseHouseSchematics.

define(function() {
  
  "use strict";
  
  // The value of the module is an IRuleSet.
  return {
    rules: [
      // IRule 1
      {
        select: {
          module: "my/Car",
          application: "my/vehicleEditor"
        },
        apply: {
          tireSize: 18,
          exteriorColor: "caribbean-blue"
        }
      },
    
      // IRule 2
      {
        priority: 1,
        select: {
          module: "my/Candy"
        },
        apply: {
          cocoaPercentage: 0.9,
          fillingFlavour: "orange"
        }
      },
      
      // IRule 3
      {
        select: {
          module: [
            "my/friends/john", 
            "my/friends/marie"
          ]
        },
        apply: {
          empathyLevel: 0.6
        }
      },
      
      // IRule 4
      {
        select: {
          module: "my/houses/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 systems integrators or system administrators, by placing these in the global configuration file — a conveniently pre-registered configuration file.

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.