Articles in this section

Handlebars helper reference

Tom Santiago
Updated

Handlebars helpers extend the Handlebars language with functions for math, string handling, dates, logic, and lists. You use them anywhere integrator.io accepts a Handlebars template — field mappings, HTTP request bodies and relative URIs, file names, lookups, and transformations. This reference lists every helper integrator.io supports, grouped by category, with its syntax and what it does. Select a helper name for its parameters, examples, and usage notes. For how templates and expressions work, see Handlebars overview and Handlebars syntax.

Note: NetSuite import mappings and lookups use a smaller helper set. The mapping rows and lookup expressions of a NetSuite import are evaluated by the Celigo bundle (SuiteBundle or SuiteApp) inside your NetSuite account, which supports only part of this list. A helper that the bundle doesn't support fails every record with INVALID_HANDLE_BAR_EXPRESSION … "Missing helper: "<name>"", even when the Playground renders the same expression. Helpers that aren't available in NetSuite import mappings include pluck, eq, isEmpty, startsWith, inArray, not, some, isTruthy, isFalsey, jsonParse, padLeft, padRight, trimLeft, trimRight, htmlEncode, htmlDecode, reverse, unique, typeOf, modulo, addCommas, after, before, and the case helpers (camelcase, dashcase, dotcase, pascalcase, pathcase, snakecase, sentence). Arithmetic, basic string, date, and block helpers (for example, add, sum, multiply, toFixed, join, replace, regexReplace, #if, #compare, #contains, #each, #filter) are available. The supported set changes with bundle releases, so use the mapping editor's Preview to check an expression before you save it.

Aggregate helpers

Helper Syntax Description
avg {{avg number1 number2...}} Calculates the arithmetic mean of two or more numeric values.
sum {{sum arrayField}} Adds all numeric elements of an array field. To add several separate values or fields, use add.

Block helpers

Helper Syntax Description
#and {{#and field1 field2}} expr {{else}} expr {{/and}} Renders one expression if both arguments have a non-empty value, and a fallback {{else}} expression if either argument is empty, null, or undefined.
#compare {{#compare field operator field}}expr{{else}}expr{{/compare}} Compares two values with a comparison operator and renders its block when the comparison is true.
#contains {{#contains array value}} Checks whether a value is present in an array or string, and renders one of two blocks based on the result.
#each {{#each field}} {{this}} {{/each}} Iterates over an array or object, rendering the block once for each element.
#filter {{#filter array value arrayProperty}} expr {{else}} expr {{/filter}} Iterates over an array and renders the block once for each element whose value or property matches a specified value.
#if...else {{#if field}}contentIfTruthy{{else}}contentIfFalsy{{/if}} Renders a block of content when a condition is truthy, and optionally renders an alternative block with {{else}} when the condition is falsy.
#ifEven {{#ifEven field}} expr {{else}} expr {{/ifEven}} Checks whether a numeric field is even and renders one expression if true, or an optional {{else}} expression if the value is odd.
#inArray {{#inArray array value}} expr {{else}} expr {{/inArray}} Checks whether a specified value exists in an array and renders one expression if found, or an optional {{else}} expression if not.
#isEmpty {{#isEmpty collection}} expr {{else}} expr {{/isEmpty}} Renders one expression when a collection is empty, missing, or null, and an optional {{else}} expression when it contains items.
#neither {{#neither field1 field2}} expr {{else}} expr {{/neither}} Renders one expression when both arguments are empty, null, or undefined, and an optional {{else}} expression when one or both arguments have a non-empty value.
#not {{#not value}} expr {{else}} expr {{/not}} Inverts a value's presence: it renders one expression when the input is empty, null, or undefined, and an optional {{else}} expression when the input has a non-empty value.
#or {{#or field1 field2}} expr {{else}} expr {{/or}} Renders one expression when at least one argument has a non-empty value, and an optional {{else}} expression when both arguments are empty, null, or undefined.
#some {{#some array conditionFn}} expr {{else}} expr {{/some}} Checks whether at least one element in an array satisfies a condition and renders one expression if true, or an optional {{else}} expression if no elements match.
#startsWith {{#startsWith prefix testString}} expr {{else}} expr {{/startsWith}} Checks whether a string begins with a specified prefix and renders one expression if it matches, or an optional {{else}} expression if it doesn't.
#unless {{#unless field}} expr {{else}} expr {{/unless}} Renders one expression when a field is empty, null, or undefined, and an optional {{else}} expression when the field has a non-empty value.
#with {{#with object}} {{field1}} {{field2}} {{/with}} Sets the context to a nested object for all expressions inside the block.
Nested block helpers and raw blocks — Nest one block helper inside another, and use raw blocks ({{{{ }}}}) to output content literally.

Data variables

Helper Syntax Description
@first {{#each field}}{{#if @first}} expr {{/if}}{{/each}} Evaluates to true for the first element when iterating over an array or object with #each.
@index {{#each field}}{{@index}}{{/each}} Returns the zero-based position of the current element during a #each iteration over an array or object.
@key {{#each field}}{{@key}}{{/each}} Returns the current key name when iterating over an object with #each, or the numeric index when iterating over an array.
@last {{#each field}}{{#if @last}} expr {{/if}}{{/each}} Evaluates to true for the final element when iterating over an array with #each.
.length {{field.length}} Returns the number of characters in a string or the number of elements in an array.
@root {{@root.fieldName}} References the top-level context object from anywhere in a template, including inside nested #each blocks where the context has shifted to a child element.
this {{this}} References the current context inside a block helper — the current array element or key value in a #each loop.

Date/time helpers

Helper Syntax Description
dateAdd {{dateAdd dateField offsetField timeZoneField}} Adds or subtracts a time offset, in milliseconds, from a date and returns the result as an ISO 8601 timestamp.
dateFormat {{dateFormat oFormat date iFormat timezone}} Converts a date into a specified output format, and can optionally parse a custom input format and apply a time zone.
timestamp {{timestamp format timezone}} Returns the current date and time as a formatted string.

List helpers

Helper Syntax Description
after {{after array n}} Returns a new array that excludes the first n elements of the input array.
arrayify {{arrayify value}} Casts any value into an array.
before {{before array n}} Returns a new array excluding the last n elements of the input array.
pluck {{pluck array "property"}} Extracts the value of a specified property from each element in an array of objects and returns the results as a new array.
sort {{sort field [number="true"] [reverse="true"]}} Arranges the elements of an array in ascending or descending order.
split {{split field delimiter index}} Breaks a string into substrings based on a specified delimiter and returns either a specific element by index or the element at position 0 by default.
unique {{unique array}} Returns a new array with all duplicate values removed, preserving the order of first occurrences.

Logic-check helpers

Helper Syntax Description
eq {{eq firstVal secondVal}} Compares two values and returns true if they are equal using loose equality — meaning a string "5" and the integer 5 are considered equal.
hasNoItems {{hasNoItems value}} Returns true when an array has no elements or an object has no keys.
hasOwn {{hasOwn object "key"}} Checks whether a specified key exists as a direct property of an object and returns true if it does.
isFalsey {{isFalsey value}} Returns true if the input value is absent or empty, and false if it has a meaningful value.
isTruthy {{isTruthy value}} Returns true when the input has a meaningful value, and false when it is absent or empty.

Miscellaneous helpers

Helper Syntax Description
aws4 {{{aws4 accessKey secretKey sessionToken region serviceName}}} Generates an AWS Signature Version 4 string for authenticating API requests to Amazon Web Services.
bytes {{bytes input precision}} Converts a numeric byte value into a human-readable size string (for example, 825399 → 825.4 kB).
getLookupCacheData {{getLookupCacheData _lookupCacheAliasID key pathToValue defaultValue}} Reads a value from a lookup cache and inserts it in your Handlebars template.
getValue {{getValue fieldPath "defaultValue"}} Retrieves the value at a specified field path and returns an optional fallback if the field is missing or null.
jsonParse {{{jsonParse string}}} Parses a valid JSON string and returns the resulting object or array.
lookup {{lookup.dynamicLookup}} or {{lookup "staticLookup" field}} Retrieves data from a lookup you define in the same flow step.
typeOf {{typeOf value}} Returns the JavaScript type of a given value as a lowercase string.

Numeric helpers

The avg and sum helpers also work on numbers — see Aggregate helpers.

Helper Syntax Description
abs {{abs number}} Returns the absolute value of a number, removing any negative sign.
add {{add number1 number2...}} Sums two or more numeric values and returns the total.
addCommas {{addCommas value}} Formats a number by inserting commas as thousands separators (for example, 1234567 → 1,234,567).
ceil {{ceil field}} Rounds a numeric value up to the nearest whole integer.
divide {{divide number1 number2}} Returns the quotient of two numeric values.
floor {{floor field}} Rounds a numeric value down to the nearest whole integer.
modulo {{modulo a b}} Returns the remainder when dividing one number by another.
multiply {{multiply value1 value2}} Returns the product of two numeric values.
random {{random "method" length}} Generates a random string or numeric sequence.
round {{round field}} Rounds a numeric value, including a numeric string, to the nearest whole integer.
subtract {{subtract minuend subtrahend}} Returns the difference between two numeric values.
toExponential {{toExponential field fractionDigits}} Converts a numeric value to exponential (scientific) notation.
toFixed {{toFixed field digits}} Formats a numeric value to a specified number of decimal places and returns the result as a string.
toPrecision {{toPrecision field precision}} Formats a number to a specified number of significant digits.

String helpers

Helper Syntax Description
base64Decode {{base64Decode base64String "decodeFormat"}} Decodes a base64-encoded string into a specified output format.
base64Encode {{{base64Encode base64String}}} Encodes a string or field value as a base64 string.
camelcase {{camelcase value}} Converts a string to camelCase format, removing non-alphanumeric characters (spaces, dashes, slashes, underscores) and capitalizing the first letter of each word after the first.
capitalize {{capitalize field}} Capitalizes the first letter of a string and leaves all other characters unchanged.
capitalizeAll {{capitalizeAll field}} Capitalizes the first letter of every word in a string, leaving all other characters unchanged.
chop {{chop value}} Removes leading and trailing whitespace and non-alphanumeric characters from a string.
dashcase {{dashcase value}} Converts a string to dash-case by replacing spaces, underscores, and other non-word characters with hyphens and lowercasing the result.
decodeURI {{{decodeURI field}}} Converts a URI-encoded string back to its decoded form, replacing encoded characters such as %20 with their original equivalents (for example, a space).
dotcase {{dotcase value}} Converts a string to dot.case format by replacing spaces, dashes, underscores, and other non-word characters with periods and lowercasing the result.
encodeURI {{{encodeURI field}}} Converts special characters in a string to their percent-encoded equivalents, making the string safe for use in a URL.
hash {{hash algorithm encoding field}} Applies a cryptographic hash function to a string and returns the result in a specified encoding format.
hmac {{hmac "algorithm" key "encoding" field keyEncoding}} Generates an HMAC (Hash-based Message Authentication Code) from a field or string value using a secret key and a supported hash algorithm.
htmlDecode {{{htmlDecode value}}} Converts HTML-encoded entities such as &lt;, &amp;, and &quot; back to their readable characters.
htmlEncode {{htmlEncode value}} Converts reserved HTML characters such as <, >, &, ', and " into their HTML entity equivalents.
join {{join delimiterField field1 field2...}} Concatenates two or more values with a specified delimiter between each item.
jsonEncode {{jsonEncode field}} Outputs a string field value without surrounding quotes.
jsonSerialize {{{jsonSerialize objectToSerialize}}} Converts an object or array into a JSON-formatted string.
jsonStringify {{{jsonStringify value}}} Converts a value into JSON text.
lowercase {{lowercase field}} Converts all letters in a string to lowercase.
occurrences {{occurrences str substring}} Returns the number of times a specified substring appears in a string.
ordinalize {{ordinalize value}} Converts a number into its ordinal string form (for example, 1 → 1st, 2 → 2nd, 3 → 3rd).
padLeft {{padLeft value length "char"}} Adds characters to the beginning of a string until it reaches a specified length.
padRight {{padRight value length "char"}} Adds characters to the end of a string until it reaches a specified length.
pascalcase {{pascalcase value}} Converts a string to PascalCase format, capitalizing the first letter of each word and removing all separators.
pathcase {{pathcase value}} Converts a string to path/case format by replacing spaces, dashes, underscores, and other non-word characters with forward slashes and lowercasing the result.
regexMatch {{regexMatch field regex index options}} Searches a string using a regular expression and returns the matching substring.
regexReplace {{regexReplace field replacement regex options}} Replaces substrings that match a regular expression pattern with a specified replacement value.
regexSearch {{regexSearch field regex options}} Returns the zero-based index of the first substring that matches a regular expression pattern within a string.
removefirst {{removefirst str substring}} Removes the first occurrence of a specified substring from a string, leaving all later occurrences unchanged.
replace {{replace field oldSubstring newSubstring}} Substitutes all occurrences of a specified substring in a field with a new value.
replacefirst {{replacefirst str a b}} Replaces only the first occurrence of a specified substring with another value, leaving all later occurrences unchanged.
reverse {{reverse value}} Reverses the order of characters in a string.
sanitize {{sanitize string}} Removes all HTML markup tags from a string and returns the plain text content.
sentence {{sentence value}} Converts text to sentence case: the first letter of each sentence is capitalized and all remaining letters are lowercased.
snakecase {{snakecase value}} Converts a string to snake_case format by replacing spaces, dashes, and other non-word characters with underscores and lowercasing the result.
stripProtocol {{stripProtocol url}} Removes the protocol prefix (for example, http://, https://) from a URL and returns a protocol-relative path.
stripQuerystring {{stripQuerystring url}} Removes everything from the ? onward in a URL, returning only the base path.
substring {{substring stringField startIndex endIndex}} Extracts a portion of a string from a specified start index up to (but not including) a specified end index.
trim {{trim field}} Removes leading and trailing whitespace from a string.
trimLeft {{trimLeft value}} Removes leading whitespace from the beginning of a string, leaving trailing whitespace unchanged.
trimRight {{trimRight value}} Removes trailing whitespace from the end of a string, leaving leading whitespace unchanged.
truncateWords {{truncateWords string limit suffix}} Shortens a string to a specified number of words and optionally appends a suffix.
uppercase {{uppercase field}} Converts all letters in a string to uppercase.

Guides and examples

These articles cover syntax details and worked examples that apply across helpers.

Article Description
Access parent-level variables in a Handlebars #each loop Reach values outside the current #each context with ../ or @root.
Build a database query based on multiple exported values Collect exported values into lists with a script, then reference them in one SQL lookup query.
Calculate the number of days between dates Convert dates to seconds since the epoch and compare them with dateFormat, add, and #compare.
Convert a multiline field value to a single line Escape newline characters with jsonEncode and replace them with the replace helper.
Date and time format codes The moment.js format tokens accepted by the dateFormat and timestamp helpers, with sample output.
Escape Handlebars expressions Render an expression as literal text with a backslash (\{{ }}) or a raw block.
Handlebars comments Inline ({{! }}) and block ({{!-- --}}) comment syntax, and when each is safe to use.
Handlebars helper equivalents for common JavaScript functions JavaScript string methods (split, replace, match, exec) mapped to their Handlebars helper equivalents.
hashOptions fields for the hash helper The hashOptions fields (body, URI, method, headers, encrypted key) available to the hash helper when you build an authentication signature.
integrator.io supported time zones The IANA time zone identifiers accepted by the timeStamp and dateAdd helpers.
Literal segments and Handlebars identifiers Which characters and reserved words are invalid in an identifier, and how to reference them with [ ] bracket notation.
Regular expressions (regex) How regex works with the regexMatch, regexReplace, and regexSearch helpers, with the parameters they share.
Remove rich text or HTML markup from RTF fields Strip HTML tags and &nbsp; entities from a rich-text field with regexReplace.
Set up JSON mapping for an HTTP(S) import from a NetSuite saved search A complete #each template that maps saved-search rows and line items to a JSON request body.
Use Handlebars in static lookups Enter Handlebars expressions in the Export Field of a static lookup on the mapping screen.
Verify the default time zone for the timeStamp helper in imports Why timeStamp in import configuration fields should set a time zone explicitly, and how to check your imports.
Whitespace in Handlebars expressions Avoid leading and internal whitespace in expressions, and close each expression before starting another.