Extend Expressional Inference Rule Engine

Info: Bloomreach provides Enterprise support for this feature to Bloomreach Experience customers. The release cycle for this feature may differ from the core product release cycle.

Overview

The Expressional Inference Rule Engine offers a sandboxed expression execution environment, powered by Apache Commons JEXLTM, to enforce security. By default, it restricts property and operation access to only registered (white-listed) objects and function namespaces.

You can extend the Expressional Inference Rule Engine by registering additional objects and function namespaces. This allows integration with custom systems, such as CRM access objects or custom function namespaces.

Add Custom Attributes to the Built-In Root Object

To add custom attribute objects to the built-in root object ($), complete the following steps:

1. Add a Spring bean assembly XML file to the site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/inference/engine/ directory. For example, create my-custom-extensions.xml in this folder.
2. Register all white-listed object class names (fully qualified class names, or FQCNs) in the Spring bean assembly XML file.
3. Register additional attribute object beans in the same XML file.

To register the white-listed object class names, define a org.springframework.beans.factory.config.ListFactoryBean bean named inferenceEngineWhiteSet. List all allowed class names (FQCNs) in this bean.

To register extra attribute objects, define a org.springframework.beans.factory.config.MapFactoryBean bean named inferenceEngineGenericBuiltinModelExtraAttributes. List all attribute name and object pairs in this bean.

The following example demonstrates both configurations:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2018 BloomReach B.V. (http://www.bloomreach.com)
-->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd>

  <!--
    For security, explicitly add any custom class types here to allow their use in expressions.
  -->
  <bean id="inferenceEngineWhiteSet"
        class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
      <list>
        <value>com.onehippo.cms7.inference.engine.demo.integration.FooMarketingAccount</value>
        <value>com.onehippo.cms7.inference.engine.demo.integration.FooMarketingConnector</value>
      </list>
    </property>
  </bean>

  <!--
    Add custom attributes as name-object pairs below.
    Access an attribute in an expression using '$.getAttribute("fooMarketingConnector").getAccount();'
  -->
  <bean id="inferenceEngineGenericBuiltinModelExtraAttributes"
        class="org.springframework.beans.factory.config.MapFactoryBean">
    <property name="sourceMap">
      <map>
        <entry key="fooMarketingConnector">
          <ref bean="fooMarketingConnector" />
        </entry>
      </map>
    </property>
  </bean>

  <!-- SNIP -->

</beans>
copy

Access your custom attributes through the built-in root object ($) in expressions. For example:

var fooMarketingConnector = $.getAttribute("fooMarketingConnector");
var account = fooMarketingConnector.getAcount();
copy

Add Custom Function Namespaces

You can register custom function namespaces to extend expression capabilities. To add custom function namespaces:

1. Add a Spring bean assembly XML file to the site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/inference/engine/ directory. For example, create my-custom-extensions.xml in this folder.
2. Register all white-listed object class names (FQCNs) for your custom function classes in the XML file.
3. Register additional function namespace beans in the same XML file.

To register the white-listed object class names for your custom function classes, add all class names to the org.springframework.beans.factory.config.ListFactoryBean bean named inferenceEngineWhiteSet. Maintain only one inferenceEngineWhiteSet bean in your custom Spring bean assembly XML files, and combine all white-listed class names in this bean.

To register extra function namespaces, define a org.springframework.beans.factory.config.MapFactoryBean bean named inferenceEngineNamespaces. List all function namespace name and object pairs in this bean.

The following example demonstrates this configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2017 Hippo B.V. (http://www.onehippo.com)
-->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd>

  <!--
    For security, explicitly add any custom class types here to allow their use in expressions.
  -->
  <bean id="inferenceEngineWhiteSet"
        class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
      <list>
        <!-- SNIP -->
        <!-- Register your function namespace class name in the white list as well -->
        <value>com.example.util.MyMarketingUtils</value>
      </list>
    </property>
  </bean>

  <!-- SNIP --> 

  <!--
    Add custom function namespaces as name-object pairs below.
    Access a function namespace in an expression using 'mymarketing:getAccountInfo("foo");'
  -->
  <bean id="inferenceEngineNamespaces"
        class="org.springframework.beans.factory.config.MapFactoryBean">
    <property name="sourceMap">
      <map>
        <entry key="mymarketing">
          <ref bean="myMarketingUtils" />
        </entry>
      </map>
    </property>
  </bean>

  <!-- SNIP -->

</beans>
copy

Access your custom function namespaces in standard JEXL expressions. For example:

var accountInfo = mymarketing:getAccountInfo("foo");
copy