• deleteSupplementRecord
• distanceBetweenPostalCodes
• getConvertedDate
• getDistanceBetweenCoordinates
• getEventRecords
• getJson
• getMicroNow
• getNow
• getOrders
• getProducts
• getSimpleXML
• getSupplementRecords
• jsonPrettyPrint
• lastSendTimestamp
• renderInfo
• sendMessage
• setContact
• sortArray
• strContains
• updateSupplementRecord

• addEvent
• addExportRecord
• generateUUID4
• getContactByDeviceToken
• getRaw
• updateContact
• upsertContact
• upsertOrder
• upsertProduct
• upsertSupplementRecord

• addSendProperties
• addSendTag
• getBarcodeURL
• getMessageLinkAppendValue
• reserveOne
• setEmailOpensTracking
• setMessageLinkAppendValue

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}

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

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 <sgtrong>{$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 2 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)}

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}

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

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}

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"
  }
}

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']}

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.
{else}
No contact records contain this token.
{/if}

<h2>Contact record:</h2>
{$utils->jsonPrettyPrint($mobileContact)}

{
  "_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"
    }
  }
}

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

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($array*)}

{$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"
  ]
}

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"
}

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}

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:    Message Automations   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)}

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}

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"
  }
}

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:   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: {$utils->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.automobiles = $utils->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"
    }
}

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 id already exists, the record will be updated. Learn more about how supplement records are stored.

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

{$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"
}