shuffleArray

Cordial provides a custom Smarty utility to randomize an array of data in a message. This is useful when building recommended product content blocks, as one common way of making that content dynamic is by randomizing an array of items.

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

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 use the setContact utility to look up an existing contact record and then pass update data using the updateContact utility.

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

Data jobs

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

• Contact Age: 46
  Last Name: Smith
  
  Debug $updateContact
  

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

• 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'}
  {$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}

• Parameter	Description	Required	Expected	Default
  data	Contact data to be updated including attribute values and list associations.	required	Array	NA
  waitForResult	If true, will wait on the preceding contact update operation to complete before moving to the next line of Smarty. Typically set to true when subsequent Smarty functions require the newly created contact identifier value for successful execution.	optional	Boolean string	false
  suppressTriggers	If true, will suppress any triggered messages set to fire based on updates to values in the import. Defaults to true.	optional	Boolean string	true
  forceSubscribe	If set to true, will allow previously unsubscribed contacts to be updated as subscribed. Defaults to false.	optional	Boolean string	false

Message content

To change the contact record when sending a message, add the following Smarty to your message content.

• {$utils->updateContact(['flavor'=>'vanilla','age'=>['inc' => '+1'], 'fav_fruit'=>['add' => ['orange','strawberry']]])}

• 

• Parameter	Description	Required	Expected	Default
  data	Contact data to be updated including attribute values and list associations.	required	Array	N/A

updateSupplementRecord

Updates an existing supplement record within the specified supplement collection.

When updating a contact attribute supplement record, you can use the setContact utility as a way to provide the required contact ID (cID) value.

• {$supplement.key = 'automobiles'}
  {$supplement.writeData.id = 2}
  {$supplement.writeData.price = '36000'}
  {$supplement.writeData.milage = '100'}
  {$supplement.writeData.model = 'explorer'}
  {$supplement.writeData.brand = 'ford'}
  
  {$supplement.automobiles = $supplements->updateSupplementRecord($supplement.key, $supplement.writeData)}
  
  <h2>Debug $supplement</h2>
  {$utils->jsonPrettyPrint($supplement)}

• This is our existing supplement record within the automobiles collection before the update. We are updating the price and milage field key values.

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

• Parameters	Description	Required	Expected	Default
  supplementKey	A unique supplement collection identifier.	Required	String	NA
  data	An array of supplement record field key/value pairs.	Required	Array	NA

Data automations only

addEvent

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

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

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

• Debug $event

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

• Parameter	Description	Required	Expected	Default
  a	Defines an action such as open, click, or any other custom action. The maximum length of the parameter is 40 characters.	required	String	NA
  UID	Unique event identifier. If undefined, a value will automatically be generated.	optional	String	NA
  contact_identifier	Unique primary or secondary contact identifier key/value pair to look up and reference the contact.	required	String	NA
  ats	Action occurrence timestamp. If undefined, the current date and time will be used. Date format is ISO 8601 standard.	optional	String	current time
  properties	An object of additional event attributes. Note that property keys consisting of numeric-only values (e.g. 57) or keys containing a "dot" (e.g. shoes.color) will be stripped.	optional	Object	NA

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}

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

• Parameter	Description	Required	Expected	Default
  file_identifier	Export file identifier (Export name field from the Data Mapping UI).	required	String	NA
  row	Object of data to insert as a row into the export file.	required	Object	NA

createTmpSupplementVersion

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

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

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

deleteTmpSupplementVersion

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

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

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

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}

• Random UUID:
  86f556b0-7882-48ef-8f09-5b735066e856

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

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

• Parameter	Description	Required	Expected	Default
  $channelKey	Mobile push channel key.	required	String	NA
  $token	APNS (Apple) or FCM (Android) issued device token.	required	String	NA

mergeContacts

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

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

• {*
  Trigger Data:
    - Event = crdl_contact_update_unique_constraint_error
    - originCID = The contact that was attempted to be updated
    - conflictCID = The contact that already has the unique value in the request payload
    - requestData = A copy of the data in the request
  *}
  
  {$data.originCID = $triggerData.properties.originCID}
  {$data.conflictCID = $triggerData.properties.conflictCID}
  {$data.requestData = $triggerData.properties.requestData}
  
  {*Examine the conflicting contact and conflicting fields*}
  {*
    {$utils->setContact($data.conflictCID)}
    {$utils->jsonPrettyPrint($contact)}
  
    {$utils->setContact($data.originCID)}
    {$utils->jsonPrettyPrint($contact)}
  *}
  
  {*Decide to merge the conflicting contact into the origin contact*}
  {* Available options and theirs values: 
    - orders: merge, ignore
    - events: merge, ignore
    - cart: sourceContact, destinationContact, lastModified
    - lists: sourceContact, destinationContact
    - attributes: sourceContact, destinationContact
    - supplements: sourceContact, destinationContact
    - email_channels: sourceContact, destinationContact
    - sms_channels: sourceContact, destinationContact
    - push_channels: merge, ignore
  *}
  
  {$options = [
    'orders' => 'merge',
    'events' => 'merge',
    'cart' => 'lastModified',
    'lists' => 'destinationContact',
    'attributes' => 'sourceContact',
    'supplements' => 'destinationContact',
    'email_channels' => 'destinationContact',
    'sms_channels' => 'sourceContact',
    'push_channels' => 'merge'
  ]}
  
  {$sourceContactCID = $data.conflictCID}
  {$destinationContactCID = $data.originCID}
  {$result = $utils->mergeContacts($sourceContactCID, $destinationContactCID, $options)}

• Parameter	Description	Required	Expected	Default
  sourceContactCID	Contact ID (CID) of the source contact. This contact will be deleted after the merge.	required	Valid Contact ID	NA
  destinationContactCID	Contact ID (CID) of the destination contact. This contact will still exist after the merge.	required	Valid Contact ID	NA
  options	A list of which data to keep from each contact	required	A valid json object with all required fields (See above example)	NA

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: Data Automations
• Syntax: {$utils->setContact($lookup_key*)}

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

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

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

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.

The contact channels.email.address property must be defined and populated if using the forceSubscribe argument of this method.

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

• Parameter	Description	Required	Expected	Default
  data	Contact data to be updated including attribute values and list associations.	required	Array	NA
  lookup_key	A valid primary or secondary contact identifier key/value pair - email:msmith@example.com cID:58d2fc99ac0c8117814d4e78 custID:idValue.	required	String	NA
  suppressTriggers	If true, will suppress any triggered messages set to fire based on updates to values in the import. Defaults to true.	optional	Boolean string	true
  forceSubscribe	If set to true, will allow previously unsubscribed contacts to be updated as subscribed. Defaults to false.	optional	Boolean string	false

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.

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.

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

• {$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'
    ]
  ])}

• Parameter	Description	Required	Expected	Default
  data	An array of order attributes. Empty quotes should be used for optional order attributes that have no value.	required	Array	NA
  options	An array of options. The only available option is suppressTriggers which is either true or false.	optional	Array	NA

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

• Parameter	Description	Required	Expected	Default
  data	An array of product attributes. Empty quotes should be used for optional product attributes that have no value.	required	String	NA
  custom_id	If product records do not inherently have a value for productID, the custom_id parameter can be used to set this value. Provide only the value without the attribute key.	optional	String	NA

upsertSupplementRecord

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

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

• {$supplement.key = 'automobiles'}
  {$supplement.writeData.brand = 'honda'}
  {$supplement.writeData.model = 'odyssey'}
  {$supplement.writeData.price = '11000'}
  {$supplement.writeData.id = 5}
  
  {$supplement.automobiles = $utils->upsertSupplementRecord($supplement.key, $supplement.writeData)} 
  
  <h2>Debug $supplement</h2> 
  {$utils->jsonPrettyPrint($supplement)}

• The _action parameter will indicate action type as being updated or created.

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

• An example of creating a supplement record using the custom_id as pk parameter when id is not passed in $data:

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

• Parameter	Description	Required	Expected	Default
  key	A unique supplement collection identifier.	required	String	NA
  data	An array of supplement record field key/value pairs. Mind that if the supplement is a contact attribute, contact identifier (cID) should be provided.	required	Array	NA
  pk	A unique supplement record identifier. Parameter is optional as supplement record identifier can be set as one of the field key/value pairs in the data parameter. A unique id will be generated automatically if one is not passed in data or pkparameters. If different identifiers are passed in both data and pkparameters pk has priority over data.	optional	String	NA
  options	An array of key/value pairs describing the function execution behaviour. As one of the optionsthe strategy can be set. strategy defines whether the supplement records update and create actions are allowed or not. strategy possible values are upsert|update|insert. If strategy is update then only the existent records will be updated. If strategy is insert then only the new records will be introduced. If strategy is upsert then both actions are allowed.	optional	Array	upsert

Message automations only

addSendProperties

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

Send properties must be added before the message is sent. It is not possible to add send properties to sent messages.

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

• {$contactSendProperties = [
      'region' => 'northwest', 
      'internalCode' => 'pacific'
      ]}
  
  {$utils->addSendProperties($contactSendProperties)}
  
  {$utils->jsonPrettyPrint($contactSendProperties)}

• The resulting system events properties object:

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

• Parameter	Description	Required	Expected	Default
  sendProperties	An array of system event property key/value pairs.	required	String	NA

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.

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.

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

• {$send.tagName = $contact.loyalty}
  
  {$utils->addSendTag($send.tagName)}

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

  

• Add a single string value as message send tag:

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

  Add an array of string values as message send tags:

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

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

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

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

addVcard

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

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

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

• 

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

getBarcodeURL

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

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

• {$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 can upload a supplement of coupon codes, and, using the reserveOne utility, provide unique codes to each of your contacts.

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

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

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

getMessageLinkAppendValue

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

This utility does not return link appends set using the appendQueryString Smarty modifier or the data-crdl-linkappend attribute.

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

isTestSend

This utility is used to determine whether or not an email message is being sent as a test. It returns a boolean value, either true or false, depending on whether the email is a test message or not.

You can use it in testing environments to ensure your messages are sending correctly, and also as a way to make sure test emails aren't sent to live contacts.

• Used in: Message automations
• Syntax: {if $utils->isTestSend()}

• {if $utils->isTestSend()}
      This is a test message. Please do not act on it.
  {else}
      Thank you for your recent purchase! We hope you enjoy your new products.
  {/if}  

• This is a test message. Please do not act on it.

  Thank you for your recent purchase! We hope you enjoy your new products.

jwt_encode

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

See the jwt_decode utility to verify that the JWT is valid with the provided public key.

• Used in: Message Automations
• Syntax: {$utils->jwt_encode(array $data, str $privateKey, str $algorithm, array $optional_headers)}
• Supported algorithms: 'ES384','ES256', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'EdDSA'

• {$privateKey=MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvBsaJq7S5wA+kzeVOVpVWw
  kWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHcaT92whREFpLv9cj5lTeJSibyr/Mr
  m/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIytvHWTxZYEcXLgAXFuUuaS3uF9gEi
  NQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0e+lf4s4OxQawWD79J9/5d3Ry0vbV
  3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWbV6L11BWkpzGXSW4Hv43qa+GSYOD2
  QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9MwIDAQABAoIBACiARq2wkltjtcjs
  kFvZ7w1JAORHbEufEO1Eu27zOIlqbgyAcAl7q+/1bip4Z/x1IVES84/yTaM8p0go
  bmMhvgry/mS8vNi1BN2SAZEnb/7xSxbflb70bX9RHLJqKnp5GZe2jexw+wyXlwaM
  +bclUCrh9e1ltH7IvUrRrQnFJfh+is1fRon9Co9Li0GwoN0x0byrrngU8Ak3Y6D9
  D8GjQA4Elm94ST3izJv8iCOLSDBmzsPsXfcCUZfmTfZ5DbUDMbMxRnSo3nQeoKGC
  0Lj9FkWcfmLcpGlSXTO+Ww1L7EGq+PT3NtRae1FZPwjddQ1/4V905kyQFLamAA5Y
  lSpE2wkCgYEAy1OPLQcZt4NQnQzPz2SBJqQN2P5u3vXl+zNVKP8w4eBv0vWuJJF+
  hkGNnSxXQrTkvDOIUddSKOzHHgSg4nY6K02ecyT0PPm/UZvtRpWrnBjcEVtHEJNp
  bU9pLD5iZ0J9sbzPU/LxPmuAP2Bs8JmTn6aFRspFrP7W0s1Nmk2jsm0CgYEAyH0X
  +jpoqxj4efZfkUrg5GbSEhf+dZglf0tTOA5bVg8IYwtmNk/pniLG/zI7c+GlTc9B
  BwfMr59EzBq/eFMI7+LgXaVUsM/sS4Ry+yeK6SJx/otIMWtDfqxsLD8CPMCRvecC
  2Pip4uSgrl0MOebl9XKp57GoaUWRWRHqwV4Y6h8CgYAZhI4mh4qZtnhKjY4TKDjx
  QYufXSdLAi9v3FxmvchDwOgn4L+PRVdMwDNms2bsL0m5uPn104EzM6w1vzz1zwKz
  5pTpPI0OjgWN13Tq8+PKvm/4Gb2MjgOgPWQkslulO/oMcXbPwWC3hcRdr9tcQtn9
  Imf9n2spL/6EDFId+Hp/7QKBgAqlWdiXsWckdE1Fn91/NGHsc8syKvjjk1onDcw0
  NvVi5vcba9oGdElJX3e9mxqUKMrw7msJJv1MX8LWyMQC5L6YNYHDfbPF1q5L4i8j
  8mRex97UVokJQRRA452V2vCO6S5ETgpnad36de3MUxHgCOX3qL382Qx9/THVmbma
  3YfRAoGAUxL/Eu5yvMK8SAt/dJK6FedngcM3JEFNplmtLYVLWhkIlNRGDwkg3I5K
  y18Ae9n7dHVueyslrb6weq7dTkYDi3iOYRW8HRkIQh06wEdbxt0shTzAJvvCQfrB
  jg/3747WSsf/zBTcHihTRBdAv6OmdhV4/dD5YBfLAkLrd+mX7iE=}
  
  {$token=$utils->jwt_encode([
      "iss" => "cordial.com",
      "aud" => "example.com",
      "iat" => 1356999524,
      "nbf" => 1357000000
  ],$privateKey)}
  
  
  Token: {$token}

• Token: sampleTokenvalue112233445566

• Parameter	Description	Type	Default
  data	Claims are not required but provide security and permissions.	Array	NA
  privateKey	The secret key used to generate the signature, which is validated by the consumer's public key.	String	NA
  algorithm	Determines which algorithm is used to sign the JWT.	String	rs256

jwt_decode

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

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

• {$token=$utils->jwt_encode([$data],$privateKey)}
  
  {$decoded=$utils->jwt_decode($token, $publicKey, $algorithm)}
  Decoded: {$utils->jsonPrettyPrint($decoded)}
  

• Decoded: true

• Parameter	Description	Type	Default
  token	A signed JSON Web Token that certifies that the public/private key pairing can be verified and trusted.	String	NA
  publicKey	The consumer of the JWT gets a public key that is used to validate the signature given by the private key of the provider.	String	NA
  algorithm	Determines which algorithm is used to sign the JWT.	String	rs256

mmsMedia

The mmsMedia utility inserts an experiment into an MMS or SMS message.

SMS & MMS experiments are only supported in batch messages.

• Used in: Batch Messages
• Syntax: {$utils->mmsMedia($mediaURL, $mediaType)}

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

• 
• The media type parameter supports the following media types:
  Image

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

  Audio

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

  Video

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

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

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.

In addition to live message sends, test message sends will also flag a record as "reserved".

• 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>

• 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

• Parameter	Description	Required	Expected	Default
  key	A unique key created by the user for a stored supplement.	required	String	NA
  filterOptions	A filter used to query supplement records by date. Only indexed fields can be queried.	optional	Array	[]

sendWebhook

The sendWebhook utility allows you to ping a URL when a message renders during preview or send time. This is useful if you need to ping a URL with a query string unique to the contact.

Due to the high traffic volume that the sendWebhook utility can generate, it is recommended to only use this on a service your company owns, or a service your company has explicit permission to use.

• Used in:Message Automations
• Syntax: {$utils->sendWebhook($url}

• {$webhook_response = $utils->sendWebhook("http://analytics.example.com/pingme?cID=$cID&mcID=$mcID&msID=$message.msID")}

setEmailHeaders

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

The following headers cannot be overridden: X-Feedback-ID, X-MSYS-SUBACCOUNT, X-Crdl-Mc, fromDesc, fromEmail, subject, toName, replyEmail, DKIM-Signature, To, From, MIME-Version, Content-type, Return-Path, Received, Path, Sender, bcc, cc, reply-to, Message-ID, Date

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

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

• Parameter	Description	Required	Expected	Default
  headers	Used to set custom headers on an email message.	required	Array of key value pairs	NA

setEmailLinkTracking

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

The Link Tracking setting under message Goals and Tracking does not override the utility.

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.

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