| Data & Message Automations | Data Automations Only | Message Automations Only |
|---|---|---|
|
addEventAdds a custom event to the events data collection and associates it to specific contact(s).
{$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)}
Debug $event
{
"success": true,
"messages": "created"
}
|
||||||||||||||||||||||||||||||
addExportRecordUsed 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.
{$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}
This example generates two CSV files with Local download as the file destination (previously set in our Data Job settings via the UI). The source of data is internal supplement and product data. After the script is run, the files can be downloaded from the Jobs page in Cordial. Additional file destinations include FTP, SFTP, and Amazon S3. More advanced use cases carry out data transformations on loaded data, using addExportRecord to add export file data rows. {* 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}
|
||||||||||||||||||||||||||||||
createTmpSupplementVersionCreates 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.
Warning: The createTmpSupplementVersion utility should only be used within the pre job script. It is also always used in conjunction with replaceTmpSupplementVersion utility in post job script of the same data transformation.
{* in preview mode createTmpSupplementVersion does not run *}
{$utils->createTmpSupplementVersion('existing_collection_name')}
|
||||||||||||||||||||||||||||||
deleteTmpSupplementVersionThis 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.
Warning: Please only run deleteTmpSupplementVersion under the guidance of a Solutions Engineer. There are very few instances where this would ever be needed in production, as it will clear out the unused tmp collection.
{* If running deleteTmpSupplementVersion, it should be the only line of code in the script *}
{$utils->deleteTmpSupplementVersion('existing_collection_name')}
|
||||||||||||||||||||||||||||||
addSendPropertiesThe 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. Note: Send properties must be added before the message is sent. It is not possible to add send properties to sent messages.
{$contactSendProperties = [
The resulting system events properties object: "properties":{
"region":"northwest",
"internalCode":"pacific"
}
|
||||||||||||||||||||||||||||||
addSendTagTo 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. Note: Ensure that tags added using the addSendTag utility are not duplicates of tags added during message creation. When duplicate tags are present, only one instance will be tracked.
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.
{$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'}
|
||||||||||||||||||||||||||||||
deleteSupplementRecordDeletes a supplement record from the supplement collection using Smarty. If the target supplement record does not exist, the utility will not interrupt script execution.
{$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}
Supplement record 1 was deleted from the automobiles supplement collection.
|
||||||||||||||||||||||||||||||
distanceBetweenPostalCodesCalculates the distance between 2 postal codes for rendering content based on that distance.
{$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)}
Distance = 1756.88
Debug $distance
{
"zip1": 35244,
"zip2": 92109,
"data": "1756.88"
}
Display "Marketing Content" where the contact's postal code is less than 200 miles from 92131. The address attribute in this example assumes a geo-location type of attribute with a key of address. The contact's postal code can be pulled from any contact attribute. {$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}
Calculate the distance between United States and Canada postal codes. {$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)}
|
||||||||||||||||||||||||||||||
generateUUID4Generates a random universally unique identifier using UUID4 standards. Can be used to assign unique data record identifiers during data transformations, imports, and exports.
{$uuid = $utils->generateUUID4()}
<h2>Random UUID:</h2><br>
{$uuid}
Random UUID:
86f556b0-7882-48ef-8f09-5b735066e856 |
||||||||||||||||||||||||||||||
getBarcodeURLThe barcode generator provides an easy way to generate high-quality horizontal barcode images in your messages based on the provided code.
{$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 {$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}
|
||||||||||||||||||||||||||||||
getConvertedDateUsing the getConvertedDate utility, you are able to convert a given date and time to a different time zone.
{$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}
Date in UTC: 2020-05-01T18:57:20Z
Date Converted to LA: May 01 2020 11:57:20 AM
|
||||||||||||||||||||||||||||||
getDistanceBetweenCoordinatesCalculates 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.
{$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.
The distance between 44.1793, -72.4731 and 32.9014, -117.2079 coordinate points is 2505.51 miles.
For this example we are using the getCoordinatesFromZip utility to derive longitude and latitude coordinates from two postal codes for use with the getDistanceBetweenCoordinates utility.
{$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')}
Debug $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"
}
|
||||||||||||||||||||||||||||||
getEventRecordsData stored within the contact activities collection can be referenced and used within any message body.
{$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)}
Items You Browsed
Khaki Shirt $9.99 A Really Cool Khaki Shirt http://example.com/shirts Khaki Pants $19.99 Awesome Khaki Pants http://example.com/shirt Debug $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"
}
]
}
]
NewerThan: Return records newer than the specified date. {$events.newerThan = '2020-08-19T21:36:13+0000'}
NewerThan: Return records newer than 1 day in the past. {$events.newerThan = '-1 day'|date_format:'Y-m-d\TH:i:sO'}
NewerThan: Using the the Smarty utility, {$lastSend.templateKey = 'automation_key'}
{$lastSend.date = $utils->lastSendTimestamp($lastSend.templateKey)}
{$events.newerThan = $lastSend.date|date_format:'Y-m-d\TH:i:sO'}
Properties: Return records by multiple specified values. {$events.properties = ['category'=>'shoes','brand'=>'nike']}
Sort: Sort results by action timestamp in descending order. {$events.sort = ['column'=>'ats','direction'=>'DESC']}
|
||||||||||||||||||||||||||||||
getJsonData stored within an externally hosted JSON feed can be referenced and used within any message body.
{$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)}
Honda Pilot
$33000 Mileage: 100000 View details Ford Explorer $34000 Mileage: 39000 View details Toyota Prius $27000 Mileage: 66000 View details Debug $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"
}
]
}
Options: Setting HTTP request headers for authorization. {$json_feed.options = ['headers'=>['Authorization' => 'Basic <base64 encoded username:password>']]}
Options: Setting the maximum wait time (cannot exceed 60 seconds). {$json_feed.options = ['timeout' => 1]}
Options: Setting the limit on the number of records returned. {$json_feed.options = 3}
|
||||||||||||||||||||||||||||||
getMessageLinkAppendValueThe 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. Note: This utility does not return link appends set using the appendQueryString Smarty modifier or the data-crdl-linkappend attribute.
{$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"
}
}
|
||||||||||||||||||||||||||||||
getMicroNowSimilar to the getNow utility, you can render the current time for a specified time zone, with the addition of microseconds.
{$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)}
Time since Unix epoch with microseconds:
1590861373.977000 Debug $getMicroNow
{
"tzId": "UTC",
"format": "U.u",
"data": "1590861373.977000"
}
|
||||||||||||||||||||||||||||||
getNowUsing the getNow utility, you can render the current time for a specified time zone when the template is compiled.
{$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)}
Current time:
2020-04-27 13:30:57 Debug $getNow
{
"tzId": "America\/Los_Angeles",
"format": "Y-m-d\\TH:i:sO",
"data": "2020-04-27 13:30:57"
}
Rendering a copyright date in the footer of your email: {$getNow.tzId = $account.timezone}
{$getNow.format = 'Y'}
{$getNow.data = $utils->getNow($getNow.tzId, $getNow.format)}
© {$getNow.data} Example Company
The time zone can be a variable unique to each contact if you are storing the time zone as an attribute value. Learn how to set an attribute as the primary time zone. {$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}
|
||||||||||||||||||||||||||||||
getOrdersData stored within the orders collection can be referenced and used within any message body.
{$orders.query = []}
OrderID 001
Purchase Date - Jan 10, 2015 Product 111 Khaki Shorts - $19.99 Size - large Color - tan Product 222 Khaki Pants - $29.99 Size - large Color - tan Total Amount - $49.98 Shipping Address: Fred Garvin 555 Truss St San Diego CA 92108 Debug $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
}
]
}
]
Query: Return records filtered by a specified value. {$orders.query = ['orderID"=>'002']}
Query: Return records filtered by a value within an order item. {$orders.query = ['items'=>['productID'=>'111']]}
Query: Return records by multiple specified values. {$orders.query = ['purchaseDate'=>['gt'=>'2016-01-09'],'shippingAddress.city'=>'san diego']}
Sort: Sort results by order ID in descending order. {$orders.sort = ['column'=>orderID,'direction'=>'DESC']}
|
||||||||||||||||||||||||||||||
getProductsData stored within the products collection can be referenced and used within any message body.
{$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)}
Skirt - $19.99
Color: blue Size: small Sku: 111 Color: blue Size: medium Sku: 112 Shorts - $29.99 Color: green Size: small Sku: 221 Color: green Size: medium Sku: 222 Debug $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"
}
}
]
}
]
}
]
Query: Return records filtered by values between two numbers. {$products.query = ['price'=>['between'=>['start'=>10,'end'=>30]]]}
Query: Return records filtered by multiple specified values of the same key. {$products.query = ['productID'=>['in' => [123,1234]]]}
Query: Return records that are not in the specified array. {$products.query = ['productID'=>['notIn' => [123,1234]]]}
Query: Return records filtered by comparison operators (lt, gt, gte). {$products.query = ['price'=>['lt'=>39]]}
Sort: Sort results by price in descending order. {$products.sort = ['column'=>'price','direction'=>'DESC']}
|
||||||||||||||||||||||||||||||
getContactByDeviceTokenChecks 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.
Note: The mobile push channel key may differ depending on your account configuration.
{$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}
Contact record with this token exists.
Contact record: {
"_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"
}
}
}
|
||||||||||||||||||||||||||||||
replaceTmpSupplementVersionSwaps the production and temporary supplement collection versions after all data are loaded into the temporary supplement collection.
Warning: The replaceTmpSupplementVersion utility should only be used within the post job script. It is also always used in conjunction with createTmpSupplementVersion utility in the pre job script of the same data transformation.
{* in preview mode replaceTmpSupplementVersion does not run and also post job script does not run *}
{$utils->replaceTmpSupplementVersion('existing_collection_name')}
|
||||||||||||||||||||||||||||||
getRawThe 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.
{$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:
|
||||||||||||||||||||||||||||||
getSimpleXMLData stored within an externally hosted XML feed can be referenced and used within any message body.
{$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"> Classic AlbumsFleetwood Mac - Rumourshttp://fleetwoodmac.comRumours tends to be remembered as the album that was characterized by personal strife between the band members. Pink Floyd - Dark Side of the Moonhttp://www.pinkfloyd.com/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.
|
||||||||||||||||||||||||||||||
getSupplementRecordsData stored within a supplement can be referenced and used within any message body.
{$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)}
Honda Pilot
$33000 Mileage: 100000 View details Ford Explorer $34000 Mileage: 39000 View details Debug $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"
}
]
}
]
Query: Return records filtered by values between two numbers. {$supplement_records.query = ['price'=>['between'=>['start'=>10000,'end'=>50000]]]}
Query: Return records filtered by values between two dates. {$supplement_records.query = ['date'=>['lt'=>{$smarty.now|date_format:'%Y-%m-%dT%H:%M:%S+0000'}],'date'=>['gt'=>{'2020-10-10T22:21:18+0000'}]]}
Query: Return records that are not in the specified array. {$supplement_records.query = ['brand'=>['notIn' => [toyota,honda]]]}
Query: Return records where the color black is contained in the array with the key of colors: {$supplement_records.query = ['colors' => ['array_contains' => 'black']]}
Sort: Last modified in descending order. {$supplement_records.sort = ['column'=>'lm','direction'=>'DESC']}
|
||||||||||||||||||||||||||||||
jsonPrettyPrintYou 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.
{$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. |
||||||||||||||||||||||||||||||
lastSendTimestampThe lastSendTimestamp utility allows you to render the last send date of a specified automation template.
{$lastSend.templateKey = 'order-confirmation'}
{$lastSend.date = $utils->lastSendTimestamp($lastSend.templateKey)}
Message last sent: {$lastSend.date|date_format:'Y-m-d\TH:i:sO'};
Message last sent: 2020-04-27T22:17:58+0000
|
||||||||||||||||||||||||||||||
mergeContactsThe mergeContacts utility allows you to merge a source contact into a destination contact while choosing which data is kept.
{*
|
||||||||||||||||||||||||||||||
renderInfoA 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.
{$metadata = $utils->renderInfo()}
Debug $metadata
{
"name": "Data Automation",
"preview": true
}
An example of executing the
stopMessage Smarty function in a Message Automation and otherwise returning information text if the script is ran in a Data Automation, where stopMessage is not supported.{$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}
Debug $data:
{
"metadata": {
"name": "Data Automation",
"preview": true
},
"info": [
"We are in Data Automation, stopMessage can NOT run"
]
}
|
||||||||||||||||||||||||||||||
reserveOneThe 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. Note: In addition to live message sends, test message sends will also flag a record as "reserved".
{$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>
In our example, these coupon codes are stored as supplement records in the couponBank1 supplement collection. We are using the expdate supplement field to filter for coupons that have not expired using the filterOptions parameter.
{
"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"
}
Here is your coupon code: 1234015
|
||||||||||||||||||||||||||||||
setEmailHeadersUse 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. Note: The following headers cannot be overridden:
{$utils->setEmailHeaders(["foo"=>"bar", "biz"=> $baz])}
|
||||||||||||||||||||||||||||||
setEmailLinkTrackingUse the setEmailLinkTracking utility to disable link tracking at the message level. When set to Note: The Link Tracking setting under message Goals and Tracking does not override the utility.
Tip: When using conditionals with this utility, you can check whether link tracking will be enabled or disabled for a particular message using the getEmailLinkTracking utility.
{$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}
Link tracking is disabled for this message.
Link tracking can be disabled conditionally using Smarty. Here is a simple example of using an
{if} statement to display specific content and disable link tracking for messages where the recipient's age is 23.{if $contact['age'] == 23}
Message content with a <a href="example.com">link</a>.
{$utils->setEmailLinkTracking(false)}
{/if}
Use the
true and false boolean values to enable or disable link tracking in email messages. Links are tracked by default. |
||||||||||||||||||||||||||||||
setEmailOpensTrackingUse the setEmailOpensTracking utility to disable email opens tracking at the message level. When set to Tip: When using conditionals with this utility, you can check whether opens tracking will be enabled or disabled for a particular message using the getEmailOpensTracking utility.
{$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}
Opens tracking is disabled for this message.
Message opens tracking can be disabled conditionally using Smarty. Here is a simple example of using an
{if} statement to display specific content and disable opens tracking for messages where the recipient's age is 23.{if $contact['age'] == 23}
Message content with a <a href="example.com">link</a>.
{$utils->setEmailOpensTracking(false)}
{/if}
Use the
true and false boolean values to enable or disable email message opens tracking. The setEmailOpensTracking utility is set to true by default. |
||||||||||||||||||||||||||||||
sendMessageThe 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. Note: This utility requires the enablement of an additional account feature. Please contact your CSM if your use case absolutely relies on the implementation of this utility.
{$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)}
|
||||||||||||||||||||||||||||||
setContactSets 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.
{$contact = $utils->setContact('email:msmith@example.com')}
{* Contact object is msmith@example.com for the followng context *}
|
||||||||||||||||||||||||||||||
setMessageLinkAppendValueThe 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:
Link appends can also be set using the appendQueryString Smarty modifier and the data-crdl-linkappend attribute. Tip: You can preview default link append key/value pairs set at the account level during message creation using the getMessageLinkAppendValue utility.
{$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"
}
}
|
||||||||||||||||||||||||||||||
setMmsMediaThe setMmsMedia utility inserts media into an MMS message. Supported media types are images, audio and video. Note: the setMmsMedia utility is only supported in SMS channel messages when the send type is set to
MMS
{$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")}
|
||||||||||||||||||||||||||||||
sortArrayCordial 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.
{$json_feed.data = $utils->getJson('http://p5.zdassets.com/hc/theme_assets/656597/200049057/automobiles.json')}
{$sorted = $utils->sortArray($json_feed.data, 'price', 'asc')}
[
{
"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"
}
]
Nissan Versa
$16000 Mileage: 94000 ID: 05 Honda Accord $24000 Mileage: 49000 ID: 07 Toyota Prius $27000 Mileage: 66000 ID: 03
|
||||||||||||||||||||||||||||||
strContainsThe 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
{$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
}
|
||||||||||||||||||||||||||||||
updateContactUpdates 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.
{$lookup_key = 'email:msmith@example.com'}
Contact Age: 46
Last Name: Smith Debug $updateContact {
"data": {
"last_name": "Smith",
"age": {
"inc": "+1"
}
},
"waitForResult": true,
"suppressTriggers": true,
An example of using the
forceSubscribe parameter to update an existing contact's channel subscribe status from unsubscribed to subscribed. Note that the channel key for SMS and push channels will vary depending on your account configuration.
{$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)}
Updated Contact:{$utils->jsonPrettyPrint($contactRecord)}
The following example demonstrates looking up contacts who performed a click event 1 day in the past, retrieves the click date, and updates the lastClick contact attribute.
{$clickEvents.eventName = 'click'}
|
||||||||||||||||||||||||||||||
updateSupplementRecordUpdates an existing supplement record within the specified supplement collection. Note: When updating a contact attribute supplement record, you can use the setContact utility as a way to provide the required contact ID (cID) value.
For example: {$contact = $utils->setContact('msmith@example.com')}
{$supplement.writeData.cID = $contact._id}
{$supplement.key = 'automobiles'}
{$supplement.writeData.id = 2}
{$supplement.writeData.price = '36000'}
{$supplement.writeData.milage = '100'}
This is our existing supplement record within the automobiles collection before the update. We are updating the price and milage field key values. [ {
"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"
}
}
|
||||||||||||||||||||||||||||||
upsertContactUpdates or creates a contact record in the Cordial database using supplied data. A new contact record will be created if the supplied
{$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>
Debug $contact_upsert:
{
"data": {
"channels": {
"email": {
"address": "msmith@example.com"
}
},
"age": 26,
"welcome_series": 1,
"weekly_deals": 0
},
"lookup_key": "msmith@example.com",
"suppressTriggers": true,
"forceSubscribe": false
}
Debug $contact:
{
"_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"
}
Note: The contact channels.email.address property must be defined and populated if using the forceSubscribe argument of this method.
|
||||||||||||||||||||||||||||||
upsertOrderCreates a new order in the orders collection or performs an update if the Note: The contact identifier attribute is not part of the upsertOrder utility schema. Contact must be set in the context of a transformation, using the setContact utility for example.
{$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'
]
])}
|
||||||||||||||||||||||||||||||
upsertProductCreates a new product record in the products collection or performs an update if the supplied
{$product=$utils->upsertProduct([
|
||||||||||||||||||||||||||||||
upsertSupplementRecordCreates a new supplement record using the supplied data. If the supplied record
{$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)}
The {
"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"
}
}
An example of creating a supplement record using the {$supplement = $utils->upsertSupplementRecord(
'automobiles',
[
'brand' => 'honda',
'model' => 'odyssey',
'price' => '11000'
],
'customID123'
)}
<h2>Debug $supplement</h2>
{$utils->jsonPrettyPrint($supplement)}
Debug $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"
}
|
Comments
0 comments
Please sign in to leave a comment.