​

Troubleshooting

​

Template Validation Errors

​

Syntax Error: Invalid Handlebars Syntax

1. Unbalanced brackets
   • Every {{#if}} needs a closing {{/if}}
   • Every {{#each}} needs a closing {{/each}}
   <!-- ❌ Missing closing /if -->
   {{#if entity.owner}}
     Owner: {{entity.owner}}
   
   <!-- ✅ Correct -->
   {{#if entity.owner}}
     Owner: {{entity.owner}}
   {{/if}}
   
2. Incorrect helper syntax
   • Verify helper names are spelled correctly.
   • Check that parentheses are balanced.
   <!-- ❌ Misspelled helper -->
   {{formatDate entity.updatedAt}}
   
   <!-- ✅ Correct -->
   {{formatDate entity.updatedAt}}
   
3. Missing quotes in string attributes
   • String values must be quoted.
   <!-- ❌ Missing quotes -->
   {{#if (eq status Failed)}}
   
   <!-- ✅ Correct -->
   {{#if (eq status "Failed")}}
   

• Use the Validate button in the template editor before saving.
• Check brackets are balanced: each opening has a closing pair.
• Verify helper names match exactly (case-sensitive).
• Add quotes around string values in helper attributes.

​

Max Length Error: Template Exceeds 10,240 Characters

• Template is too comprehensive.
• Too many examples or detailed change descriptions.
• Large data structures being displayed without filtering.

1. Simplify the template
   • Remove unnecessary formatting.
   • Remove comments.
   • Use shorter variable names where possible.
2. Use the limit helper
   <!-- Show only first 10 changes instead of all -->
   {{#each (limit (filter changes.updates) 10)}}
     {{name}}
   {{/each}}
   
3. Show summaries instead of details
   <!-- ❌ Shows all field details (verbose) -->
   {{#each changes.updates}}
     {{name}}: {{oldValue}} → {{newValue}}
   {{/each}}
   
   <!-- ✅ Shows only count and highlights (concise) -->
   {{length changes.updates}} fields updated
   {{#if entity.owner}}(Owner: {{entity.owner}}){{/if}}
   
4. Remove conditional sections for optional data
   <!-- Only show tags if they exist -->
   {{#if (gt (length entity.tags) 0)}}
     Tags: {{#each (limit entity.tags 5)}}{{tagFQN}}, {{/each}}
   {{/if}}
   
5. Split into multiple templates
   • Create separate templates for detailed vs. summary views.
   • Use different templates for different entity types.

​

Field Name Not Recognized

• Incorrect property path.
• Property doesn’t exist for this entity type.
• Typo in property name.

1. Verify property names
   • Check Template Context Reference
   • Use dot notation: entity.owner, not entity.owner_name
2. Use conditionals for optional fields
   {{#if entity.owner}}
     Owner: {{entity.owner}}
   {{/if}}
   
3. Check for property availability by entity type
   {{#if (eq event.entityType "testCase")}}
     Status: {{entity.testCaseStatus}}
   {{/if}}
   
   {{#if (eq event.entityType "table")}}
     Columns: {{length entity.columns}}
   {{/if}}
   

​

Notifications Not Rendering Correctly

​

Notifications Look Garbled or Misformatted

• Text appears without line breaks.
• HTML tags visible in notification.
• Formatting looks different on different channels.

• HTML is malformed.
• Characters aren’t escaped properly.
• Channel-specific formatting issues.

1. Validate HTML
   • Ensure all HTML tags are properly closed.
   • Use standard HTML tags (not XHTML self-closing unless valid).
   <!-- ❌ Unclosed tags -->
   <p>This is a paragraph
   <ul><li>Item 1</ul>
   
   <!-- ✅ Properly closed -->
   <p>This is a paragraph</p>
   <ul><li>Item 1</li></ul>
   
2. Use the Preview feature
   • Preview shows how template renders with sample data.
   • Check preview across different channel types.
3. Send test notifications
   • Test to your actual Slack/email/Teams channels.
   • Verify formatting in each platform.
4. Check special characters
   • Characters like <, >, & need escaping in HTML.
   • Use <, >, & instead.
   <!-- ❌ This will break HTML -->
   <p>{{entity.description}} contains < and > characters</p>
   
   <!-- ✅ Use proper escaping -->
   <p>{{{entity.description}}} (use triple braces for HTML content)</p>
   

​

Template Selected But Not Showing

• Notifications are sent but template isn’t being used.
• Using default formatting instead of custom template.

• Template not selected in subscription.
• Subscription is inactive.
• Event type doesn’t match what subscription is listening for.

1. Verify template is selected
   • Go to Settings > Notifications > Subscriptions.
   • Edit the subscription.
   • Confirm the Notification Template dropdown has your template selected and is not blank.
2. Check subscription is active
   • Enable/activate the subscription.
   • Verify it’s not disabled.
3. Verify event types match
   • Subscription must be listening to entity updates that match your template.
   • Example: Template for tables won’t be used for dashboard updates.

​

Missing Data in Notifications

​

Template Shows Empty Values

• Owner: appears with no value.
• Sections are blank even though field should exist.
• Links or data don’t appear.

• Data doesn’t exist for this entity instance.
• Property name is different than expected.
• Data is nested differently.

1. Use conditionals to handle missing data
   {{#if entity.owner}}
     <p>Owner: {{entity.owner}}</p>
   {{else}}
     <p><em>No owner assigned</em></p>
   {{/if}}
   
2. Check property availability
   {{#if entity.description}}
     {{entity.description}}
   {{/if}}
   
3. Verify nested properties exist
   {{#if entity.testCaseResult}}
     {{#if entity.testCaseResult.result}}
       Result: {{entity.testCaseResult.result}}
     {{/if}}
   {{/if}}
   

​

Change Data Not Displaying Correctly

• Updated fields showing as empty.
• Can’t see what changed in the notification.

• Not using groupEventChanges helper.
• Trying to access raw change description.

<!-- ❌ Don't access changeDescription directly -->
{{event.changeDescription}}

<!-- ✅ Use groupEventChanges helper -->
{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#if changes.updates}}
    <h3>Updated:</h3>
    {{#each changes.updates}}
      {{name}}: {{oldValue}} → {{newValue}}
    {{/each}}
  {{/if}}
{{/with}}

​

Link and URL Issues

​

Links Don’t Work or Point to Wrong Place

• Clicking link in notification shows 404 error.
• Link goes to wrong entity.

• Incorrect entity type in URL.
• baseUrl is not configured.
• Entity IDs have changed.

1. Use buildEntityUrl helper
   <!-- ✅ Best practice: Use helper -->
   <a href="{{buildEntityUrl event.entityType entity}}">
     View {{entity.displayName}}
   </a>
   
2. Verify baseUrl is set
   • The system should automatically set baseUrl.
   • Check if your Collate URL is configured correctly.
3. Test links
   • Send test notifications.
   • Click links and verify they work.

​

Helper Issues

​

Helper Not Found or Returns Wrong Result

• “Helper not found” error.
• Helper name is red/underlined in editor.
• Results are unexpected.

1. Misspelled helper name
   <!-- ❌ Typo in helper name -->
   {{len entity.tags}}
   
   <!-- ✅ Correct -->
   {{length entity.tags}}
   
2. Wrong number of arguments
   <!-- ❌ limit needs 2 arguments -->
   {{limit entity.tags}}
   
   <!-- ✅ Correct: array and max count -->
   {{limit entity.tags 5}}
   
3. Arguments in wrong order
   <!-- ❌ Wrong order -->
   {{split "." entity.fullyQualifiedName}}
   
   <!-- ✅ Correct: string first, then delimiter -->
   {{split entity.fullyQualifiedName "."}}
   

• Check Custom Helpers Reference
• Verify exact helper name and argument order.
• Use Preview to test.

​

Best Debugging Practices

​

1. Use Preview Frequently

• See how template renders with sample data.
• Catch formatting issues early.
• Test across different channels.

​

2. Send Test Notifications

• Send to real email/Slack/Teams.
• Verify how it actually appears to users.
• Test with your actual notification setup.

​

3. Start Simple

• Start with basic template.
• Add features one at a time.
• Test each addition.

<!-- Start here -->
{{entity.displayName}} was updated

<!-- Then add details -->
{{entity.displayName}} was updated
{{#with (groupEventChanges event.changeDescription) as |changes|}}
  Updated: {{#each changes.updates}}{{name}}{{/each}}
{{/with}}

<!-- Then add formatting and styling -->
<!-- ... etc -->

​

4. Ask for Help

• The template code.
• What error or unexpected behavior occurs.
• What data you expected to see.
• Screenshots of Preview/test results.