Overview

This page includes all of Cordial's custom Smarty utilities that allow you to read and write data and simplify complex personalization rules. 

Data and Message Automations

deleteSupplementRecord

Deletes a supplement record from the supplement collection using Smarty. If the target supplement record does not exist, the utility will not interrupt script execution.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->deleteSupplementRecord($supplementKey*, $supplementID*)}

• HTML & Smarty
• Rendered Output
• Parameters

{$record.supplementKey = 'automobiles'}
{$record.supplementId = 1}

{$record.data = $utils->deleteSupplementRecord($record.supplementKey, $record.supplementId)}

{if $record.data}
Supplement record <strong>{$record.SupplementId}</strong> was deleted from the <strong>{$record.SupplementKey}</strong> supplement collection.
{else}
The record was not deleted.
{/if}

distanceBetweenPostalCodes

Calculates the distance between two postal codes for rendering content based on that distance.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->distanceBetweenPostalCodes($zip1*, $zip2*, $units, $countryZip1, $countryZip2)}
• Learn more about distanceBetweenPostalCodes

• HTML & Smarty
• Rendered Output
• Examples
• Parameters

{$distance.zip1 = '35244'}
{$distance.zip2 = '92109'}

{$distance.data = $utils->distanceBetweenPostalCodes($distance.zip1, $distance.zip2)}

{if $distance.data !== 0}
  Distance = {$distance.data}          
{/if}

<h2>Debug $distance</h2>
{$utils->jsonPrettyPrint($distance)}

{
    "zip1": 35244,
    "zip2": 92109,
    "data": "1756.88"
}

{$distance.zip1 = $contact.address.postal_code}
{$distance.zip2 = '92131'}

{$distance.data = $utils->distanceBetweenPostalCodes($distance.zip1, $distance.zip2)}

{if $distance.data < 200 && $distance.data !== 0}
Marketing content
{else}
Default content
{/if}

{$distance.zip1 = '92107'}
{$distance.zip2 = 'V6R'}
{$distance.units = 'miles'}
{$distance.countryZip1 = 'US'}
{$distance.countryZip2 = 'CA'}

{$distance.data = $utils->distanceBetweenPostalCodes($distance.zip1, $distance.zip2, $distance.units, $distance.countryZip1, $distance.countryZip2)}

{if $distance.data !== 0}
  Distance = {$distance.data}          
{/if}

<h2>Debug $distanceh2</h2>
{$utils->jsonPrettyPrint($distance)}

getConvertedDate

Using the getConvertedDate utility, you are able to convert a given date and time to a different time zone.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getConvertedDate(date*, TOtz*, FROMtz*, format*)}

• HTML & Smarty
• Rendered Output
• Parameters

{$convertDate.date = '2020-05-01T18:57:20Z'}
{$convertDate.to = 'America/Los_Angeles'}
{$convertDate.from = 'UTC'}
{$convertDate.format = 'F d Y h:i:s A'}

{$convertDate.data = $utils->getConvertedDate($convertDate.date, $convertDate.to, $convertDate.from, $convertDate.format)}

<strong>Date in UTC:</strong> {$convertDate.date}<br>
<strong>Date Converted to LA:</strong> {$convertDate.data}

getDistanceBetweenCoordinates

Calculates the distance between two points on the map using longitude and latitude coordinates, and renders the output in miles or kilometers. Message content can then be rendered based on the geographic area within the given distance.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getDistanceBetweenCoordinates($latitude1*, $longitude1*, $latitude2*, $longitude2*, $units)}

{$distance.lat_1 = 44.1793}
{$distance.lon_1 = -72.4731}
{$distance.lat_2 = 32.9014}
{$distance.lon_2 = -117.2079}
{$distance.units = 'miles'}

{$distance=$utils->getDistanceBetweenCoordinates($distance.lat_1, $distance.lon_1, $distance.lat_2, $distance.lon_2, $distance.units)}

The distance between 44.1793, -72.4731 and 32.9014, -117.2079 coordinate points is <strong>{$distance}</strong> miles.

{$distance.zip_a = 92121}
{$distance.zip_b = 92115}
{$distance.lat_long_a = $utils->getCoordinatesFromZip($distance.zip_a, "US")}
{$distance.lat_long_b = $utils->getCoordinatesFromZip($distance.zip_b, "US")}

{$distance.BetweenCoordinates = $utils->getDistanceBetweenCoordinates($distance.lat_long_a.latitude, $distance.lat_long_a.longitude, $distance.lat_long_b.latitude, $distance.lat_long_b.longitude, 'miles')}

<h2>Debug $distance</h2>
{$utils->jsonPrettyPrint($distance)}

        {
    "zip_a": 92121,
    "zip_b": 92115,
    "lat_long_a": {
        "latitude": "32.9014",
        "longitude": "-117.2079"
    },
    "lat_long_b": {
        "latitude": "32.7555",
        "longitude": "-117.0701"
    },
    "BetweenCoordinates": "12.87"
}
        

getEventRecords

Data stored within the contact activities collection can be referenced and used within any message body.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getEventRecords($eventName*, $newerThan, $properties, $limit, $sort)}
• Learn more about getEventRecords

{$events.eventName = 'browse'}
{$events.newerThan = ''}
{$events.properties = []}
{$events.limit = 2}
{$events.sort = []}

{$events.data = $utils->getEventRecords($events.eventName, $events.newerThan, $events.properties, $events.limit, $events.sort)}

<strong>Items You Browsed</strong><br><br>
{foreach $events.data as $item}
  {$item.properties.title|capitalize}<br>
  ${$item.properties.price} <br>
  {$item.properties.description|capitalize} <br>
  {$item.properties.url} <br><br>
{/foreach}

<h2>Debug events</h2>
{$utils->jsonPrettyPrint($events)}

[
  {
    "eventName": "browse",
    "newerThan": "",
    "properties": [],
    "limit": 2,
    "sort": [],
    "data": [
      {
        "cID": "58d2fc99ac0c8117814d4e78",
        "_id": "59014a9608ab4e356ec0706a",
        "properties": {
          "title": "khaki shirt",
          "url": "http://example.com/shirt",
          "price": 9.99,
          "description": "a really cool khaki shirt"
        },
        "action": "browse",
        "time": "2017-04-27T01:34:13+0000",
        "email": "fredgarvin@gmail.com"
      },
      {
        "cID": "58d2fc99ac0c8117814d4e78",
        "_id": "59014a9608ab4e356ec0706a",
        "properties": {
          "title": "khaki pants",
          "url": "http://example.com/pants",
          "price": 19.99,
          "description": "awesome khaki pants"
        },
        "action": "browse",
        "time": "2017-04-27T01:37:13+0000",
        "email": "fredgarvin@gmail.com"
      }
    ]
  }
]
               

{$events.newerThan = '2020-08-19T21:36:13+0000'}

{$events.newerThan = '-1 day'|date_format:'Y-m-d\TH:i:sO'}

{$lastSend.templateKey = 'automation_key'}
{$lastSend.date = $utils->lastSendTimestamp($lastSend.templateKey)}

{$events.newerThan = $lastSend.date|date_format:'Y-m-d\TH:i:sO'}

{$events.properties = ['category'=>'shoes','brand'=>'nike']}

{$events.sort = ['column'=>'ats','direction'=>'DESC']}

getJson

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

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getJson($url*, $cacheMinutes, $options)}
• Learn more about getJson

• HTML & Smarty
• Rendered Output
• Setting the Options
• Parameters

{$json_feed.url = 'http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json'}
{$json_feed.cacheMinutes = 10}
{$json_feed.options = []}

{$json_feed.data = $utils->getJson($json_feed.url, $json_feed.cacheMinutes, $json_feed.options)}

{foreach $json_feed.data as $car}  
 <strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
   ${$car.price}<br>
  Mileage: {$car.mileage}<br><br>
{/foreach}

<h2>Debug $json_feed</h2>
{$utils->jsonPrettyPrint($json_feed)}

{
  "url": "http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json",
  "cacheMinutes": 10,
  "options": {
    "timeout": 1
  },
  "data": [
    {
      "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"
    }
  ]
}

{$json_feed.options = ['headers'=>['Authorization' => 'Basic <base64 encoded username:password>']]}

{$json_feed.options = ['timeout' => 1]}

{$json_feed.options = 3}

getMicroNow

Similar to the getNow utility, you can render the current time for a specified time zone, with the addition of microseconds.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getMicroNow($tzId, $format)}

• HTML & Smarty
• Rendered Output
• Parameters

{$getMicroNow.tzId = 'UTC'}
{$getMicroNow.format = 'U.u'}

{$getMicroNow.data = $utils->getMicroNow($getMicroNow.tzId, $getMicroNow.format)}

<strong>Time since Unix epoch with microseconds:</strong><br>
{$getMicroNow.data}

<h2>Debug $getMicroNow</h2>
{$utils->jsonPrettyPrint($getMicroNow)}

{
    "tzId": "UTC",
    "format": "U.u",
    "data": "1590861373.977000"
}

getNow

Using the getNow utility, you can render the current time for a specified time zone when the template is compiled.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getNow($tzId, $format)}
• Learn more about getNow

• HTML & Smarty
• Rendered Output
• Examples
• Parameters

{$getNow.tzId = 'America/Los_Angeles'}
{$getNow.format = 'Y-m-d\TH:i:sO'}

{$getNow.data = $utils->getNow($getNow.tzId, $getNow.format)}

<strong>Curent time:</strong><br>
{$getNow.data}

<h2>Debug $getNow</h2>
{$utils->jsonPrettyPrint($getNow)}

{
    "tzId": "America\/Los_Angeles",
    "format": "Y-m-d\\TH:i:sO",
    "data": "2020-04-27 13:30:57"
}

{$getNow.tzId = $account.timezone}
{$getNow.format = 'Y'}

{$getNow.data = $utils->getNow($getNow.tzId, $getNow.format)}

© {$getNow.data} Example Company

{$getNow.tzId = $contact.address.tz}
{$getNow.format = 'Y-m-d\TH:i:sO'}

{$getNow.data = $utils->getNow($getNow.tzId, $getNow.format)}

Time unique to the contact: {$getNow.data}

getOrders

Data stored within the orders collection can be referenced and used within any message body.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getOrders($query, $limit, $sort)}
• Learn more about getOrders

• HTML & Smarty
• Rendered Output
• Queries & Sorting
• Parameters

{$orders.query = []}
{$orders.limit = 1}
{$orders.sort = []}

{$orders.data = $utils->getOrders($orders.query, $orders.limit, $orders.sort)}

{foreach $orders.data as $order}
  <b>OrderID {$order.orderID}</b><br>
  Purchase Date - {$order.purchaseDate|date_format}<br><br>
   {foreach $order.items as $orderitem}
        Product {$orderitem.productID}<br>
        {$orderitem.description|capitalize} - ${$orderitem.amount|string_format:'%.2f'}<br>
        Size - {$orderitem.attr.size}<br>
        Color - {$orderitem.attr.color}<br><br>
   {/foreach}
  Total Amount - ${$order.totalAmount}<br><br>
  Shipping Address:<br>
  {$order.shippingAddress.name|capitalize}<br>
  {$order.shippingAddress.address|capitalize}<br>
  {$order.shippingAddress.city|capitalize} {$order.shippingAddress.state|capitalize} {$order.shippingAddress.postalCode}<br><br>
{/foreach}

<h2>Debug $orders</h2>
{$utils->jsonPrettyPrint($orders)}

[
  {
    "query": [],
    "limit": 1,
    "sort": [],
    "data": [
      {
        "cID": "58d2fc99ac0c8117814d4e78",
        "orderID": "001",
        "purchaseDate": "2015-01-10T01:47:43+0000",
        "shippingAddress": {
          "name": "fred garvin",
          "address": "555 truss St",
          "city": "san diego",
          "state": "ca",
          "postalCode": "92108",
          "country": "usa"
        },
        "billingAddress": {
          "name": "fred garvin",
          "address": "555 truss st",
          "city": "san diego",
          "state": "ca",
          "postalCode": "92108",
          "country": "usa"
        },
        "items": [
          {
            "productID": "111",
            "description": "khaki shorts",
            "sku": "1212",
            "category": "shorts",
            "name": "khaki shorts",
            "qty": 1,
            "itemPrice": 19.99,
            "amount": 19.99,
            "attr": {
              "color": "tan",
              "size": "large"
            }
          },
          {
            "productID": "222",
            "description": "khaki pants",
            "sku": "1213",
            "category": "pants",
            "name": "khaki pants",
            "qty": 1,
            "itemPrice": 29.99,
            "amount": 29.99,
            "attr": {
              "color": "tan",
              "size": "large"
            }
          }
        ],
        "tax": 0,
        "totalAmount": 49.98
      }
    ]
  }
]

{$orders.query = ['orderID"=>'002']}

{$orders.query = ['items'=>['productID'=>'111']]}

{$orders.query = ['purchaseDate'=>['gt'=>'2016-01-09'],'shippingAddress.city'=>'san diego']}

{$orders.sort = ['column'=>orderID,'direction'=>'DESC']}

getProducts

Data stored within the products collection can be referenced and used within any message body.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getProducts($query, $limit, $sort, $cacheMinutes)}
• Learn more about getProducts

• HTML & Smarty
• Rendered Output
• Queries & Sorting
• Parameters

{$products.query = []}
{$products.limit = 2}
{$products.sort = []}
{$products.cacheMinutes = 20}

{$products.data = $utils->getProducts($products.query, $products.limit, $products.sort, $products.cacheMinutes)}

{foreach $products.data as $product}  
  <strong>{$product.productName|capitalize}</strong> - ${$product.price}<br><br>
  {foreach $product.variants as $variant}
    Color: {$variant.attr.color}<br>
    Size: {$variant.attr.size}<br>
    Sku: {$variant.sku}<br><br>
  {/foreach}
{/foreach}

<h2>Debug $products</h2>
{$utils->jsonPrettyPrint($products)}

[
  {
    "query": [],
    "limit": 2,
    "sort": [],
    "cacheMinutes": 20,
    "data": [
      {
        "productID": "1172",
        "productName": "skirt",
        "price": 19.99,
        "variants": [
          {
            "sku": "111",
            "attr": {
              "color": "blue",
              "size": "small"
            }
          },
          {
            "sku": "112",
            "attr": {
              "color": "blue",
              "size": "medium"
            }
          }
        ]
      },
      {
        "productID": "1173",
        "productName": "shorts",
        "price": 29.99,
        "variants": [
          {
            "sku": "221",
            "attr": {
              "color": "green",
              "size": "small"
            }
          },
          {
            "sku": "222",
            "attr": {
              "color": "green",
              "size": "medium"
            }
          }
        ]
      }
    ]
  }
]

{$products.query = ['price'=>['between'=>['start'=>10,'end'=>30]]]}

{$products.query = ['productID'=>['in' => [123,1234]]]}

{$products.query = ['productID'=>['notIn' => [123,1234]]]}

{$products.query = ['price'=>['lt'=>39]]}

{$products.sort = ['column'=>'price','direction'=>'DESC']}

getRaw

The getRaw utility allows you to retrieve unfiltered HTML from a file on an external server. The retrieved content is unprocessed and can be inserted anywhere in your message body. Can be used to include content such as product recommendations.

• Used in:   Message Automations   Data Automations
• Syntax: {$supplements->getRaw($url*, $cacheMinutes)}

• HTML & Smarty
• HTML File
• Rendered Output
• Parameters

{$raw.url = 'https://example.com/55788/sunglasses.htm'}
{$raw.cacheMinutes = 20}

{$raw.data = $supplements->getRaw($raw.url, $raw.cacheMinutes)}

<h2>Display HTML:</h2>
{$raw.data}

This is the raw HTML within the sunglasses.htm file.

<table width="579" cellspacing="0" cellpadding="0" border="0" align="center">
<tbody>
<tr>
<td style="font-family: arial, san-serif; text-align: center; padding: 10px; color: #666; font-size: 14px; line-height: 22px;">QUAY AUSTRALIA<br>Retro and modern influences merge seamlessly on lightweight sunglasses featuring tortoiseshell frames and flashy mirrored lenses.
</td>
<td><img src="https://example.com/files/products/3467238.jpg"></td></tr></tbody></table>

Display HTML:

QUAY AUSTRALIA Retro and modern influences merge seamlessly on lightweight sunglasses featuring tortoiseshell frames and flashy mirrored lenses.

Parameter	Description	Required	Expected	Default
url	URL for the HTML resource.	required	valid URL	NA
cacheMinutes	Number of minutes to store the retrieved data in memory. This optimizes send time if the system doesn't have to request the data for every individual message.	optional	integer	10

getSessionStore

Returns data stored in a previous action for use in the current action within a Podium orchestration.

• Used in:   Message Automations   Data Automations
• Syntax: {$data = $utils->getSessionStore()}

{$coupon = '12345'}
<h1>{$coupon}</h1>
{$utils->updateSessionStore($coupon)}

{$coupon = $utils->getSessionStore()}
<h1>{$coupon}</h1>

Here is your coupon code: <strong>{$coupon.code}</strong>

getSimpleXML

Data stored within an externally hosted XML feed can be referenced and used within any message body.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getSimpleXML($url*, $cacheMinutes)}
• Learn more about getSimpleXML

{$xml.url = 'http://p13.zdassets.com/hc/theme_assets/656597/200049057/simpleXML_example_1.xml'}
{$xml.cacheMinutes = 20}

{$xml.data = $utils->getSimpleXML($xml.url, $xml.cacheMinutes)}

<h1>{$xml.data->channel->title}</h1>
{foreach $xml.data->channel->item as $record}
  <h2>{$record->title}</h2>
  {$record->link}<br>
  {$record->description}<br><br>
{/foreach}

<rss version="2.0">
<channel>
  <title>Classic Albums</title>
  <link>https://www.example.com</link>
  <description>A list of classic albums.</description>
  <item>
    <title>Fleetwood Mac - Rumours</title>
    <link>http://fleetwoodmac.com</link>
    <description>Rumours tends to be remembered as the album that was characterized by personal strife between the band members.</description>
  </item>
  <item>
    <title>Pink Floyd - Dark Side of the Moon</title>
    <link>http://www.pinkfloyd.com/</link>
    <description>No-one in March 1973 could have imagined that an album released in that month would still be thrilling listeners 38 years later, but it's true. </description>
  </item>
</channel>
</rss>

getSupplementRecords

Data stored within a supplement can be referenced and used within any message body.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->getSupplementRecords($key*, $query, $limit, $sort, $cacheMinutes)}
• Learn more about getSupplementRecords

{$supplement_records.key = 'automobiles'}
{$supplement_records.query = []}
{$supplement_records.limit = 25}
{$supplement_records.sort = []}
{$supplement_records.cacheMinutes = 25}

{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key, $supplement_records.query, $supplement_records.limit, $supplement_records.sort, $supplement_records.cacheMinutes)}

{foreach $supplement_records.data as $car}  
  <strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
  ${$car.price}<br>
  Mileage: {$car.mileage}<br><br>
{/foreach}

<h2>Debug $supplement_records</h2>
{$utils->jsonPrettyPrint($supplement_records)}

[
  {
    "key": "automobiles",
    "query": [],
    "limit": 25,
    "sort": [],
    "cacheMinutes": 25,
    "data": [
      {
        "model": "pilot",
        "brand": "honda",
        "price": "33000",
        "milage": "100000",
        "ct": "2020-04-15T04:32:49+0000",
        "lm": "2020-04-15T04:32:49+0000",
        "id": "1"
      },
      {
        "model": "explorer",
        "brand": "ford",
        "price": "34000",
        "milage": "39000",
        "ct": "2020-04-15T04:32:49+0000",
        "lm": "2020-04-15T04:32:49+0000",
        "id": "2"
      }
    ]
  }
]

{$supplement_records.query = ['price'=>['between'=>['start'=>10000,'end'=>50000]]]}

{$supplement_records.query = ['date'=>['lt'=>{$smarty.now|date_format:'%Y-%m-%dT%H:%M:%S+0000'}],'date'=>['gt'=>{'2020-10-10T22:21:18+0000'}]]}

{$supplement_records.query = ['brand'=>['notIn' => [toyota,honda]]]}

{$supplement_records.query = ['colors' => ['array_contains' => 'black']]}

{$supplement_records.sort = ['column'=>'lm','direction'=>'DESC']}

jsonPrettyPrint

You can use the jsonPrettyPrint Smarty utility to view all data available from the get methods within the message preview.

For example, you can retrieve all product data in message preview by pasting the following code in the HTML editor and clicking the Preview button.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->jsonPrettyPrint($object*)}

{$products=$utils->getProducts()} 
{$utils->jsonPrettyPrint($products)}

[
  {
    "_id": "5668084929aa544d754bd640",
    "productID": "09990",
    "productName": "Shirts for Men",
    "productType": "physical",
    "manufacturerName": "Cordial Threads",
    "accountID": "45",
    "lm": "2015-12-09T10:54:01+0000",
    "ct": "2015-12-09T10:54:01+0000"
  },
  {
    "_id": "56b2fb56733462ca89f52f3c",
    "productID": "TB111",
    "category": "Performance Wear",
    "productName": "Adult Medium Cut Brief",
    "price": 16.66,
    "variants": [
      {
        "sku": "TB111",
        "attr": ""
      }
    ],
    "accountID": "45",
    "lm": "2016-02-04T07:18:46+0000",
    "ct": "2016-02-04T07:18:46+0000"
  }
]

This will work for all data utilities, as well as retrieving contact attribute data.

lastSendTimestamp

The lastSendTimestamp utility allows you to render the last send date of a specified automation template.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->lastSendTimestamp($templateKey*)}
• Learn more about lastSendTimestamp

• HTML & Smarty
• Rendered Output
• Parameters

{$lastSend.templateKey = 'order-confirmation'}

{$lastSend.date = $utils->lastSendTimestamp($lastSend.templateKey)}

Message last sent: {$lastSend.date|date_format:'Y-m-d\TH:i:sO'};

renderInfo

A utility that renders automation metadata. Useful for setting conditional statements based on the rendering engine in use. Allows for execution of automation scripts that are reusable across message and data automations. The metadata object contains the automation name (Message Automation or Data Automation) and preview (true or false) key-value pairs.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->renderInfo()}

{$metadata = $utils->renderInfo()}

<h2>Debug $metadata</h2>
{$utils->jsonPrettyPrint($metadata)}

{
    "name": "Data Automation",
    "preview": true
}

{$data.metadata = $utils->renderInfo()}

{if $data.metadata.name == 'Message Automation'}
  {$data.info[] = 'We are in Message Automation, stopMessage can run'}
  {if $contact.city == 'San Diego'}{stopMessage}{/if}
{else}
  {$data.info[] = 'We are in Data Automation, stopMessage can NOT run'}
{/if}

{if $data.metadata.name == 'Message Automation' and $data.metadata.preview == true}
  <h2>Debug $data</h2>
  {$utils->jsonPrettyPrint($data)}
{elseif $data.metadata.name == 'Data Automation' and $data.metadata.preview == true}
  <h2>Debug $data</h2>
  {$utils->jsonPrettyPrint($data)}
{/if}

{
  "metadata": {
    "name": "Data Automation",
    "preview": true
  },
  "info": [
    "We are in Data Automation, stopMessage can NOT run"
  ]
}

setContact

Sets a contact object for which the transformation is to be carried out. Once set, the contact object is accessible to utilities and Smarty functions that rely on contact data for the remainder of the transformation. Subsequent instances of setContact will unset the preceding contact object, allowing for execution of consecutive context-sensitive and contact-dependent transformations. Also useful for providing the cID value when targeting contact data using utilities such as updateSupplementRecord.

• Used in:    Message Automations   Data Automations
• Syntax: {$utils->setContact($lookup_key*)}

{$contact = $utils->setContact('email:msmith@example.com')}
{* Contact object is msmith@example.com for the followng context *}

{$mdtKey = 'messageKey'}
{$order = [..list of attributes..]}

{if !empty($contact)}
{$utils->sendMessage($mdtKey)}
{$utils->upsertOrder($order)}    
{/if}

{$contact = $utils->setContact('cID:58d2fc99ac0c8117814d4e78')}
{* Contact object has been changed to 58d2fc99ac0c8117814d4e78 for the followng context *}

{if !empty($contact)}
{$utils->sendMessage($mdtKey)}
{$utils->upsertOrder($order)}
{/if}

sortArray

Cordial provides a custom Smarty utility to sort an array of data in a message. This is useful if you need to sort an array of data after it is retrieved using a "get" method.

The example below shows the sortArray utility in conjunction with the getJson utility to sort the list of cars by price in ascending order.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->sortArray($arrayName, $column_name, $sort)}
• Learn more about sortArray

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

{$sorted = $utils->sortArray($json_feed.data, 'price', 'asc')}

{foreach $sorted as $car}  
<strong>{$car.brand|capitalize} {$car.model|capitalize}</strong>
  ${$car.price}<br>
  Mileage: {$car.mileage}<br>
  ID: {$car.id}<br><br>
{/foreach}

[
  {
    "model": "prius",
    "brand": "toyota",
    "price": 27000,
    "mileage": 66000,
    "id": "03"
  },
  {
    "model": "versa",
    "brand": "nissan",
    "price": 16000,
    "mileage": 94000,
    "id": "05"
  },
  {
    "model": "accord",
    "brand": "honda",
    "price": 24000,
    "mileage": 49000,
    "id": "07"
  }
]

strContains

The strContains utility can be used to find a string of characters within another string of characters.

Our example uses the utility to check if fire exists in firestorm, and then prints the result with an {if} statement.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->strContains($lookup_str*, $string*, $caseSensitive)}
• Learn more about strContains

{$contains.lookup_str = 'Fire'}
{$contains.string = 'firestorm'}
{$contains.caseSensitive = true}

{if $utils->strContains($contains.lookup_str, $contains.string, $contains.caseSensitive)}
  {$contains.found = true}
{else}
  {$contains.found = false}
{/if}

{$utils->jsonPrettyPrint($contains)}

{
  "lookup_str": "Fire",
  "caseSensitive": true,
  "found": false
}

updateContact

Updates an existing contact record in the Cordial database using the supplied data. Cannot be used to create new contact records. In this example, we are using the setContact utility to look up an existing contact record and then pass update data using the updateContact utility.

• Used in:   Message Automations   Data Automations
• Syntax: {$utils->updateContact($data*, $waitForResult, $suppressTriggers, $forceSubscribe)}

{$lookup_key = 'email:msmith@example.com'}
{$contactRecord = $utils->setContact($lookup_key)}

{$updateRecord.data = ['last_name'=>'Smith', 'age' => ['inc' =>'+1']]} 
{$updateRecord.waitForResult = true} 
{$updateRecord.suppressTriggers = true}
{$updateRecord.forceSubscribe = false}
      
{if !empty($contactRecord)} 
{$contactRecord = $utils->updateContact($updateRecord.data, $updateRecord.waitForResult, $updateRecord.suppressTriggers, $updateRecord.forceSubscribe)}
{/if} 

Contact Age: {$contact.age}<br>
Last Name: {$contact.last_name}

<h2>Debug $updateRecord</h2> 
{$utils->jsonPrettyPrint($updateRecord)}

{
    "data": {
        "last_name": "Smith",
        "age": {
            "inc": "+1"
        }
    },
    "waitForResult": true,
    "suppressTriggers": true,
    "forceSubscribe": false
}

{$lookup_key = 'email:msmith@example.com'}
{$contactRecord = $utils->setContact($lookup_key)}

{$channelKey = 'email'}
{$subscribeStatus = 'subscribed'}

{$updateRecord.waitForResult = true} 
{$updateRecord.suppressTriggers = true}
{$updateRecord.forceSubscribe = true}

{$contactRecord = $utils->updateContact(["channels.$channelKey.subscribeStatus" => $subscribeStatus], $updateRecord.waitForResult, $updateRecord.suppressTriggers, $updateRecord.forceSubscribe)}

{$utils->jsonPrettyPrint($contactRecord)}

{$clickEvents.eventName = 'click'}
{$clickEvents.newerThan = '-600 days'|date_format:'%Y-%m-%dT%H:%M:%S+0000'}
{$clickEvents.properties = []}
{$clickEvents.limit = 1}
{$clickEvents.sort = ['column'=>'ats','direction'=>'DESC']}
{$clickEvents.data = $utils->getEventRecords($clickEvents.eventName, $clickEvents.newerThan, $clickEvents.properties, $clickEvents.limit, $clickEvents.sort)}{$write.data.lastClick = $clickEvents.data.0.ats}

{if not empty($write.data.lastClick)}
  {* We have new data to write *}
  {$write.data.channels.email.address = $contact.channels.email.address} {* need to set Primary Key *}
  {$write.data.lastetldate = $utils->getNow('UTC', 'Y-m-d\TH:i:sO')} {* remember the last time We ETLed this record *}

  {if not $block_update}
    {$write.waitForResults = true}
    {$write.suppressTriggers = true}
    {$result_of_write = $utils->updateContact($write.data, $write.waitForResults, $write.suppressTriggers)}
  {/if}
{/if}

{if $debug}
  <h2>Debug $write</h2>
  {$utils->jsonPrettyPrint($write)}  
<h2>Debug $clickEvents</h2>
  {$utils->jsonPrettyPrint($clickEvents)}  
<h2>Debug $contact</h2>
  {$utils->jsonPrettyPrint($contact)}
{/if}

updateSupplementRecord

Updates an existing supplement record within the specified supplement collection.

{$contact = $utils->setContact('msmith@example.com')}
{$supplement.writeData.cID = $contact._id}

• Used in:   Message Automations   Data Automations
• Syntax: {$supplements->updateSupplementRecord($supplementKey*, $data*)}

• HTML & Smarty
• JSON
• Rendered Output
• Parameters

{$supplement.key = 'automobiles'}
{$supplement.writeData.id = 2}
{$supplement.writeData.price = '36000'}
{$supplement.writeData.milage = '100'}
{$supplement.writeData.model = 'explorer'}
{$supplement.writeData.brand = 'ford'}

{$supplement.automobiles = $supplements->updateSupplementRecord($supplement.key, $supplement.writeData)}

<h2>Debug $supplement</h2>
{$utils->jsonPrettyPrint($supplement)}

[
  {
        "model": "explorer",
        "brand": "ford",
        "price": "34000",
        "milage": "39000",
        "ct": "2020-04-15T04:32:49+0000",
        "lm": "2020-04-15T04:32:49+0000",
        "id": "2"
  }
]

{
    "key": "automobiles",
    "writeData": {
        "id": 2,
        "price": "36000",
        "milage": "100"
    },
    "automobiles": {
        "_id": "2",
        "model": "explorer",
        "brand": "ford",
        "price": "36000",
        "milage": "100",
        "ct": "2020-04-15T04:32:49+0000",
        "lm": "2020-06-15T21:26:48+0000",
        "_action": "updated"
    }
}

Data Automations Only

addEvent

Adds a custom event to the events data collection and associates it to specific contact(s).

• Used in:   Data Automations
• Syntax: {$utils->addEvent($a*, $UID, $contact_identifier*, $ats, $properties)}

{$event=$utils->addEvent([
    'a' => 'browse', 
    'UID' => '', 
    'email' => 'msmith@example.com', 
    'ats' => '2018-12-18T17:50:25+0000',
    'properties' => [
        'category' => 'Shirts',
        'url' => 'http://example.com/shirts',
        'description' => 'A really cool khaki shirt.',
        'price' => 9.99,
        'title' => 'Khaki Shirt'
    ]
])}; 

<h2>Debug $event</h2>
{$utils->jsonPrettyPrint($event)}

{
    "success": true,
    "messages": "created"
}

addExportRecord

Used to add a record to one or more of the pre-initialized export files (via UI). Dynamically build a collection of data records that will be processed in the data transformation and exported to the target file. Multiple instances of addExportRecord can be added to a single transformation to add data rows at varying states of the transformation or to create separate export files using unique file identifiers.

• Used in:   Data Automations
• Syntax: {$utils->addExportRecord($file_identifier*, $row*)}

{$supplement_records.key = 'automobiles'}
{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key)}

{foreach $supplement_records.data as $car}  
{$export_record.file_identifier = 'CoolCarsExport'}
{$utils->addExportRecord($export_record.file_identifier, ['brand' => $car.brand, 'price' => $car.price])}
{/foreach}

{$products.query = ['productID'=>['in' => [123,1234]]]}
{$products.data = $utils->getProducts($products.query)}

{foreach $products.data as $product}  
{$export_record.file_identifier = 'CoolProductsExport'}
{$utils->addExportRecord($export_record.file_identifier, ['product name' => $product.productName, 'product price' => $product.productID])}
{/foreach}

{* debug flag(s) *}
{* set value to 0 when ready to go live *}
{$block_update = 1} 

{* get metadata about this automation *}
{$data.metadata = $utils->renderInfo()}

{* settings *}
{$export.file_identifier = 'my_export_name'}

{* data transformation *}
{foreach $contact as $attr => $value}
  {* now, we build up a data record to export; can perform transformations in this codeblock *}
  {$export.data[$attr] = $value}
{/foreach}

{* add row to export *}
{if not $block_update and not empty($export.data)}
  {$utils->addExportRecord($export_record.file_identifier, $export.data)}}  
{/if}

{* debug output *}
{if $data.metadata.preview}
  <h2>Debug <code>$contact</code></h2>
  {$utils->jsonPrettyPrint($contact)}
  <h2>Debug <code>$export.data</code></h2>
  {$utils->jsonPrettyPrint($export.data)}
{/if}

createTmpSupplementVersion

Creates an empty, structurally identical copy of an existing supplement collection. The temporary version inherits the name, options, and index fields of the original, making it fully compatible to accept the same data types.

• Used in:   Data Automations
• Syntax: {$utils->createTmpSupplementVersion('existing_collection_name')}
• Learn more about swapping supplements.

{* in preview mode createTmpSupplementVersion does not run *}
{$utils->createTmpSupplementVersion('existing_collection_name')}

deleteTmpSupplementVersion

This utility provides the means for clearing temporary supplement collection data in the event of a critical swap supplement data job failure. There are only a handful of instances when this utility should be used and always with consultation from the Cordial Solutions Engineering team.

• Used in:   Data Automations
• Syntax: {$utils->deleteTmpSupplementVersion('existing_collection_name')}
• Learn more about swapping supplements.

{* If running deleteTmpSupplementVersion, it should be the only line of code in the script *}
{$utils->deleteTmpSupplementVersion('existing_collection_name')}

generateUUID4

Generates a random universally unique identifier using UUID4 standards. Can be used to assign unique data record identifiers during data transformations, imports, and exports.

• Used in:   Data Automations
• Syntax: {$utils->generateUUID4()}

{$uuid = $utils->generateUUID4()}

<h2>Random UUID:</h2><br>
{$uuid}

getContactByDeviceToken

Checks if an existing contact record already contains the provided mobile push device token. When importing mobile push contacts, it can be used in conjunction with other Smarty utilities and functions. For example, if the token already exists, you could choose to skip that record or perform a number of updates on that record.

• Used in:   Data Automations
• Syntax: {$utils->getContactByDeviceToken($channelKey, $token)}

{$mobileContact = $utils->getContactByDeviceToken('push', 'do4-_NCZRbiKTo_l-8jVKy...')}

{if $mobileContact}
Contact record with this token exists.<br><br>
<h2>Contact record:</h2>
{$utils->jsonPrettyPrint($mobileContact)}
{else}
No contact records contain this token.
{/if}

{
  "_id": "541137c785a750ffef7500999",
  "channels": {
    "email": {
      "address": "msmith@example.com",
      "subscribeStatus": "subscribed",
      "subscribedAt": "2020-01-06T18:29:12+0000",
      "unsubscribedAt": ""
    }
  },
  "push": {
    "address": {
      "5c98d21q-b3o8-42bc-9dac-e9d3c00e34e1": {
        "app": "1.0.0-MobileApp",
        "os": "android",
        "pushEnabled": true,
        "sdk": "1.0",
        "token": "do4-_NCZRbiKTo_l-8jVKy...",
        "v": "10"
      },
      "createdAt": "2020-01-06T18:29:12+0000",
      "lastModified": "2020-01-08T15:24:01+0000",
      "cID": "541137c785a750ffef7500999",
      "id": "541137c785a750ffef7500999"
    }
  }
}

mergeContacts

The mergeContacts utility allows you to merge a source contact into a destination contact while choosing which data is kept.

• Used in: Data Automations
• Syntax: {$utils->mergeContacts($sourceContactCID, $destinationContactCID, $options)}

• HTML & Smarty
• Parameters

{*
Trigger Data:
  - Event = crdl_contact_update_unique_constraint_error
  - originCID = The contact that was attempted to be updated
  - conflictCID = The contact that already has the unique value in the request payload
  - requestData = A copy of the data in the request
*}

{$data.originCID = $triggerData.properties.originCID}
{$data.conflictCID = $triggerData.properties.conflictCID}
{$data.requestData = $triggerData.properties.requestData}

{*Examine the conflicting contact and conflicting fields*}
{*
  {$contact = $utils->setContact($data.conflictCID)}
  {$utils->jsonPrettyPrint($contact)}

  {$contact = $utils->setContact($data.originCID)}
  {$utils->jsonPrettyPrint($contact)}
*}

{*Decide to merge the conflicting contact into the origin contact*}
{* Available options and theirs values: 
  - orders: merge, ignore
  - events: merge, ignore
  - cart: sourceContact, destinationContact, lastModified
  - lists: sourceContact, destinationContact
  - attributes: sourceContact, destinationContact
  - supplements: sourceContact, destinationContact
  - email_channels: sourceContact, destinationContact
  - sms_channels: sourceContact, destinationContact
  - push_channels: merge, ignore
*}

{$options = [
  'orders' => 'merge',
  'events' => 'merge',
  'cart' => 'lastModified',
  'lists' => 'destinationContact',
  'attributes' => 'sourceContact',
  'supplements' => 'destinationContact',
  'email_channels' => 'destinationContact',
  'sms_channels' => 'sourceContact',
  'push_channels' => 'merge'
]}

{$sourceContactCID = $data.conflictCID}
{$destinationContactCID = $data.originCID}
{$result = $utils->mergeContacts($sourceContactCID, $destinationContactCID, $options)}

replaceTmpSupplementVersion

Swaps the production and temporary supplement collection versions after all data are loaded into the temporary supplement collection.

• Used in:   Data Automations
• Syntax: {$utils->replaceTmpSupplementVersion('existing_collection_name')}
• Learn more about swapping supplements.

{* in preview mode replaceTmpSupplementVersion does not run and also post job script does not run *}
{$utils->replaceTmpSupplementVersion('existing_collection_name')}

sendMessage

The sendMessage utility can send a message using the message automation template key. Typically used to send an automation template sometime in the future if certain conditions are met.

• Used in:    Data Automations
• Syntax: {$utils->sendMessage($templateKey*, $extVars, $scheduledTime)}

{$send.templateKey = 'order-confirm'}
{$send.extVars = ['orderID'=>1233,'totalAmount'=>12.33]}
{$send.scheduledTime = '2120-06-21T12:23:00Z'}

{$send.data = $utils->sendMessage($send.templateKey, $send.extVars, $send.scheduledTime)}

upsertContact

Updates or creates a contact record in the Cordial database using supplied data. A new contact record will be created if the supplied lookup_key value does not already exist.

• Used in:   Data Automations
• Syntax: {$utils->upsertContact($data*, $lookup_key*, $suppressTriggers, $forceSubscribe)}

{$contact_upsert.data.channels.email.address = 'msmith@example.com'}
{$contact_upsert.lookup_key = "email:{$contact_upsert.data.channels.email.address}"}
{$contact_upsert.data.age = 26}
{$contact_upsert.data.welcome_series = 1}
{$contact_upsert.data.weekly_deals = 0}
{$contact_upsert.data.channels.email.subscribeStatus = 'subscribed'}
{$contact_upsert.suppressTriggers = true}
{$contact_upsert.forceSubscribe = true}

{$contact = $utils->upsertContact($contact_upsert.data, $contact_upsert.lookup_key, $contact_upsert.suppressTriggers, $contact_upsert.forceSubscribe)}

<h2>Debug $contact_upsert:</h2>
{$utils->jsonPrettyPrint($contact_upsert)}
<h2>Debug $contact:</h2>

{
  "data": {
    "channels": {
      "email": {
        "address": "msmith@example.com"
      }
    },
    "age": 26,
    "welcome_series": 1,
    "weekly_deals": 0
  },
  "lookup_key": "msmith@example.com",
  "suppressTriggers": true,
  "forceSubscribe": false
}

{
  "_id": "541137c785a750ffef7500999",
  "channels": {
    "email": {
      "address": "msmith@example.com",
      "subscribeStatus": "subscribed",
      "subscribedAt": "2020-01-06T18:29:12+0000",
      "unsubscribedAt": ""
    }
  },
  "age": 26,
  "lists": [
    "welcome_series"
  ],
  "createdAt": "2020-01-06T18:29:12+0000",
  "lastModified": "2020-01-08T15:24:01+0000",
  "cID": "541137c785a750ffef7500999",
  "id": "541137c785a750ffef7500999"
}

upsertOrder

Creates a new order in the orders collection or performs an update if the orderID already exists. Please see the orders API documentation for a complete list of order attributes.

• Used in:    Data Automations
• Syntax: {$utils->upsertOrder($data*)}

{$order=$utils->upsertOrder([
  'orderID' => '33451',
  'storeID' => '1',
  'customerID' => 4321,
  'purchaseDate' => '2018-12-14T17:50:25+0000',
  'shippingAddress' => [
    'name' => 'Mark Smith',
    'address' => '404 W Broadway',
    'city' => 'San Diego',
    'state' => 'CA',
    'postalCode' => 500000,
    'country' => 'USA'
  ],
  'billingAddress' => [
    'name' => 'Mark Smith',
    'address' => '404 W Broadway',
    'city' => 'San Diego',
    'state' => 'CA',
    'postalCode' => 500000,
    'country' => 'USA'
  ],
  'items' => [
    [
      'productID' => 'AC30',
      'description' => 'Stapler',
      'sku' => 'AC30-1000R',
      'category' => 'office_supplies',
      'name' => 'Acme-30 Stapler',
      'qty' => 1,
      'itemPrice' => 14.95,
      'salePrice' => 14.95,
      'url' => 'http://acmeofficesupplies.com/AC30',
      'productType' => 'physical',
      'manufacturerName' => 'Acme',
      'UPCCode' => '8 34460 00372 4',
      'images' => [
        'http://acmeofficesupplies.com/AC30/image.png'
      ],
      'tags' => [
        'tag1'
      ],
      'properties' => [ 'p1' => 'v1' ],
      'inStock' => true,
      'taxable' => true,
      'enabled' => true
    ]
  ],
  'tax' => 10,
  'shippingAndHandling' => '3.99',
  'properties' => [
     'p1' => 'v1',
     'p2' => 'v2'
  ]
])}

upsertProduct

Creates a new product record in the products collection or performs an update if the supplied productID already exists. Please see the products API documentation for a complete list of product attributes.

• Used in:    Data Automations
• Syntax: {$utils->upsertProduct($data*, custom_id)}

{$product=$utils->upsertProduct([
        'productID' => 'AC30',
        'productName' => 'AC30 Stapler',
        'productType' => 'physical',
        'category' => 'Office Supplies',
        'price' => 35.99,
        'images' => [
            'http://example.com/image.png'
        ],
        'variants' => [
            [
                'sku' => '321',
                'qty' => 2,
                'attr' => [
                    'color' => 'red',
                    'size' => 'm'
                ]
            ],
            [
                'sku' => '444',
                'qty' => 5
            ]
        ],
        'tags' => [
            'tag1',
            'tag12'
        ],
        'sale' => [
            [
                'enabled' => 1,
                'price' => 29.99,
                'start' => '2018-12-13T01:09:07+0000',
                'end' => '2018-12-31T01:09:07+0000'
            ]
        ]
    ],
    'custom_id' (if productID is not specified)
)}

upsertSupplementRecord

Creates a new supplement record using the supplied data. If the supplied record with id already exists, the record will be updated. Learn more about how supplement records are stored.

• Used in:    Data Automations
• Syntax: {$utils->upsertSupplementRecord($key*, $data*, $pk, $options)}

{$supplement.key = 'automobiles'}
{$supplement.writeData.brand = 'honda'}
{$supplement.writeData.model = 'odyssey'}
{$supplement.writeData.price = '11000'}
{$supplement.writeData.id = 5}

{$supplement.automobiles = $utils->upsertSupplementRecord($supplement.key, $supplement.writeData)} 

<h2>Debug $supplement</h2> 
{$utils->jsonPrettyPrint($supplement)}

{
    "key": "automobiles",
    "writeData": {
        "brand": "honda",
        "model": "odyssey",
        "price": "11000",
        "id": 5
    },
    "automobiles": {
        "_id": "5",
        "brand": "honda",
        "model": "odyssey",
        "price": "11000",
        "lm": "2020-05-12T20:58:58+0000",
        "ct": "2020-05-12T20:58:58+0000",
        "_action": "created"
    }
}

{$supplement = $utils->upsertSupplementRecord(
  'automobiles',
  [
  'brand' => 'honda', 
  'model' => 'odyssey', 
  'price' => '11000'
  ],
  'customID123'
)}

<h2>Debug $supplement</h2>
{$utils->jsonPrettyPrint($supplement)}

{
    "_id": "customID123",
    "brand": "honda",
    "model": "odyssey",
    "price": "11000",
    "lm": "2020-05-13T21:07:57+0000",
    "ct": "2020-05-13T20:56:04+0000",
    "_action": "created"
}

Message Automations Only

addSendProperties

The Smarty utility addSendProperties allows you to add key/value pairs to the system events (message-sent, open, click, bounce, etc.) properties object. System events are associated with every contact receiving the message and are stored in the contact activities collection.

• Used in:   Message Automations
• Syntax: {$utils->addSendProperties($data)}
• Learn more about addSendProperties

{$contactSendProperties = [
    'region' => 'northwest', 
    'internalCode' => 'pacific'
    ]}

{$utils->addSendProperties($contactSendProperties)}

{$utils->jsonPrettyPrint($contactSendProperties)}

"properties":{
  "region":"northwest",
  "internalCode":"pacific"
}

addSendTag

To maintain consistent stats filter results over time, you can apply send tag filters. Send tag filters are added within the message code using Smarty and can be unique per contact based on a contact's attribute. Send tags can be added to batch and automated messages.

For example, you may want to filter message stats according to a contact loyalty attribute to check a subset of the message send stats for Gold, Silver and Platinum members.

• Used in:   Message Automations
• Syntax: {$utils->addSendTag($tagName)}

• HTML & Smarty
• Rendered Output
• Examples
• Parameters

{$send.tagName = $contact.loyalty}

{$utils->addSendTag($send.tagName)}

Loyalty attribute category values can now be added to message Stats Filters of sent messages containing the utility:

Add a single string value as message send tag:

{$utils->addSendTag('value1')}

Add an array of string values as message send tags:

{$utils->addSendTag(['value1', 'value2'])}

Add a default send tag along with conditional tags based on contact's list membership:

{$send.tagName[] = '2020 Donor List Member'}

{if in_array('donate19campaign', $contact.lists)}
  {$send.tagName[] = '2019 Donor List Member'}
{/if}
{if in_array('donate18campaign', $contact.lists)}
  {$send.tagName[] = '2018 Donor List Member'}
{/if}

{$utils->addSendTag($send.tagName)}

Parameter	Description	Required	Expected	Default
tagName	Send tag name. Can be an array of message send tag values. Variables are allowed.	required	String	NA

addVcard

The addVcard utility inserts the parameters and media into an MMS Contact Card, such as your company name, logo, phone number, address, email, address, and note. All parameters are optional but at least one is required to send the Contact Card.

• Used in:   Message Automations 
• Syntax: {$utils->addVcard

• Smarty
• Rendered Output
• Parameters

{$utils->addVcard([ 
    'photo' => 'https://images.cordial.com/1003/96x96/CordialThreads_favicon_96x.png', 
    'first' => 'Cordial', 
    'last' => 'Threads', 
    'phone' => '+18885551212', 
    'title' => 'Best ESP', 
    'url' => 'https://www.cordial.com/', 
    'company' => 'Cordial Inc', 
    'street' => '123 Main Street', 
    'city' => 'San Diego', 
    'state' => 'CA', 
    'postal' => '92109', 
    'country' => 'USA' 
])} 

Parameters	Description	Required	Expected
photo	Thumbnail image (90x90)	optional	String
first	First name	optional	String
last	Last name	optional	String
title	Title	optional	String
url	Company name	optional	Object
street	Phone number	optional	String
city	City	optional	String
state	State	optional	String
postal	Postal code	optional	String
country	Country	optional	String
note	Additional text	optional	String

getBarcodeURL

The barcode generator provides an easy way to generate high-quality horizontal barcode images in your messages based on the provided code.

• Used in:   Message Automations
• Syntax: {$utils->getBarcodeURL($code*, $symbology*, $options)}
• Learn more about geBarcodeURL

• HTML & Smarty
• Rendered Output
• Examples
• Parameters

{$barCode.code = '28373984'}
{$barCode.symbology = code39}
{$barCode.options.padding = 20}
{$barCode.options.scale = 2}
{$barCode.options.height = 100}

{$barCode.data = $utils->getBarcodeURL($barCode.code, $barCode.symbology, $barCode.options)}

<strong>Scan the code:</strong><br>
<img src={$barCode.data}>

<h2>Debug $barCode</h2>
{$utils->jsonPrettyPrint($barCode)}

Scan the code:

Debug $barCode

{
  "code": "28373984",
  "symbology": "code39",
  "options": {
    "padding": 20,
    "scale": 2,
    "height": 100
  },
  "data": "https://barcodes.cfw.cordial.com/gen/?p=eyJzeW1ib2xvZ3kiOiJjb2RlMzkiLCJ0ZXh0IjoiMjgzNzM5ODQiLCJwYWRkaW5nIjoyMCwic2NhbGUiOjIsImhlaWdodCI6MTAwfQ&s=OebhWu6WWVufZPk7oc_erEQpurBjL8lWz2E0GRqlmYw"
}

Generate a barcode using the value of the contact attribute "membership_number" as the code parameter. Note that the contact record must have a value for the "membership_number" attribute or the barcode will not render.

{$barcode.code = $contact.membership_number}

You are able to upload a supplement of coupon codes, and using the reserveOne utility, provide unique codes to each of your contacts.

The following example assumes that you have a supplement collection called "couponBank1" with codes stored as supplement records in the proper format.

{$coupon=$supplements->reserveOne('couponBank1')}

{$barcode.code = $coupon.code}

Parameter	Type	Description	Example
*code	string	A code that will be used to generate the bar code. Note: If symbology is set to "code128", the code can contain letters and numbers. If symbology is set to "code39", the code can only contain numbers.	1723746389
*symbology	string	Defines the symbology type for the bar code. Possible Values: code128, code39	code39
options	object	An object of key/value pairs for additional control of barcode rendering. See below for parameters.	See below
padding	number	Sets the padding in pixels of the barcode. Default is 0, Max is 25. Possible Values: 1-25	5
scale	number	Sets the scale of the barcode using a range of 1-5. Pixel width is determined by the number of characters set in the code parameter. Default is 2, max is 5. Possible Values: 1-5	2
height	number	Sets the height of the barcode in pixels using a range of 0-300px Default is 100, max is 300. Possible Values: 0-300	50

getMessageLinkAppendValue

The getMessageLinkAppendValue utility returns link append key/value pairs previously set as defaults at the account level and those set using the setMessageLinkAppendValue utility. Useful for verifying existing link append key/value pairs before setting additional pairs.

• Used in:   Message Automations
• Syntax: {$utils->getMessageLinkAppendValue()}

{$links.account_level_appends = $utils->getMessageLinkAppendValue()}

{$links.returns_null = $utils->setMessageLinkAppendValue('foo', 'bar')}

{$links.account_and_utility_appends = $utils->getMessageLinkAppendValue()}

{$utils->jsonPrettyPrint($links)}

{
  "account_level_appends": {
    "utm_campaign": "{$message.name}",
    "utm_source": "cordial",
    "utm_medium": "email",
    "mciD": "{$mcID}"
  },
  "returns_null": null,
  "account_and_utility_appends": {
    "utm_campaign": "{$message.name}",
    "utm_source": "cordial",
    "utm_medium": "email",
    "mciD": "{$mcID}",
    "foo": "bar"
  }
}

jwt_encode

The jwt_encode utility is used to create a JSON Web Token with the provided payload, using the RS256 signing algorithm.

• Used in:   Message Automations
• Syntax: {$utils->jwt_encode(array $data, str $privateKey, str $algorithm)}

{$privateKey=MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvBsaJq7S5wA+kzeVOVpVWw
kWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHcaT92whREFpLv9cj5lTeJSibyr/Mr
m/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIytvHWTxZYEcXLgAXFuUuaS3uF9gEi
NQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0e+lf4s4OxQawWD79J9/5d3Ry0vbV
3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWbV6L11BWkpzGXSW4Hv43qa+GSYOD2
QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9MwIDAQABAoIBACiARq2wkltjtcjs
kFvZ7w1JAORHbEufEO1Eu27zOIlqbgyAcAl7q+/1bip4Z/x1IVES84/yTaM8p0go
bmMhvgry/mS8vNi1BN2SAZEnb/7xSxbflb70bX9RHLJqKnp5GZe2jexw+wyXlwaM
+bclUCrh9e1ltH7IvUrRrQnFJfh+is1fRon9Co9Li0GwoN0x0byrrngU8Ak3Y6D9
D8GjQA4Elm94ST3izJv8iCOLSDBmzsPsXfcCUZfmTfZ5DbUDMbMxRnSo3nQeoKGC
0Lj9FkWcfmLcpGlSXTO+Ww1L7EGq+PT3NtRae1FZPwjddQ1/4V905kyQFLamAA5Y
lSpE2wkCgYEAy1OPLQcZt4NQnQzPz2SBJqQN2P5u3vXl+zNVKP8w4eBv0vWuJJF+
hkGNnSxXQrTkvDOIUddSKOzHHgSg4nY6K02ecyT0PPm/UZvtRpWrnBjcEVtHEJNp
bU9pLD5iZ0J9sbzPU/LxPmuAP2Bs8JmTn6aFRspFrP7W0s1Nmk2jsm0CgYEAyH0X
+jpoqxj4efZfkUrg5GbSEhf+dZglf0tTOA5bVg8IYwtmNk/pniLG/zI7c+GlTc9B
BwfMr59EzBq/eFMI7+LgXaVUsM/sS4Ry+yeK6SJx/otIMWtDfqxsLD8CPMCRvecC
2Pip4uSgrl0MOebl9XKp57GoaUWRWRHqwV4Y6h8CgYAZhI4mh4qZtnhKjY4TKDjx
QYufXSdLAi9v3FxmvchDwOgn4L+PRVdMwDNms2bsL0m5uPn104EzM6w1vzz1zwKz
5pTpPI0OjgWN13Tq8+PKvm/4Gb2MjgOgPWQkslulO/oMcXbPwWC3hcRdr9tcQtn9
Imf9n2spL/6EDFId+Hp/7QKBgAqlWdiXsWckdE1Fn91/NGHsc8syKvjjk1onDcw0
NvVi5vcba9oGdElJX3e9mxqUKMrw7msJJv1MX8LWyMQC5L6YNYHDfbPF1q5L4i8j
8mRex97UVokJQRRA452V2vCO6S5ETgpnad36de3MUxHgCOX3qL382Qx9/THVmbma
3YfRAoGAUxL/Eu5yvMK8SAt/dJK6FedngcM3JEFNplmtLYVLWhkIlNRGDwkg3I5K
y18Ae9n7dHVueyslrb6weq7dTkYDi3iOYRW8HRkIQh06wEdbxt0shTzAJvvCQfrB
jg/3747WSsf/zBTcHihTRBdAv6OmdhV4/dD5YBfLAkLrd+mX7iE=}

{$token=$utils->jwt_encode([
    "iss" => "cordial.com",
    "aud" => "example.com",
    "iat" => 1356999524,
    "nbf" => 1357000000
],$privateKey)}


Token: {$token}

jwt_decode

The jwt_decode utility returns true/false based on if a public key successfully decodes the provided JSON Web Token.

• Used in:   Message Automations
• Syntax: {$utils->jwt_decode(str $token, str $publicKey, str $algorithm)}

{$token=$utils->jwt_encode([$data],$privateKey)}

{$decoded=$utils->jwt_decode($token, $publicKey, $algorithm)}
Decoded: {$utils->jsonPrettyPrint($decoded)}

reserveOne

The reserveOne utility allows you to reserve a supplement record and render its value in a message. Once a supplement record is reserved and rendered in a message, it it is given a time of use stamp, and cannot be rendered again via the reserveOne utility. Therefore, one of the primary use cases for this utility is to reserve and render a unique coupon code for individual message recipients.

• Used in:   Message Automations
• Syntax: {$supplements->reserveOne($key, $filterOptions)}
• Learn more about reserveOne

{$coupon.key = 'couponBank1'}
{$coupon.filter = ['filterOptions' => ['expdate' => ['gt' => {$smarty.now|date_format:'%Y-%m-%d'}]]]}

{$coupon = $supplements->reserveOne($coupon.key, $coupon.filter)}

Here is your coupon code: <strong>{$coupon.code}</strong>

{
  "code": "1234015",
  "id": "1",
  "expdate": "2023-03-23T17:45:18+0000"
},
{
  "code": "1234016",
  "id": "2",
  "expdate": "2023-03-23T17:45:18+0000"
},
{
  "code": "1234017",
  "id": "3",
  "expdate": "2023-03-23T17:45:18+0000"
}

setEmailHeaders

Use the setEmailHeaders utility to set or override email headers at the message level. If email headers are set at the account level, the headers specified by this util will override the ones set at the account level. 

• Used in:   Message Automations 
• Syntax: {$utils->setEmailHeaders($headers)}

{$utils->setEmailHeaders(["foo"=>"bar", "biz"=> $baz])}

setEmailLinkTracking

Use the setEmailLinkTracking utility to disable link tracking at the message level. When set to false, link tracking will be disabled for every sent message unless conditionally applied to individual messages using Smarty conditionals. Links are tracked by default for all sent messages.

• Used in:   Message Automations
• Syntax: {$utils->setEmailLinkTracking(true/false)}

{$utils->setEmailLinkTracking(false)}

{$linkTrack = $utils->getEmailLinkTracking()}
{if $linkTrack == false}
Link tracking is <strong>disabled</strong> for this message.
{else}
Link tracking is <strong>enabled</strong> for this message.
{/if}

{if $contact['age'] == 23}
  Message content with a <a href="example.com">link</a>.
  {$utils->setEmailLinkTracking(false)}
{/if}

setEmailOpensTracking

Use the setEmailOpensTracking utility to disable email opens tracking at the message level. When set to false, opens tracking will be disabled for every sent message unless conditionally disabled for qualifying messages using Smarty conditionals. By default, opens tracking is set to true for all sent messages.

• Used in:   Message Automations
• Syntax: {$utils->setEmailOpensTracking(true/false)}

{$utils->setEmailOpensTracking(false)}

{$opens = $utils->getEmailOpensTracking()}

{if $opens == false}
  Opens tracking is <strong>disabled</strong> for this message.
{else}
  Opens tracking is <strong>enabled</strong> for this message.
{/if}

{if $contact['age'] == 23}
  Message content with a <a href="example.com">link</a>.
  {$utils->setEmailOpensTracking(false)}
{/if}

setMessageLinkAppendValue

The setMessageLinkAppendValue utility appends a key/value pair to all links in a message. Similar to default link appends, the utility operates on a global level. Unlike with default link appends, the output of dynamic Smarty variables can be used as the append value.

Additional notes:

• If the utility key matches any of the default keys set at the account level, its value will overwrite the account default value
• Link appends defined with the utility are appended to the default link append string
• If default link appends are disabled at the message level, the utility appends will still render

Link appends can also be set using the appendQueryString Smarty modifier and the data-crdl-linkappend attribute.

• Used in:   Message Automations
• Syntax: {$utils->setMessageLinkAppendValue($appendKey*, $appendValue*)}

{$links.account_level_appends = $utils->getMessageLinkAppendValue()}

{$links.returns_null = $utils->setMessageLinkAppendValue('foo', 'bar')}

{$links.account_and_utility_appends = $utils->getMessageLinkAppendValue()}

{$utils->jsonPrettyPrint($links)}

{
  "account_level_appends": {
    "utm_campaign": "{$message.name}",
    "utm_source": "cordial",
    "utm_medium": "email",
    "mciD": "{$mcID}"
  },
  "returns_null": null,
  "account_and_utility_appends": {
    "utm_campaign": "{$message.name}",
    "utm_source": "cordial",
    "utm_medium": "email",
    "mciD": "{$mcID}",
    "foo": "bar"
  }
}

setMmsMedia

The setMmsMedia utility inserts media into an MMS message. Supported media types are images, audio and video.

• Used in:   Message Automations
• Syntax: {$utils->setMmsMedia($mediaURL, $mediaType)}

• HTML & Smarty
• Rendered Output
• Examples
• Parameters

{$utils->setMmsMedia("https://images-na.ssl-images-amazon.com/images/I/61IkrxQ9p8L._AC_SL1500_.jpg", "image")}

The media type parameter supports the following media types:

Image

{$utils->setMmsMedia("https://images-na.ssl-images-amazon.com/images/I/61IkrxQ9p8L._AC_SL1500_.jpg", "image")}

Audio

{$utils->setMmsMedia("https://cordialdev-testclient.s3.us-west-2.amazonaws.com/johanna/HappyFace.mp3", "audio")}

Video

{$utils->setMmsMedia("https://cordialdev-testclient.s3.us-west-2.amazonaws.com/johanna/SampleVideo_1280x720_1mb.mp4", "video")}

Parameter	Description	Required	Expected	Default
mediaURL	A valid URL to the media asset.	required	String	NA
mediaType	Specifies the type of media. Accepted values are: image audio video	required	String	NA

signature_encode

The signature_encode utility generates a signature from a private key that is shared between the provider and the consumer.

• Used in:   Message Automations
• Syntax: {$utils->signature_encode($data,$privateKey,$algorithm)}

              {$stringForEncode = "email@example.com"}
              {$signature = $utils->signature_encode($stringForEncode,$privateKey)}
              

              Signature: {$signature}