Introduction

The Rules Engine is a lightweight client-side framework for executing rules: declarative event listeners that invoke outcomes. An outcome can be a declarative Rules Engine action chain or a JavaScript function. Its primary focus is deploying and integrating Digital Customer Service (DCS) Embedded Service into web sites. Rules and action chains can be loaded from a JSON file or via the Rules Engine’s API.

Rules

A rule defines the execution of an outcome in response to an event. An outcome can either be a Rules Engine action chain or a JavaScript function.

The rule specifies the following details:

Events

The following events are supported by the Rules Engine.

Click

Listens for the browser click event on the DOM element with the specified id. If the element being clicked is a child of the element with the specified id, the rule still executes. Keyboard activation of some elements (e.g., space on a focused button) also triggers click.

{
  eventName: 'click',
  properties: { id: 'showES' },
  outcome: 'showES'
}

History

Listens for changes to the browser’s history (e.g., single-page application navigation).

{
  eventName: 'history',
  outcome: 'history',
  parameters: { url: '[[ window.location.href ]]' }
}

Load

Fires after a site definition has been loaded using the load API.

{
  eventName: 'load',
  outcome: 'load'
}

Variable Change

Listens for changes to the value of a specified window variable. The variable name is specified on the rule via properties.window.

{
  eventName: 'variableChange',
  properties: { window: 'myVariable' },
  outcome: 'vc',
  parameters: {
    nextValue: '[[ event.nextValue ]]',
    value: '[[ event.value ]]'
  }
}

Embedded Service

All Embedded Service events can be listened for using the es: namespace. If the Embedded Service framework is not yet loaded when the rule is defined, the event listener is registered when the framework loads.

{
  eventName: 'es:load',
  outcome: 'esLoaded'
}

Custom

Custom events can be dispatched using the Rules Engine API for application and framework integration. Register rules for custom events like any other event.

{
  eventName: 'myCustomEvent',
  outcome: 'myCustomEventHandler'
}

Outcomes

An outcome for a rule can either be a Rules Engine action chain or a JavaScript function.

Action Chain

An action chain is a sequence of one or more actions, each performing synchronous work. Some actions, e.g., if, can branch execution. The root property of the chain specifies the start action; subsequent actions are selected by the current action’s outcomes.

Each action specifies the following details:

Example

{
  root: 'default',
  actions: {
    default: {
      executor: 'if',
      parameters: {
        condition: '[[ nextValue > (value || 0) ]]'
      },
      outcomes: {
        'true': 'true',
        'false': 'false'
      }
    },
    true: {
      executor: 'alert',
      parameters: {
        message: 'Value Increased'
      }
    },
    false: {
      executor: 'alert',
      parameters: {
        message: 'Value Decreased'
      }
    }
  }
}

If

Branches the action chain by evaluating a boolean condition. The condition is passed via parameters.condition. The action has 'true' and 'false' outcomes.

{
  executor: 'if',
  parameters: {
    condition: '[[ nextValue > (value || 0) ]]'
  },
  outcomes: {
    'true': 'true',
    'false': 'false'
  }
}

Switch

Branches the chain by evaluating a string-returning condition. Outcomes correspond to the returned string values.

{
  executor: 'switch',
  parameters: {
    condition: '[[ site.properties.mode ]]'
  },
  outcomes: {
    'proactive': 'proactive',
    'reactive': 'reactive'
  }
}

Alert

Displays a JavaScript alert dialog with the specified message.

{
  executor: 'alert',
  parameters: {
    message: 'Hello, World!'
  }
}

Script

Runs arbitrary JavaScript code.

{
  executor: 'script',
  parameters: {
    script: 'const message = (await (await fetch("https://jsonplaceholder.typicode.com/todos/")).json())[Math.floor(Math.random() * 200)].title; alert(message);'
  }
}

Load Embedded Service

Loads Embedded Service with the specified configuration. Expressions can be used to make the configuration dynamic.

{
  executor: 'loadES',
  parameters: {
    vbUrl: "https://<visual-builder-host>"
  }
}

Update Embedded Service

Updates Embedded Service with the specified configuration.

{
  executor: 'updateES',
  parameters: {
    context: {
      serviceRequestNumber: '[[ serviceRequestNumber ]]',
      categoryId: '[[ categoryId ]]',
      product: {
        inventoryItemId: '[[ productItemId ]]',
        productGroupId: '[[ productGroupId ]]'
      }
    }
  }
}

Maximize Embedded Service

Shows the Embedded Service dialog.

{
  executor: 'maximizeES'
}

Function

Function outcomes are supported for integrating with existing applications.

{
  eventName: 'click',
  properties: { id: 'function' },
  outcome: (message) => alert(message),
  parameters: ['[[ site.properties.message ]]']
}

Site Properties

The Rules Engine maintains a set of site properties that can be set through the site definition at load time or dynamically using the Rules Engine API.

Expressions

An expression is a string starting with [[ and ending with ]]. Expressions can be used in rules (as outcome parameters) and in action chains (as executor parameters) to pass values evaluated at runtime. You can reference site.properties, event payloads, or other JavaScript variables.

Deployment

The Rules Engine is packaged as an ES6 module which can be imported in a script tag of type module. Importing the Rules Engine module returns the singleton instance of the Rules Engine which can optionally be assigned to a global variable to make it easier to access later.

JSON File

          
<script type="module">
  import re from 'https://ee.channels.ocs.oraclecloud.com/re/25.10.0/dist/re.js';
  window.re = re;
  re.load('https://host/rules.json');
</script>

JavaScript Object

The Rules Engine configuration can also be loaded using a JavaScript object instead of a file URL.

<script type="module">
  import re from 'https://ee.channels.ocs.oraclecloud.com/re/25.10.0/dist/re.js';
  window.re = re;
  re.load({
    properties: {
      message: 'This is a Site Property'
    },
    rules: [{
      eventName: 'load',
      outcome: (message) => alert(message),
      parameters: [ "[[ site.properties.message ]]" ]
    }]
  });
</script>

JET Component

An oj-dcs-rules-engine JET component is available for integrating the Rules Engine into Visual Builder and JET applications.

<oj-dcs-rules-engine id="dcs-shell-rules-engine" event-filter="["es:linkAction"]"
  on-event="[[$listeners.rulesEngineEvent]]" url="[[ $application.path + 'resources/json/portal.site.json' ]]"
  properties="[[ $page.functions.buildRulesEngineProperties($application) ]]"
  translation-data.app-strings="[[ $application.translations.app ]]">
</oj-dcs-rules-engine>

For applications built prior to the JET component being available (25B and below), you must: upgrade oj-dcs components; add oj-dcs-rules-engine to the app; and place it on the shell page.

Rules Engine API

load

Loads the rules, action chains and properties from a supplied site definition file URL or object.

addActionChain

Adds an action chain to the registry to be invoked as an outcome.

on

Registers a rule that invokes either a function or a named action chain in response to an event.

dispatch

Dispatches all registered rules for the specified custom event.

set

Sets a site property value. The property is available in expressions as site.properties.{name}.

Logging & Debugging

Enable logging by setting the re.logging flag in session storage to true. Use your developer tools console to filter for messages containing RE:.

sessionStorage.setItem('re.logging', true);

Examples

Site Properties

This simple definition shows the use of site properties in expressions.

{
  properties: {
    message: 'This is a site property'
  },
  actionChains: {
    alert: {
      root: 'default',
      actions: {
        default: {
          executor: 'alert',
          parameters: {
            message: '[[ `VALUE ${site.properties.message}` ]]'
          }
        }
      }
    }
  },
  rules: [
    {
      eventName: 'click',
      properties: { id: 'alert' },
      outcome: 'alert'
    }
  ]
}

Event Parameters

This definition shows passing the event payload as parameters to an action chain.

{
  "actionChains": {
    "vc": {
      "root": "default",
      "actions": {
        "default": {
          "executor": "if",
          "parameters": {
            "condition": "[[ nextValue > (value || 0) ]]"
          },
          "outcomes": {
            "true": "true",
            "false": "false"
          }
        },
        "true": {
          "executor": "alert",
          "parameters": {
            "message": "[[ `Value Increased` ]]"
          }
        },
        "false": {
          "executor": "alert",
          "parameters": {
            "message": "Value Decreased"
          }
        }
      }
    }
  },
  "rules": [
    {
      "eventName": "variableChange",
      "properties": "test",
      "outcome": "vc",
      "parameters": {
        "nextValue": "[[ event.nextValue ]]",
        "value": "[[ event.value ]]"
      }
    }
  ]
}

Load Embedded Service

Script to load Embedded Service on any webpage.

          
<script type="module">
  import re from 'https://ee.channels.ocs.oraclecloud.com/re/25.10.0/dist/re.js';
  window.re = re;
  const config = {
  actionChains: {
    onLoad: {
      root: "load",
      actions: {
        load: {
          executor: "loadES",
          parameters: {
            esConfig: {
              vbUrl: "https://<visual-builder-host>"
            }
          }
        }
      }
    }
  },
  rules: [
    {
      eventName: "load",
      outcome: "onLoad"
    }
  ]
};
  re.load(config);
</script>

          
         

Domain Restriction

Example script to load the Embedded Service exclusively on permitted domain(s). In this case, the 'allowedUrl' array specifies the host domains where the Embedded Service is allowed to run.

          
<script type="module">
import re from 'https://ee.channels.ocs.oraclecloud.com/re/25.10.0/dist/re.js';
window.re = re;
const config = {
  properties: {
  allowedUrls: [
    "https://<your-allowed-domain>"
    ]
  },
  actionChains: {
    onLoad: {
      root: "checkUrl",
      actions: {
        checkUrl: {
          executor: "if",
          parameters: {
            condition: "[[ Array.isArray(site.properties.allowedUrls) && site.properties.allowedUrls.some((p) => new RegExp(p).test(window.location.href)) ]]"
          },
          outcomes: {
            true: "load"
          }
        },
        load: {
          executor: "loadES",
          parameters: {
            esConfig: {
              vbUrl: "https://<visual-builder-host>"
            }
          }
        }
      }
    }
  },
  rules: [
    {
      eventName: "load",
      outcome: "onLoad"
    }
  ]
};
  re.load(config);
</script>

          
        

DCS Portal

Sample configuration for integrating Embedded Service into DCS Portal. Portal uses a custom update event to update ES context as the user navigates. It also listens for es:linkAction via JET component on-event and event-filter, and invokes the application handler.

portal.site.json

{
  "actionChains": {
    "loadES": {
      "root": "default",
      "actions": {
        "default": {
          "executor": "loadES",
          "parameters": {
            "vbUrl": "https://<visual-builder-host>",
            "screen": { "screenId": "chat" },
            "screens": {
              "chat": {
                "backButton": "hidden",
                "disconnectScreen": { "screenId": "chat" },
                "components": [
                  {
                    "buttonDisplay": "inline",
                    "enabled": "enabled",
                    "id": "chatScreenComponentChat",
                    "launchFormFields": [
                      { "name": "Title", "id": "chatSubject", "enabled": "enabled", "required": true, "persisted": "none", "value": "" },
                      { "name": "FirstName", "id": "chatLaunchFormFieldFirstName", "enabled": "enabled", "required": true, "persisted": "app", "value": "[[ site.properties.firstName ]]" },
                      { "name": "LastName", "id": "chatLaunchFormFieldLastName", "enabled": "enabled", "required": true, "persisted": "app", "value": "[[ site.properties.lastName ]]" },
                      { "name": "Email", "id": "chatLaunchFormFieldEmail", "enabled": "enabled", "required": true, "persisted": "app", "value": "[[ site.properties.email ]]" },
                      { "name": "ServiceRequestNumber", "id": "ServiceRequestNumber", "enabled": "enabled", "required": false, "persisted": "none" },
                      { "name": "Category", "id": "chatLaunchFormFieldCategory", "enabled": "enabled", "required": false, "persisted": "none" },
                      { "name": "Product", "id": "chatLaunchFormFieldProduct", "enabled": "enabled", "required": false, "persisted": "none" }
                    ],
                    "role": "primary",
                    "titleKey": "chatTitle",
                    "type": "chat"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "showES": {
      "root": "default",
      "actions": {
        "default": { "executor": "maximizeES" }
      }
    },
    "updateES": {
      "root": "default",
      "actions": {
        "default": {
          "executor": "updateES",
          "parameters": {
            "context": {
              "serviceRequestNumber": "[[ serviceRequestNumber ]]",
              "categoryId": "[[ categoryId ]]",
              "product": {
                "inventoryItemId": "[[ productItemId ]]",
                "productGroupId": "[[ productGroupId ]]"
              }
            }
          }
        }
      }
    }
  },
  "rules": [
    { "eventName": "load", "outcome": "loadES" },
    {
      "eventName": "click",
      "properties": { "id": "odcs-home-page-chat" },
      "outcome": "showES"
    },
    {
      "eventName": "update",
      "outcome": "updateES",
      "parameters": {
        "serviceRequestNumber": "[[ serviceRequestNumber ]]",
        "categoryId": "[[ categoryId ]]",
        "productItemId": "[[ productItemId ]]",
        "productGroupId": "[[ productGroupId ]]"
      }
    }
  ]
}