Zephr User Guide

JSON Features

81 views 0

This guide details how to create a JSON Feature Rule, which you will be able to use to transform a JSON response based upon Zephr Decision outcomes.

Example JSON Content

To use JSON Feature Rules within Zephr you need to set up a Site with a JSON origin. Typically this would be an API that returns JSON content, listing the features available for transformation. Read our Sites guide for more information about setting this up.

Each request to the Zephr decision engine transforms the JSON, replacing the objects with a “featureId” key with the result of Rule configured to match that the “featureId” value.

The following example JSON contains 4 features, and thus 4 targets for decision transformation in a single request.

{
    "popup1": {
       "label": ​"Popup 1"​, 
       "zephrOutput": {
          "featureId": ​"popup1" 
       }
    },
      "ctaBottom1": {
       "label": ​"Rectangular CTA"​, 
       "zephrOutput": {
          "featureId": ​"ctaBottom1" 
       }
    },
    "ctaBottom2": {
       "label": ​"Square CTA"​, 
       "zephrOutput": {
          "featureId": ​"ctaBottom2" 
       }
    },
    "footer": {
       "label": ​"Footer 1"​, 
       "zephrOutput": {
          "featureId": ​"footer1" 
       }
    } 
}

If the Source JSON is hosted at

http://<your-origin>/articleFeatures.json

And a GET request is made to

https://<your-site>.cdn.blaize.io/articleFeatures.json

Then Zephr will proxy the JSON, transforming it according to your configured rules.

Creating a JSON Feature Rule

To create JSON Feature Rule, navigate to Products > Features within you Zephr Admin Console, then click Add a Feature.

Give your rule a Title, then, under Type of Integration, select JSON. Click Continue.

A new rule will open, displaying the Developer Interface. Select if you would like web crawlers to be able to access your content, then, under JSON Configuration, enter the Target Name, Operation, and Target Value for your rule. These inputs allow you to specify the target condition of this rule, which will pick out JSON object(s) the transformation applies to.

JSON Rule Developer Interface 

Example

Let’s say you want to perform a transformation on the following JSON and you want to target the object that contains a field called ‘__typename’ with the value ‘Article’:

{
    "data": {
        "getContentByUrl": {
            "page": {
                "__typename": "Article",
                "title": "This Is A Test Article",
                "body": [
                    {
                        "__typename": "DataBlock",
                        "type": "TEXT",
                        "data": "\"<p><span><span><span><span><span><span>Here is the first paragraph of content.</span></span></span></span></span></span></p>\\n\""
                    },
                    {
                        "__typename": "DataBlock",
                        "type": "TEXT",
                        "data": "\"<p><span><span><span><span><span><span>Here is paragraph number two.</span></span></span></span></span></span></p>\\n\""
                    },
                    {
                        "__typename": "DataBlock",
                        "type": "TEXT",
                        "data": "\"<p><a href=\\\"https://www.example.com/test/test-data/22021/test-data-link\\\"><strong>&gt; Click here to review our sample data.</strong></a></p>\\n\""
                    },
                    {
                        "__typename": "DataBlock",
                        "type": "TEXT",
                        "data": "\"<p><span><span><span><span><span><span>A third paragraph appears!</span></span></span></span></span></span></p>\\n\""
                    },
                    {
                        "__typename": "DataBlock",
                        "type": "TEXT",
                        "data": "\"<p><span><span><span><span><span><span>This is the end of the article.</span></span></span></span></span></span><span><span><span><strong><span><span>evo</span></span></strong></span></span></span><span><span><span><span><span><span> readers is another matter, and with a large choice of circa-300bhp alternatives in the hot hatch class, the M135i xDrive will have to be special indeed to warrant attention</span></span></span></span></span></span></p>\\n\""
                        }
                    ]
                }
            }
        }
    }

Set the Target Name to ‘__typename’, the operation to Equals and the target value to ‘Article’.

__typename equals Article

The target rule will match multiple objects as long as the target condition is met.

Using the same example as above, if you set the target name to ‘__typename’, the operation to Equals and the target value to ‘Datablock’, the transformation will be applied to all 4 objects inside the ‘body’ array.

Once this is set, click Update & Lock, then complete your Feature Rule using our drag and drop rules builder.

JSON Transformations

There are 7 transformations that are available for JSON Feature Rules. They are:

  • No Transformation: Allows access to the content being served by the CMS – no changes will be made.
  • Set String: Allows you to enter a value to set the targeted objects to a string.
  • Set JSON: Allows you to target an object and replace it with a valid JSON object.
  • Set Boolean: Allows you to target an object and replace it with a boolean.
  • Set Number: Allows you to target an object and replace it with a number.
  • Truncate String: Allows you to truncate a string by providing a target property name, and specifying the number of words you wish to truncate at.
  • Truncate Array: Allows you to truncate a string by providing a target property name, and specifying the number of array values you wish to truncate at.

All of the ‘Set’ operations will be applied to the target itself, as they are all object operations. For example, Set String will replace the targeted object with a given string and Set JSON will replace the targeted object with a given JSON entity.

The Truncate Array and Truncate String Transformations will apply to a property of the targeted object.

For example, build your rule, then under Transformations, drag Truncate Array or Truncate String onto your canvas.

A modal will appear, allowing you to set the number of array values, or the number of words you wish to truncate. You can also specify the name of the property.

Truncate Array Example

The following example truncates the body array to 2 elements.

Sample Rule:

Example Rule - Truncate Array

Sample Transformation: 

{
    "data": {
       "getContentByUrl": {
          "page": {
             "__typename": "Article",
             "title": "This Is A Test Article",
             "body": [
                {
                   "__typename": "DataBlock",
                   "type": "TEXT",
                   "data": "\"<p><span><span><span><span><span><span>Here is the first paragraph of content.</span></span></span></span></span></span></p>\\n\""
                },
                {
                   "__typename": "DataBlock",
                   "type": "TEXT",
                   "data": "\"<p><span><span><span><span><span><span>Here is paragraph number two.</span></span></span></span></span></span></p>\\n\""
                   }
                ]
             }
          }
       }
    }

As you can see above, the JSON returns 2 Data Blocks, rather than the original 4 in the JSON, due to the Truncate Array transformation we applied.