@ghg/amplifier

Greenhouse Amplifier

Installation

$ yarn add @ghg/amplifier

Quick example

import Amplifier, { addPluginToBuilderOptions } from '@ghg/amplifier';

import BeerPlugin from '@fake-organization/beer-amplifier-plugin';

addPluginToBuilderOptions(BeerPlugin);

const amplifier = Amplifier.Builder()
  .setName('Amplifier example');

amplifier.withWeatherVariableTemperature('temperatureNoordBrabant', {
  country: 'nl',
  cities: ['Eindhoven', 'Valkenswaard'],
});

amplifier.withTimeVariableisWeekend('isWeekend');

amplifier.withBeerService('BeerService');

amplifier.withRule('Time for a "biertje"')
  .when('temperatureNoordBrabant >= 25 && isWeekend')
  .do('BeerService.bringMeBeer()');

Internal supported plugins

This module ships with some interal plugins

• Xandr (Appnexus)
• DV360
• Facebook
• Google Sheet
• Google Trends
• LemonPI (Product store)
• Outmoove
• Time
• Weather

External plugins

The amplifier also support externally developed plugins. Plugins published with -amplifier-plugin in the package name will be loaded by the PluginManager. These plugins need to extend the the Plugin module eg.

import { Plugin } from '@ghg/amplifier';

export default class SamplePlugin extends Plugin {
  // required environment variables
  static requiredEnvVariables = ['BAR'];

  // required variables in requirements
  static requiredVariables = ['foo'];

  getName({ name }) {
    return name;
  }

  getFoo() {
    return this.options.foo;
  }

  getBar() {
    return process.env.BAR;
  }
}

Rules Manger

Explanation of the rule manager. An important part of the Amplifier is the rule manager, rules can be included in the amplifier by adding them to the rules property. Rules are object with an condition that need to be met before the consequence will be executed. Both have access to the R API and the execution context

Flow control API (R)

The first argument of both condition and its corresponding consequence is the R Flow Control API. This api controls the flow of the rules.

Below are the functions available via the Flow Control API.

If you look at the below rule example.

  {
    "name": "transaction minimum",
    "priority": 3,
    "on" : true,
    "condition": function(R) {
      R.when(this.transactionTotal < 500);
    },
    "consequence": function(R) {
      this.result = false;
      R.stop();
    }
  }

R.when

This function is used to pass the condition expression that we want to evaluate. In the above expression we pass the expression to check whether the transactionTotal attribute of the fact in context is below 500 or not. If the expression passed to R.when evaluates to true, then the condition will execute. Else the rule engine will move to next rule or may terminate if there are no rules left to apply.

R.next

This function is used inside consequence functions. This is used to instruct the rule engine to start applying the next rule on the fact if any.

R.stop

This function is used inside consequence functions to instruct the Rule Engine to stop processing the fact. If this function is called, even if rules are left to be applied, the rule engine will not apply rest of rules on the fact. It is used mostly when we arrive a conclusion on a particular fact and there is no need of any further process on it to generate a result.

As you can see above example, when the transaction is less than 500, we no longer need to process the rule. So stores false in result attribute and calls the stop immediately inside consequence.

R.restart

This function is used inside consequence functions to instruct the rule engine to begin applying the Rules on the fact from first. This function is also internally used by the Rule engine when the fact object is modified by a consequence function and it needs to go through all the rules once again. Using the ignoreFactChanges: true option when initializing a new rule engine will turn off this functionality.

Execution context

argument of both condition and its corresponding consequence is the execution context and will include the resolved variables and services. Note: consequence are async condition are not.