See related
No related articles

Data validation workflow helpers

Last Update: Dec 2024 • Est. Read Time: 5 MIN
To check plan availability, see the pricing page.

Data validation helpers are designed to generate, verify, and reformat data for the purposes of utilizing it in an expected format.

In this article:

Random ID

{{randomId}} generates a string of random alphanumeric characters. For example, you can use it to create a more user-friendly conversation tracking number to share with customers instead of the longer, auto-generated conversation ID. The length of the string generated by this helper is set to 10 characters by default, but a different length can be specified using the optional size parameter if needed.

  • {{{randomId}}} will result in a randomly generated string like "KGGCJG3FGP"
  • {{{randomId size=6}}} will result in a randomly generated string like "6O9L4M"

Email Address Validation

The /#fn:isValidEmailAddress function helper checks whether a string contains the @ character with at least one character on either side, using the regex "/.+@.+/". It returns a boolean value of either true or false. This is useful for checking if a string may or may not be a valid email address, though there are scenarios in which a value of true may be returned for an invalid email address.

  • Given steps.1.attributes.data.email = "www.kustomer.com"
    /#fn:isValidEmailAddress,steps.1.attributes.data.email resolves to the boolean value false

  • Given steps.1.attributes.data.email = "k@t"
    /#fn:isValidEmailAddress,steps.1.attributes.data.email resolves to the boolean value true

Phone Number Validation

The /#fn:isValidPhoneNumber function helper checks if a string resolves to a valid phone number format, returning either a boolean value of true or false. It accepts numbers of various formats (for example, +1 (555) 123-4567 or 1234567), though numbers from outside the US and Canada must include a country code (e.g. "+44 7911 123456").

This helper uses the phoneutl.parse method from the Google's "libphonenumber" library to validate phone number values.

  • Given steps.1.attributes.data.phone = "73255".
    /#fn:isValidPhoneNumber,steps.1.attributes.data.phone resolves to the boolean value false

Escape

{{escape}} detects HTML special characters &, <, >, ', and ", and converts them to their corresponding HTML entities, even inside a triple-stache expression.

  • {{{escape 'Zak & Sara'}}} resolves to the string "Zak &amp; Sara"

Escape RegExp

{{escapeRexExp}} adds escape sequences to help display literal representations of special characters that may have alternate meanings in code, such as ^, $, ., *, +, ?, (, ), [, ], {, }, and |.

  • {{{escapeRegExp '(https://kustomer.com/)'}}} resolves to the string "\\(https://kustomer\\.com/\\)"

    Note: Additional escape sequence characters are included to properly escape an escape sequence when passed on.

Markdown to HTML

The {{markdownToHTML}} helper converts text formatted in Markdown (a popular markup language) into equivalent HTML syntax, including escape sequencing for necessary characters.

  • Given steps.1.custom.markdownStr = "**[Kustomer](https://www.kustomer.com)**"
    {{markdownToHTML steps.1.custom.markdownStr}} resolves to the string "<strong><a href=\"https://www.kustomer.com\">Kustomer</a></strong>"

Remove Markdown

The {{removeMarkdown}} helper removes Markdown syntax and formatting, resulting in a plain text string.

  • Given steps.1.custom.markdownStr = "**[Kustomer](https://www.kustomer.com)**"
    {{removeMarkdown steps.1.custom.markdownStr}} resolves to the string "Kustomer"

URI Encoding

The {{uriEncode}} helper converts a string into an encoded format suitable for internet transmission, while {{uriDecode}} does the reverse.

  • Given steps.1.attributes.data.string = "Kustomer 2: Electric Boogaloo"
    {{uriEncode steps.1.attributes.data.string}} resolves to the encoded string "Kustomer%202%3A%20Electric%20Boogaloo"

  • {{uriDecode Kustomer%202%3A%20Electric%20Boogaloo}} resolves to the decoded string "Kustomer 2: Electric Boogaloo"

URI encoding and decoding is also available with variant function helpers /#fn:URIEncode and /#fn:URIDecode.

  • Given steps.1.attributes.data.string =  "Kustomer%202%3A%20Electric%20Boogaloo"
    /#fn:URIDecode,steps.1.attributes.data.string resolves to the decoded string "Kustomer 2: Electric Boogaloo"

Base64 Encoding

The {{#base64Encode}} block helper converts a string of text into Base64-encoded binary data, while {{#base64Decode}} does the reverse. An optional uriEncode parameter accepts boolean values (with a default value of false) and can be used to apply URI encoding to any output string.

  • Given steps.1.attributes.data.string = "Kustomer 2: Electric Boogaloo"
    {{#base64Encode}}{{steps.1.attributes.data.string}}{{/base64Encode}} resolves to the encoded string "S3VzdG9tZXIgMjogRWxlY3RyaWMgQm9vZ2Fsb28="

  • {{#base64Decode uriEncode='true'}}S3VzdG9tZXIgMjogRWxlY3RyaWMgQm9vZ2Fsb28={{/base64Decode}} resolves to the decoded string "Kustomer%202%3A%20Electric%20Boogaloo"

Note: Due to the way in which these block helpers accept an input, {{else}} blocks will have no discernible effect.

Auth HMAC

The {{authHMAC}} helper generates a hash-based message authentication code (HMAC) from a string, using a hash function and secret key for verification. It accepts optional string parameters for secretKey, algorithm, and encoding. The algorithm parameter supports all standard cryptographic hash function configurations for HMAC, while the encoding parameter supports all standard key encoding methods.

  • {{{authHMAC steps.1.custom.password secretKey='12345' algorithm='sha256' encoding='base64'}}}

The algorithm parameter supports all standard cryptographic hash function configurations for HMAC, while the encoding parameter supports all standard key encoding methods.

Get App Setting

/#fn:getAppSetting is a function helper designed to review an installed app in your org and return the stored value for a specified setting field. For example, it might be used to access the values stored in the API Key, Kustomer URL, and Seconds until send settings fields found within the installed Stella Connect app.

When using this helper, up to three parameters may be utilized, noted as "key", "default value", and "default value type". Whichever parameter is used last must end using the # symbol.

The "key" identifies the app and specific settings field. If only the "key" is provided, the helper will return the stored value as a string.

Stored settings values can be queried and returned using the "key" parameter, which must specify the app and nested field names (this information can be obtained by sending a GET request to the /v1/apps API endpoint and reviewing data for the app in question).

Assume the following Stella Connect app settings: apiKey = "12345", kustomerBaseURL = "https://companycorp.kustomerapp.com", secondsUntilSend = 86400

  • /#fn:getAppSetting,stella_connect_kustomer.default.kustomerBaseURL# resolves to the string "https://companycorp.kustomerapp.com"

  • /#fn:getAppSetting,stella_connect_kustomer.default.secondsUntilSend# resolves to the number value 86400

A variant {{{ setting }}} handlebars helper may also be used to similar effect. This variant utilizes the same three parameters (without the need for the # symbol), but because it is a handlebars helper, it will only ever output a string value.

  • {{{ setting stella_connect_kustomer.default.secondsUntilSend }}} resolves to the string ”86400”

Note: The {{{ setting }}} helper is unusual, in that it requires three handlebars wrappers, and separated spacing.

When attempting to use either variant to access the settings of a privately installed or custom app, the org number in which the app is installed may need to be included in the app name.

  • /#fn:getAppSetting,mycustomapp_5e163d54a1995b0023788621.default.authToken#
  • {{{ setting mycustomapp_5e163d54a1995b0023788621.default.authToken }}}

App settings that are marked as containing a secret will return masked strings.

  • /#fn:getAppSetting,stella_connect_kustomer.default.apiKey# resolves to the string "****"
  • {{{ setting stella_connect_kustomer.default.apiKey }}} resolves to the string "****"

Masked values can still be incorporated into further actions when needed. For example, a masked value containing an authorization token can be passed directly into the headers of an API call.

  • {"headers": {"Authorization": "/#fn:getAppSetting,stella_connect_kustomer.default.apiKey#"}}
  • {"headers": {"Authorization": "{{{ setting stella_connect_kustomer.default.apiKey }}}"}}

Should the "key" ever fail to be recognized as a valid app or app setting, or if no value is found within an identified setting, a value of null will be returned, resulting in an empty object or string. In these scenarios, the "default value" parameter is designed to output a backup value.

  • /#fn:getAppSetting,stella_connect_kustomer.default.password# resolves to an empty object
  • /#fn:getAppSetting,stella_connect_kustomer.default.password,1234# resolves to the string "1234"
  • {{{ setting stella_connect_kustomer.default.password 1234 }}} resolves to the string "1234"

The "default value type" parameter indicates the intended data-type of the "default value" output, allowing the helper to attempt to return the value properly. This parameter defaults to a string value, and makes no significant impact when used in conjunction with the handlebars helper variant.

  • /#fn:getAppSetting,stella_connect_kustomer.default.password,1234,number# resolves to the number value 1234
  • {{{ setting stella_connect_kustomer.default.password 1234 number }}} resolves to the string "1234"

The following longhand value data-types are supported:

  • string
  • number
  • boolean

Related articles: