Overview

The data stored within an externally hosted JSON feed can be referenced and used within any message body.

Our example

For our example, we'll be using external JSON data consisting of a list of automobiles. Using the tabs below, you can view the HTML and Smarty used in the message, the JSON data being referenced and the rendered output that will display when a message is sent or previewed. Copy and paste the code below into a message and preview or send the message to see the results.

• {$cars=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json')} 
  {foreach $cars as $car}  
   <strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
     ${$car.price}<br> 
    Mileage: {$car.mileage}<br> <br> 
  {/foreach}

• [
      {
        "model": "pilot",
        "brand": "honda",
        "price": 33000,
        "mileage": 100000,
        "id": "01"
      },
      {
        "model": "explorer",
        "brand": "ford",
        "price": 34000,
        "mileage": 39000,
        "id": "02"
      },
      {
        "model": "prius",
        "brand": "toyota",
        "price": 27000,
        "mileage": 66000,
        "id": "03"
      },
      {
        "model": "model s",
        "brand": "tesla",
        "price": 130000,
        "mileage": 56000,
        "id": "04"
      },
      {
        "model": "versa",
        "brand": "nissan",
        "price": 16000,
        "mileage": 94000,
        "id": "05"
      },
      {
        "model": "camary",
        "brand": "toyota",
        "price": 29000,
        "mileage": 310000,
        "id": "06"
      },
      {
        "model": "accord",
        "brand": "honda",
        "price": 24000,
        "mileage": 49000,
        "id": "07"
      }
    ]

• Honda Pilot
  $33000
  Mileage: 100000
  View details
  
  Ford Explorer
  $34000
  Mileage: 39000
  View details
  
  Toyota Prius
  $27000
  Mileage: 66000
  View details
  
  Tesla Model S
  $130000
  Mileage: 56000
  View details
  
  Nissan Versa
  $16000
  Mileage: 94000
  View details
  
  Toyota Camary
  $29000
  Mileage: 310000
  View details
  
  Honda Accord
  $24000
  Mileage: 49000
  View details

getJson method

In order to access remote JSON data within a message, use the getJson method, which is a custom extension of Smarty provided by Cordial.

The getJson method has 3 parameters: url, cacheMinutes and options. They must be written in this order and separated by commas. Only url is required.

For best results, the remote JSON file size should not exceed 1MB in size.

getJson($url, $cacheMinutes, $options)

Set the URL

For the purpose of this example, we hosted the JSON document and included the link below. You can use the example feed in your system for testing.

{$cars=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json')} 

In the example above, a variable cars is assigned to the resulting data set returned from the remote JSON document. The getJson method will get the data from the URL for each message that is rendered per contact.

Set cacheMinutes

A cache can be set in memory for the data so the system doesn't have to request the feed for every individual message. This optimizes the time it takes to compile and send a message as well as reduces the load of the server hosting the data feed (your IT team will thank you). You can specify the number of minutes that the data is stored in memory with this parameter. In the example below, the data would be retrieved from the server 1 time every 20 minutes.

{$cars=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json',20)}

Set options

This parameter allows for the configuration of options.

Set HTTP request headers for authorization

{$coupon=$utils->getJson("http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json", 0, ["headers"=>['Authorization' => 'Basic <base64 encoded username:password>']])}

Basic authentication is currently the only supported authentication method for use with the getJson method.

Set a maximum wait time

This is useful when an external JSON file is not available or taking too long to respond. The timeout option will set a maximum number seconds the system will wait for the data.

In the following example, the request will timeout after 1 second:

{$coupon=$utils->getJson("http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json", 0, ["timeout" => 1])}

The default timeout is 60 seconds. Maximum wait time cannot exceed 60 seconds.

Set a limit on the number of records returned

You can use an integer as the third parameter to limit the number of records returned.

In the following example, the request will return three records:

{$coupon=$utils->getJson("http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json", 0, 3)}

Render data in a message

After the data is available with the getJson method, you can render the data in the message.

Loop through data with {foreach}

A {foreach} statement is the most common way to loop through the data array and render the results in a message.

Example:

{$cars=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json')} 
{foreach $cars as $car}  
 <strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
   ${$car.price}<br> 
  Mileage: {$car.mileage}<br> <br> 
{/foreach}

• Learn more about using the {foreach} statement.

Reference an array index

If you don't need to loop through all of the data in the array, you can render a specific value by referencing its index within the array.

Example:

{$cars=$utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json')} 
<strong>{$cars[0].brand|capitalize} {$cars[0].model|capitalize}</strong><br>
${$cars[0].price}<br> 
Mileage: {$cars[0].mileage}

This example will look in the first record of the data array and render the value for brand, model, price and mileage.

The first item of an array is referenced by 0, the second is 1, the third is 2, and so on.

In the next article, you can learn about getting XML feeds.