1. CPQ
  2. The Snap Language
  3. Configurator Logic

Message Rule

Article last updated:

A Message Rule is a special type of rule that sends data between objects running on your customer's web browser.

  1. If you use a 3D Scene, a message rule can send data from that scene back to the configurator containing it.
  2. If you use the Embed API, a message rule can send data from your configurator back to the web page containing it.

 

Background Context

Why do we need message rules?  Remember, Epicor CPQ's modular structure allows you to build complex UIs from simple components working together.  For example, you can have your own web page contain a configurator, or have that configurator contain a 3D scene within its viewer.  In each case, information flows from parent to child: from the containing object down into the contained object inside it.

But, what if you want information to flow back the other way, from child to parent?  For example, what if the scene needs to tell the configurator about something the user did in the scene? Or, what if the configurator needs to tell the containing web page about some event?  Message rules solve these problems.

 

Visualization

For example, consider this user interface of a web page containing a configurator containing a 3D scene:


That one UI is built by these components nesting together, which have 4 different interactions.


  1. A web page, hosted on your own server, uses the Embed API to display a configurator within it.  The page can pass information into the configurator, such as default values.
  2. A configurator shows a 3D scene inside its viewer.  The configurator automatically passes information into the scene with every field update the user makes, thanks to the Rule Cycle.
  3. Optionally, a message rule in the scene can pass information back into the configurator.
  4. Again optionally, a message rule in the configurator can pass information back into the web page it's embedded within.

Use Cases for Message Rules

Embed API Use Cases

Message rules from the configurator can cause the containing web page to react.  Here are some examples.

  • if a field is updated in the configurator, change the containing web page: have a context message text change. 
  • if the configurator is submitted, change the container page: hide the configurator, and show a "thank you for your order" message to your visitor.
  • if a page changes in the configurator, have the container web page send an analytics beacon so you can learn more about how visitors are moving through your configurator.

3D Scene Use Cases

Message rules from a scene can cause the configurator displaying it to react.

  • if a 3D object in a scene is clicked, inform the configurator so it can display a different page.  (This happens automatically when nested scene objects are clicked, but maybe you want do do that for an item when there's no nested scene.)
  • if a 3D object in a scene is dragged, inform the configurator about the new position of that object.


Message Rule Arguments

Arguments are variables your message rule can gather information from.  You can find these arguments by using the Get/Set variable snap blocks. In this rule type, the Get block exposes these arguments:

Name Type Description
clientLanguage text the two-character code representing the current user's preferred language.
configurator Configurator a handle to the current configurator, if one exists.
environment string "dev" if you are in the development environment, "test" if you are in the test environment, and "prod" if you are in the production environment.
isMobile boolean true, if the viewport seems to have the size of a mobile device.  Use this flag to show something differently on screen if required by a smaller device. 

There are many devices with smaller screens considered mobile devices, and these devices are always changing.  For this reason the isMobile flag is calculated for you: rather than trying to determine if a certain windowHeight or windowWidth would be that of a mobile device, simply read the isMobile flag.
parameters map a map of GET or POST parameters passed into the configurator when it was launched.
message Message Message Rules send messages as key/value pairs, in the format of name=data.  The name is a text string.  The data can be text or numeric.  If you want to send other data types like boolean values or arrays or custom types, cast those values into a test string or JSON first. See example below.
user User the current user.


Message Rule Examples

Basic Example of a Scene Message Rule

The most common use of message rules is to send information from a 3D scene back to its configurator. In this basic example, we'll track how many times a user clicks a specific scene object.

  1. Create your Configurator. Create a number field "ClickCount" to store data from the scene.
  2. Create your 3D scene. Link your scene and configurator together.
  3. Create a clickable mesh.
    In the Scene, create a mesh (such as a box). In the properties pane on the right, ensure "is clickable" is true.
  4. Create a scene rule to send the message.
    In the scene, create a new scene rule with this simple code:

  5. Create a configurator rule to receive the message.
    In the configurator, create a new message rule with this simple code:
  6. Run your cofigurator: you'll see the scene appear beside it. Click the box mesh in the scene to see the click counter increment in the configurator.

 

Detailed Example of a Scene Message Rule

Message rules are more than just sending simple flags! You can send complex data for parsing. Follow this walkthrough to use a message rule to send the user's drag-and-drop information from the scene back to the configurator.

 

Embed API Message Rule: Example 1

In Example 1, we embed our configurator into a parent page:

  • we create a div on our own web page where we want the configurator to appear.
  • we load the embed javascript library, which will allow the embed to work.
  • we run javascript when the page is ready to embed a new configurator into the div.

Here's the HTML for a basic web page, using the Embed API:

Example 1: Basic Embed API
<html>
    <body>
        <div id="viewer"data-kbmax data-configurator-id="25"style="height: 100%;"></div>
        <scriptsrc="https://mycompany-dev.kbmax.com/js-bundles/embed"></script>
        <script>
            //wait until the document loads before using the Epicor CPQ embed api
            document.addEventListener("DOMContentLoaded", function () {
                //instantiate the configurator
                var config = new kbmax.ConfiguratorEmbed({ elementId: "viewer" });
            }); // end of document.addEventListener
        </script>
    </body>
</html>

 

Try it yourself!

You can copy/paste the HTML in these code blocks into a new text file, save that file with an extension of .html, and run it yourself.  Remember to change the "data-configurator-id" and "script src" to point to a configurator and environment you have access to. 

You may want to learn about the Embed API first, before learning about this topic.


Embed API Message Rule: Example 2

The container web page in Example 1 is a nice wrapper around the configurator found in the "viewer" div, but it has no interaction with that configurator.  Let's change that, by adding a message rule. 

  1. First, add a rule to your configurator that will send a message.  For example, you can add it as a value rule (if you want it sent with every change made to the configurator), or as an action button (if you want to send the message only when the user clicks the button).  Regardless, let's send a simple message of the current time.  Add the SendMessage snap block to the rule of your choice:

    We're sending a Message object with the Name = "HelloWorld" and the data = "(the current date-time value on the server, expressed as text)".

    Don't use reserved words

    Ensure your message name is not an HTML or Javascript reserved word.  For example, the example above won't work if you change the message name from "HelloWorld" to "Submit".  A useful list of words to avoid can be found here.

  2. Next, update the HTML and javascript of your container page:  create a listener for messages, and create a place for that listener to write what it heard.

    Example 2: with message listener
    <html>
        <body>
            <div id="theResult">(message value from configurator will appear here)</div>
            <div id="viewer"data-kbmax data-configurator-id="25"style="height: 100%;"></div>
            <scriptsrc="https://mycompany-dev.kbmax.com/js-bundles/embed"></script>
            <script>
                //wait until the document loads before using the Epicor CPQ embed api
                document.addEventListener("DOMContentLoaded", function() {

                   //instantiate the configurator
                   var config = new kbmax.ConfiguratorEmbed({elementId: "viewer"});

                   //listen for any messages
                   config.onMessage.add(function (msg) {
                      if (msg.name == "HelloWorld" ) {
                         document.getElementById("theResult").innerHTML = msg.data;
                      }
                   }

                }); // end of document.addEventListener
            </script>
        </body>
    </html>

     

    In Example 2, we made two additions:

    • we created a second div on the page, with an id of "theResult".
    • we created a config.onMessage.add() line, which will take the data of the HelloWorld message, and write it into our div.


Now, after these two steps, you can see the contents of "theResult" div in the container page be replaced by the data of your "HelloWorld" message.  Depending on the javascript you write in your container page, you can have just about anything happen that javascript can do, not just simple updates like this example.

Embed API Message Rule: Example 3

Note that your Snap blocks are not the only source of messages.  Our platform also sends messages, with names like "pricingDetailsShown" or "pricingDetailsClosed".  Since you can choose which messages you want to pay attention to, these messages may be safely ignored or used as you like. 

Interested in what messages are transmitted? Create some simple javascript on your container page which writes incoming message name and data fields to the log, so you can see what messages are generated when your user performs various actions.

Example 3: generic message listener
<html>
    <body>
        <div id="theResult">(message value from configurator will appear here)</div>
        <div id="viewer"data-kbmax data-configurator-id="25"style="height: 100%;"></div>
        <scriptsrc="https://mycompany-dev.kbmax.com/js-bundles/embed"></script>
        <script>
            //wait until the document loads before using the Epicor CPQ embed api
            document.addEventListener("DOMContentLoaded", function() {

               //instantiate the configurator
               var config = new kbmax.ConfiguratorEmbed({elementId: "viewer"});

               //listen for any messages, and write them to the log
               config.onMessage.add(function (msg) {
                     var str1 = "Epicor CPQ message received: ";
                     console.log(str1.concat(msg.name, "=", msg.data));\}
                  }
               }

            }); // end of document.addEventListener
        </script>
    </body>
</html>

 

Snap rules run in a specific order, and in response to specific events. Learn more about rule execution order.

Was this article helpful?