Custom Helpers Reference

Collate provides 24 custom helpers to format and manipulate event data. This page also covers the standard Handlebars lookup helper. Use these helpers to transform data in your notification templates.

Combine multiple helpers to create powerful template logic. For example, use filter to show only failed tests, then limit to display only the first 5 items.

Data Extraction

`pluck` - Extract properties from objects

Extracts a specific property from each object in an array. Syntax:

{{#each (pluck array 'propertyName')}}
  {{this}}
{{/each}}

Example:

{{#each (pluck entity.tags 'tagFQN')}}
  <li>{{this}}</li>
{{/each}}

Extracts the tagFQN property from each tag object, resulting in a simple list of tag names.

`filter` - Filter lists by property value

Filters array items based on property values. Syntax:

{{#with (filter array propertyName="value") as |filtered|}}
  {{#each filtered}}
    {{this}}
  {{/each}}
{{/with}}

Example:

{{#with (filter entity.testCaseResultSummary status="Failed") as |failedTests|}}
  <p>Failed tests: {{length failedTests}}</p>
  <ul>
    {{#each failedTests}}
      <li>{{testCaseName}}</li>
    {{/each}}
  </ul>
{{/with}}

Filters test results to show only failed items.

`split` - Split strings into arrays

Splits a string by a delimiter into an array of parts. Syntax:

{{#each (split string "delimiter")}}
  {{this}}
{{/each}}

Example:

{{#each (split entity.fullyQualifiedName ".")}}
  <span class="breadcrumb">{{this}}</span>
{{/each}}

Splits a qualified name like database.schema.table into individual parts for display. Advanced Example - Nested Field Parsing: When parsing hierarchical field names like columns.columnName.tags, combine with lookup:

{{#with (split name '.') as |parts|}}
  {{#if (endsWith name '.tags')}}
    Tags for column {{lookup parts 1}}
  {{else}}
    Property {{lookup parts 2}} of column {{lookup parts 1}}
  {{/if}}
{{/with}}

`limit` - Limit array items

Limits the number of items displayed from an array. Syntax:

{{#each (limit array maxItems)}}
  {{this}}
{{/each}}

Example:

{{#each (limit failedTests 5)}}
  <li>{{testCaseName}}</li>
{{/each}}
{{#if (gt (length failedTests) 5)}}
  <li>... and {{math (length failedTests) '-' 5}} more</li>
{{/if}}

Shows first 5 items and mentions count of remaining items.

Combine limit with other helpers to prevent large notifications:

{{#each (limit (filter testResults status="Failed") 10)}}
  {{name}}
{{/each}}

`lookup` - Access array element by index

Accesses a specific element in an array by its index (0-based). Syntax:

{{lookup array index}}

Example:

{{#with (split entity.fullyQualifiedName ".") as |parts|}}
  Database: {{lookup parts 0}}
  Schema: {{lookup parts 1}}
  Table: {{lookup parts 2}}
{{/with}}

Useful for accessing specific parts after using split helper to parse hierarchical names.

String Operations

`camelCaseToTitle` - Convert camelCase to Title Case

Converts camelCase strings to Title Case format. Syntax:

{{camelCaseToTitle string}}

Example:

Type: {{camelCaseToTitle event.entityType}}

Converts testCase to Test Case, dataAsset to Data Asset.

`startsWith` - Check string prefix

Checks if a string starts with a specific prefix. Syntax:

{{#if (startsWith string "prefix")}}
  Content shown if true
{{/if}}

Example:

{{#if (startsWith name "columns.")}}
  <p>Column property changed</p>
{{/if}}

Useful for identifying specific field types in change descriptions.

`endsWith` - Check string suffix

Checks if a string ends with a specific suffix. Syntax:

{{#if (endsWith string "suffix")}}
  Content shown if true
{{/if}}

Example:

{{#if (endsWith name ".tags")}}
  <p>Tags were modified</p>
{{/if}}

Useful for identifying specific field types in change descriptions.

`textDiff` - Show text differences

Displays the difference between old and new text with strikethrough and highlighting. Syntax:

{{textDiff oldText newText}}

Example:

{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#each changes.updates}}
    {{#if (eq name 'description')}}
      Description change: {{textDiff oldValue newValue}}
    {{/if}}
  {{/each}}
{{/with}}

Renders old text with strikethrough and new text highlighted, making changes easy to spot. Optional Parameters: You can customize the HTML tags used for insertions and deletions:

{{textDiff oldValue newValue insTag="strong" delTag="del"}}

insTag: HTML tag for inserted text (default: "b")
delTag: HTML tag for deleted text (default: "s")

Email notifications remove tags they don’t allow, such as mark.

`truncate` - Shorten text

Shortens text to a maximum length. When the text exceeds the limit, the helper replaces the final character with an ellipsis (…) so the result remains within the requested length. Syntax:

{{truncate text maxLength}}

Example:

{{truncate entity.description 100}}

Returns the original text when it is within the limit. A missing or invalid limit also returns the original text.

Comparison & Logic

`eq` - Equality check

Checks if two values are equal. Syntax:

{{#if (eq value1 value2)}}
  Content shown if equal
{{/if}}

Example:

{{#if (eq event.entityType "testCase")}}
  <p>This is a test case</p>
{{/if}}

`gt` - Greater than

Checks if first value is greater than the second. Syntax:

{{#if (gt value1 value2)}}
  Content shown if greater
{{/if}}

Example:

{{#if (gt (length failedTests) 0)}}
  <p>Some tests failed</p>
{{/if}}

`and` - Logical AND

Combines multiple conditions with logical AND. Syntax:

{{#if (and condition1 condition2)}}
  Content shown if all conditions true
{{/if}}

Example:

{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#if (and (eq event.entityType "table") changes.updates)}}
    <p>Table was updated</p>
  {{/if}}
{{/with}}

Shows content only if both conditions are true.

`or` - Logical OR

Combines multiple conditions with logical OR. Syntax:

{{#if (or condition1 condition2)}}
  Content shown if any condition true
{{/if}}

Example:

{{#if (or (eq status "Failed") (eq status "Aborted"))}}
  <p>Execution had issues</p>
{{/if}}

Shows content if any condition is true.

`not` - Logical NOT

Inverts a condition. Syntax:

{{#if (not condition)}}
  Content shown if condition false
{{/if}}

Example:

{{#if (not entity.owners)}}
  <p>This entity has no owner assigned</p>
{{/if}}

Collection Operations

`groupEventChanges` - Group changes into categories

Organizes field changes into separate categories: updates, additions, and deletions. Syntax:

{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#each changes.updates}}...{{/each}}
  {{#each changes.adds}}...{{/each}}
  {{#each changes.deletes}}...{{/each}}
{{/with}}

Example:

  {{#with (groupEventChanges event.changeDescription) as |changes|}}
    {{#if changes.updates}}
      <h3>Updated Fields:</h3>
      {{#each changes.updates}}
        {{#if (eq name 'description')}}
          <li><strong>Description:</strong> {{oldValue}} → {{newValue}}</li>
        {{else if (eq name 'tags')}}
          <li><strong>Tags:</strong> {{#each oldValue}}{{this}}{{#unless @last}}, {{/unless}}{{/each}} → {{#each newValue}}{{this}}{{#unless @last}},
  {{/unless}}{{/each}}</li>
        {{else if (eq name 'owner')}}
          <li><strong>Owner:</strong> {{oldValue.displayName}} → {{newValue.displayName}}</li>
        {{else if (eq name 'owners')}}
          <li><strong>Owners:</strong> {{#each oldValue}}{{displayName}}{{#unless @last}}, {{/unless}}{{/each}} → {{#each newValue}}{{displayName}}{{#unless @last}},
  {{/unless}}{{/each}}</li>
        {{else if (startsWith name 'columns.')}}
          {{#with (split name '.') as |parts|}}
          <li><strong>Column {{lookup parts 1}}:</strong> Updated {{lookup parts 2}}</li>
          {{/with}}
        {{else if (startsWith name 'extension.')}}
          {{#with (split name '.') as |parts|}}
          <li><strong>Custom Property '{{lookup parts 1}}':</strong> {{oldValue}} → {{newValue}}</li>
          {{/with}}
        {{else}}
          <li><strong>{{name}}:</strong> {{oldValue}} → {{newValue}}</li>
        {{/if}}
      {{/each}}
    {{/if}}

    {{#if changes.adds}}
      <h3>Added Fields:</h3>
      {{#each changes.adds}}
        {{#if (eq name 'tags')}}
          <li><strong>Tags:</strong> {{#each newValue}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}</li>
        {{else if (eq name 'owner')}}
          <li><strong>Owner:</strong> {{newValue.displayName}}</li>
        {{else if (eq name 'owners')}}
          <li><strong>Owners:</strong> {{#each newValue}}{{displayName}}{{#unless @last}}, {{/unless}}{{/each}}</li>
        {{else if (startsWith name 'extension.')}}
          {{#with (split name '.') as |parts|}}
          <li><strong>Custom Property '{{lookup parts 1}}':</strong> {{newValue}}</li>
          {{/with}}
        {{else}}
          <li><strong>{{name}}:</strong> {{newValue}}</li>
        {{/if}}
      {{/each}}
    {{/if}}

    {{#if changes.deletes}}
      <h3>Deleted Fields:</h3>
      {{#each changes.deletes}}
        {{#if (eq name 'tags')}}
          <li><strong>Tags:</strong> <del>{{#each oldValue}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}</del></li>
        {{else if (eq name 'owner')}}
          <li><strong>Owner:</strong> <del>{{oldValue.displayName}}</del></li>
        {{else if (eq name 'owners')}}
          <li><strong>Owners:</strong> <del>{{#each oldValue}}{{displayName}}{{#unless @last}}, {{/unless}}{{/each}}</del></li>
        {{else if (startsWith name 'extension.')}}
          {{#with (split name '.') as |parts|}}
          <li><strong>Custom Property '{{lookup parts 1}}':</strong> <del>{{oldValue}}</del></li>
          {{/with}}
        {{else}}
          <li><strong>{{name}}:</strong> <del>{{oldValue}}</del></li>
        {{/if}}
      {{/each}}
    {{/if}}
  {{/with}}

`hasFieldInChanges` - Check if field was modified

Checks if a specific field was modified in the change description. Syntax:

{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#if (hasFieldInChanges changes "fieldName")}}
    Content shown if field changed
  {{/if}}
{{/with}}

The first argument is the grouped changes from groupEventChanges, not event. The second argument is the field name as recorded in the change event, for example entityStatus or testCaseResult. The helper checks the updated, added, and deleted fields. Example:

{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#if (hasFieldInChanges changes "testCaseResult")}}
    <p>Test results changed</p>
  {{/if}}
{{/with}}

Must be used with changes from groupEventChanges. Passing event or event.changeDescription directly doesn’t work. A create event has no list of changes, so the helper returns false for it. Soft-delete and restore events list only the deleted field.

Example: data contract status change

{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#if (hasFieldInChanges changes "entityStatus")}}
    <p>Contract status is now {{entity.entityStatus}}</p>
  {{/if}}
{{/with}}

`length` - Get array/string length

Returns the number of items in an array or characters in a string. Syntax:

{{length array}}

Example:

{{#if (gt (length entity.tags) 0)}}
  <p>Tags count: {{length entity.tags}}</p>
{{/if}}

Formatting

`formatDate` - Format timestamps

Converts timestamps to human-readable date and time format. Syntax:

{{formatDate event.timestamp}}

Example:

<p>Test executed at {{formatDate entity.testCaseResult.timestamp}}</p>

Converts timestamps to format like: 2025-11-13 14:30:00 The helper takes one value and has no format or timezone option. The output is always yyyy-MM-dd HH:mm:ss in the timezone of the Collate server. It accepts a timestamp in milliseconds, a date, or a number written as text. For any other value it returns the value unchanged, and for an empty value it returns an empty string.

`buildEntityUrl` - Generate UI links

Creates a clickable URL that opens the entity in Collate UI. Syntax:

{{buildEntityUrl event.entityType entity}}
{{buildEntityUrl event.entityType entity "tasks"}}

The first argument is the entity type and the second is the entity. You can also pass the entity type and a fully qualified name, for example {{buildEntityUrl 'table' entity.fullyQualifiedName}}. This form renders an empty link for data contracts, queries, and ingestion pipelines, so pass the full entity for those. For a data contract, the link opens the contract tab of its asset. A single argument, such as {{buildEntityUrl entity}}, doesn’t work and renders an empty link. The optional last argument adds the entity’s Activity Feed to the link. Use "tasks" to open the Tasks view of the feed. Any other value, for example "all", opens the All view. For a test case, any value of this argument opens the Issues tab instead. Example:

<a href="{{buildEntityUrl event.entityType entity}}">
  {{entity.fullyQualifiedName}}
</a>

Generates a link like: https://your-Collate/table/database.schema.table

`parseEntityLink` - Extract entity from link strings

Extracts entity information from entity link strings. Syntax:

{{#with (parseEntityLink linkString) as |link|}}
  {{link.entityFQN}}
{{/with}}

Example:

{{#with (parseEntityLink entity.entityLink) as |link|}}
  Tested entity: {{link.entityFQN}}
  Tested column: {{link.arrayField}}
{{/with}}

The returned object contains entityType, entityFQN, field, arrayField, and arrayValue. For a column test, arrayField contains the column name.

`renderTableSample` - Show a table of failed rows

Draws a small table with a sample of the rows that failed a data quality test. Use it in templates for test case alerts. Simple version: Show up to 10 columns and 3 rows.

{{{renderTableSample entity.failedRowsSample}}}

Full version: Show the tested column in bold and set the maximum number of columns and rows.

{{#with (parseEntityLink entity.entityLink) as |link|}}
  {{{renderTableSample entity.failedRowsSample link.arrayField 10 3}}}
{{/with}}

10 is the maximum number of columns to show.
3 is the maximum number of rows to show.
link.arrayField is the name of the column that the test checks.

When more data is available, the table adds ... and N more. Use three curly braces ({{{ }}}). With two curly braces, the notification displays the table as raw code.

`processMentions` - Convert mentions to links

Converts @mention syntax to clickable user profile links. Typically used with user-entered descriptions or comments that may contain @mentions to team members. Syntax:

{{{processMentions text}}}

Example:

<p>{{{processMentions entity.description}}}</p>

Converts mentions added in the rich text editor to links to the user’s profile. Text typed as a plain @john.doe stays unchanged.

Use three curly braces {{{ to render HTML output without escaping.

`resolveDomain` - Resolve domain references

Displays domain names even when passed as object references. Syntax:

{{resolveDomain domainReference}}

Example:

{{#each entity.domains}}
  <li>Domain: {{resolveDomain this}}</li>
{{/each}}

This helper gracefully handles multiple input types:

Domain object references: {{resolveDomain domain}}
Already-resolved domain strings: {{resolveDomain "domain-name"}}
Null/undefined values: Returns (no domain)

Math Operations

`math` - Perform calculations

Performs mathematical operations on numbers. Syntax:

{{math value1 "operator" value2}}

The helper takes exactly three values: a number, an operator, and a second number. It ignores anything after the second number. Supported Operators:

+ - Addition
- - Subtraction
* - Multiplication
/ - Division
% - Remainder (modulo)
round - Round the first number to the number of decimal places given as the second number

Example:

Success rate: {{math (math (math passedTests "/" totalTests) "*" 100) "round" 2}}%

Calculates: (passedTests ÷ totalTests) × 100, rounded to 2 decimal places. round is a separate step, so nest one math call inside another for each step.

If a value isn’t a number, the operator isn’t supported, or you divide by zero with /, the helper returns 0 and doesn’t show an error. A remainder by zero (% with 0) returns NaN.

More Examples:

{{math 10 '+' 5}}              <!-- 15 -->
{{math 100 '-' 30}}            <!-- 70 -->
{{math 5 '*' 3}}               <!-- 15 -->
{{math 20 '/' 4}}              <!-- 5 -->
{{math 3.14159 'round' 2}}     <!-- 3.14 -->

Next Steps

Learn Handlebars basics → Handlebars Templating Guide
Understand available data → Template Context Reference

Overview

Data Quality & Observability

Custom Helpers Reference

Custom Helpers Reference

Data Extraction

`pluck` - Extract properties from objects

`filter` - Filter lists by property value

`split` - Split strings into arrays

`limit` - Limit array items

`lookup` - Access array element by index

String Operations

`camelCaseToTitle` - Convert camelCase to Title Case

`startsWith` - Check string prefix

`endsWith` - Check string suffix

`textDiff` - Show text differences

`truncate` - Shorten text

Comparison & Logic

`eq` - Equality check

`gt` - Greater than

`and` - Logical AND

`or` - Logical OR

`not` - Logical NOT

Collection Operations

`groupEventChanges` - Group changes into categories

`hasFieldInChanges` - Check if field was modified

`length` - Get array/string length

Formatting

`formatDate` - Format timestamps

`buildEntityUrl` - Generate UI links

`parseEntityLink` - Extract entity from link strings

`renderTableSample` - Show a table of failed rows

`processMentions` - Convert mentions to links

`resolveDomain` - Resolve domain references

Math Operations

`math` - Perform calculations

Next Steps

​Custom Helpers Reference

​Data Extraction

​pluck - Extract properties from objects

​filter - Filter lists by property value

​split - Split strings into arrays

​limit - Limit array items

​lookup - Access array element by index

​String Operations

​camelCaseToTitle - Convert camelCase to Title Case

​startsWith - Check string prefix

​endsWith - Check string suffix

​textDiff - Show text differences

​truncate - Shorten text

​Comparison & Logic

​eq - Equality check

​gt - Greater than

​and - Logical AND

​or - Logical OR

​not - Logical NOT

​Collection Operations

​groupEventChanges - Group changes into categories

​hasFieldInChanges - Check if field was modified

​length - Get array/string length

​Formatting

​formatDate - Format timestamps

​buildEntityUrl - Generate UI links

​parseEntityLink - Extract entity from link strings

​renderTableSample - Show a table of failed rows

​processMentions - Convert mentions to links

​resolveDomain - Resolve domain references

​Math Operations

​math - Perform calculations

​Next Steps

Custom Helpers Reference

Data Extraction

`pluck` - Extract properties from objects

`filter` - Filter lists by property value

`split` - Split strings into arrays

`limit` - Limit array items

`lookup` - Access array element by index

String Operations

`camelCaseToTitle` - Convert camelCase to Title Case

`startsWith` - Check string prefix

`endsWith` - Check string suffix

`textDiff` - Show text differences

`truncate` - Shorten text

Comparison & Logic

`eq` - Equality check

`gt` - Greater than

`and` - Logical AND

`or` - Logical OR

`not` - Logical NOT

Collection Operations

`groupEventChanges` - Group changes into categories

`hasFieldInChanges` - Check if field was modified

`length` - Get array/string length

Formatting

`formatDate` - Format timestamps

`buildEntityUrl` - Generate UI links

`parseEntityLink` - Extract entity from link strings

`renderTableSample` - Show a table of failed rows

`processMentions` - Convert mentions to links

`resolveDomain` - Resolve domain references

Math Operations

`math` - Perform calculations

Next Steps