Template Variables

FireHydrant uses the Liquid templating language. A templating language allows you to set variables/placeholders that are replaced with actual data at execution time.

You can use template variables to reference many types of incident data, such as name and description, milestones, roles, user assignments, and more.

In FireHydrant, you can use template variables to dynamically interpolate FireHydrant incident data into multiple places, including:

As an example, in a Runbook step, you can use an incident's name and description with {{ incident.name }} and {{ incident.description }} in the fields. When the Runbook step executes on a real incident, those placeholders will be filled with the actual name and description of the incident.

To minimize impact to your instance through repeated test incidents, we recommend testing these template variables using the Liquid playground. Additionally, you can check out our liquid template examples in this GitHub repo.

Runbook steps now also feature an output preview, where you can select previous incidents as example data to preview how your templating would have looked:

Liquid/JSON preview on a Runbook step

Liquid/JSON preview on a Runbook step

Available fields and definitions

This list includes the properties in the FireHydrant API that are most often used as template variables. To see all available FireHydrant incident properties refer to the IncidentEntity model (for incident data) and PostmortemReportEntity model (for retrospective data).

All left-most fields are accessible under the main incident object with {{ incident.VAR }}, where VAR is the name of the field.

Every field is a String key, an object with String keys, or an array of objects with String keys unless denoted otherwise. Arrays are marked.

Visit the sections in the table of contents to the right to see each section's available variables.

General Incident Fields

  • id: The ID number of the incident. You can use this as a template variable inside of a Runbook with  the format app.firehydrant.io/incidents/{{incident.id}}.

  • name: The name of the incident.

  • created_at: The UTC time when the incident was created.

  • started_at: The UTC time of the started milestone.

  • summary: Summary of the incident.

  • customer_impact_summary: Summary of the impact of the incident on customers.

  • description: A more detailed description of the incident.

  • current_milestone: The current milestone state of the incident.

  • number: The number of the incident. This number increments with each additional incident that is created.

  • severity: The current severity of the incident.

  • severity_impact: Do not use; deprecated.

  • severity_condition: Do not use; deprecated.

  • tag_list: The array of tags attached to the incident.

  • private_id: The ID of the private incident status page.

  • organization_id: The customer organization ID.

  • last_update*: The most recent incident update added via add note. This field has been marked for deprecation. Please use last_note.body instead.

  • last_note (object):

    • body: The most recent incident update added via add note or update.

    • created_at: UTC for the most recent incident update added via add note or update.

  • created_by (object):

    • id: ID of the user who declared the incident.

    • name: Name of the user who declared the incident.

    • source: Where the user declared the incident (for example, firehydrant_user or slack ). 

    • email: Email address for the user who declared the incident.

  • report_id: This only shows for resolved incidents; the ID identifies the incident retro.

  • incident_url: The url for the incident overview page in FireHydrant.

📘

Note:

incident.last_update will eventually be deprecated in favor of incident.last_note.body.  We ask that all customers use the new incident.last_note fields.

Milestone Fields

  • milestones (array of objects):

    • id: The ID of the milestone occurrence for this incident.

    • created_at: The time when the milestone was created.

    • updated_at: The time when the milestone was updated.

    • type: The milestone type. Available values are listed here.

    • occurred_at: When the milestone became active.

    • duration: The time between when this milestone occurred and when the previous milestone occurred.

    • active: If the incident is in any milestone state earlier than resolved, this value will be true; otherwise, it will be false.

Role and User Assignment Fields

  • role_assignments (array of objects):

    • id: A database ID for assigning the role to the incident.

    • status: The status of the role assignment (active or inactive).

    • created_at: When the role was assigned.

    • updated_at: When the role was updated.

    • incident_role (object):

      • id: The ID for the specific incident role.

      • name: The name of the incident role.

      • summary: A summary of the incident role.

      • description: A longer description of the incident role.

      • updated at: When the incident role was updated.

      • discarded at: When the incident role was discarded.

    • user (object):

      • id: The ID for the user in this specific role.

      • name: The user's name.

      • email: Email address of the user.

      • created_at: When the user was created.

      • updated_at: When the user was updated.

      • slack_linked: Indicates whether this user's Slack account is linked to FireHydrant.

  • team_assignments (array of objects):

    • id: The ID for the team assignment (not the team's ID).
    • status: The status of the team. Either active or inactive.
    • created_at: When the assignment occurred
    • updated_at: When the assignment was updated
    • team (object): The team that was assigned. For the full list of available parameters within team, see the TeamEntity

Custom Fields

  • custom_fields (object of objects)
    • display_name: The display name of the field
    • value_type : The field type (string, single_select, multi_select)
    • value : The current value of the field (string or array of strings)
    • field_id: A UUID for the field, use slug instead
    • slug: The unique, humanized identifier for the field

Custom field attributes (e.g., display_name, value) can be accessed directly by slug name or can be iterated using Liquid's for loop, which will return each custom field as an object.

## Accessing the value of custom field by slug
{{ incident.custom_fields.slug.value }}

## Iterating over all custom fields to display the name and the value
{% for field in incident.custom_fields %}
  {{ field.name }}
  {{ field.value }}
{% endfor %}

Organization Fields

  • organization (object):

    • id: The ID of the customer organization

    • name: The name of the customer organization

Service-Related Fields

  • services (array of objects):

    • id: The ID of the impacted service

    • name: The name of the impacted service

  • functionalities (array of objects):

    • id: The ID of the impacted functionality

    • name: The name of the impacted functionality

  • environments (array of objects):

    • id: The ID of the impacted environment

    • name: The name of the impacted environment

  • impacts(array of objects):

    • id: Unique ID tracking this particular impact/instance

    • type: "service", "functionality", or "environment"

    • impact(object):

      • id: The ID of the impacted service, functionality, or environment

      • name: The name of the impacted service, functionality, or environment

    • condition(object):

      • id: The ID of the condition (to see the list of conditions and their IDs, visit the API docs)

      • name: The name of the condition

Integrations-Related Fields

  • channel_name: The name of the Slack channel for the incident.

  • channel_reference: The Slack-formatted encoded link for the Slack channel. You can use this reference number in a Slack message to create a link to the incident channel.

  • channel_id: The Slack ID for the channel (not formatted for creating links).

  • channel_status: Indicates whether the Slack channel is operational.

  • private_status_page_url: The url of the private status page for the incident.

  • incident_tickets** (array of objects):

    • id: The incident ticket ID.

    • summary: Summary of information in the ticket.

    • Description: Description of the incident as provided in the ticket.

    • state: State of the ticket: open , in_progress , done , etc.

    • type: Ticket type: Incident , follow_up , or task.

    • assignees: The incident ticket ID.

    • created_by (object)

      • id: ID of the user who created the ticket.

      • name: Name of the user who created the ticket.

      • source: Ticketing source: Slack , PagerDuty , FireHydrant , etc.

      • email: Email address for the user who created the ticket.

    • attachments (array of objects):

      • display_text: The text displayed that links to the ticket.

      • href_url: The URL for the ticket.

      • icon_url: The URL for the icon of the ticketing provider.

      • type: The type of ticket.

📘

Note:

At this time, only the incident ticket is included in this array of objects, not Tasks or Follow-Ups.

Alternatively, you may use ticket, which is the only ticket of type: Incident, and also supports any of the attributes above. This ticket object has the following attributes:

  • ticket (object): Singular object containing the incident ticket

    • link: The reference to a corresponding external integration ticket or issue

      • display_text: The text displayed that links to the ticket.

      • href_url: The URL for the ticket.

      • icon_url: The URL for the icon of the ticketing provider.

      • type: The type of ticket; in this case, it's always "link"

  • conference_bridges (array of objects):

    • id: UUID of the conference object as stored on FireHydrant (not the Zoom/Google Meet ID)

    • attachments (array of objects):

      • type: Attachment type: image, alert, etc.

      • display_text: The text displayed describes the conference bridge.

      • href_url: The URL for the conference bridge (for example, https://us02web.zoom.us/j/1234567890)

      • icon_url: The URL for the icon of the conference bridge provider.

  • incident_channels (array of objects):

    • id: Slack ID for the channel
    • name: The name of the channel
    • source: The originating source of the channel (e.g. slack)
    • url: The URL for the channel
    • icon_url: URL for the source/channel's icon

Retrospective Fields

The retro data object is only available after an incident has moved to the 'retrospective started' milestone. This object can be directly referenced like an incident, for example,{{ retro.name }}.

  • retro (object):

    • name: The name of the report

    • published_at: When the retro was completed

    • questions (array of objects): An array of custom questions set from the Retrospective Configuration tab

      • title: The title of the question

      • body: The answer to the question

      • updated_at: When the question was last updated

    • contributing_factors (array of objects): An array of the Five Whys section in contributing factors

      • summary: The content of the contributing factor

      • position: The position in the list of Five Whys

    • incident_active_duration: The duration that the incident was in an active state. Active is defined as the Started through Mitigated milestone

    • starred_events (array of objects): An array of the starred events from the incident

      • occurred_at: When the event occurred

      • created_by: Who created the event

      • summary: The content of the contributing factor

      • body: The content of the event

Cookbook

The following section contains examples of using Liquid templating to interpolate incident data.

Slack Channel URL

  • Summary: Get the URL to the Slack channel and display the link using markdown.
  • Usage: Any external comms step, like Notify with Custom Message or Email, etc., where you want to link to the incident Slack channel.
[Incident Channel]({{ incident.incident_channels[0].url }})

Confluence Retro Additions

  • Summary: Display Tags, Labels, and Jira tickets in Confluence export
  • Usage: Add to the Export to Confluence runbook step
### Tags

| Tags      |
|-----------|
{%- for tag in incident.tag_list %}
| {{ tag }} |
{%- endfor %}

### Labels

| Key | Value |
|-----|-------|
{%- for label in incident.labels %}
| {{ label[0] }} | {{ label[1] }} |
{%- endfor %}

### Jira

| Ticket Name | Link |
|-------------|------|
{%- for ticket in incident.incident_tickets[0].attachments %}
| {{ ticket.display_text }} | {{ ticket.href_url }} |
{%- endfor %}

Print Duration of Incident

  • Summary: Return the current or total duration of the incident. Calculates from Resolved milestone or now if the incident is still open.
  • Usage: Custom message to channel or email runbook steps
{% assign started = incident.milestones | where: "type", "started" | first %}
{% assign started_at = started.occurred_at | date: "%s" %}

{% assign resolved = incident.milestones | where: "type", "resolved" | first %}
{% if resolved %}
  {% assign resolved_at_or_now = resolved.occurred_at | date: "%s" %}
{% else %}
  {% assign resolved_at_or_now = "now" | date: "%s" %}
{% endif %}

{% assign SECONDS_PER_MINUTE = 60 %}
{% assign SECONDS_PER_HOUR = SECONDS_PER_MINUTE | times: 60 %}
{% assign SECONDS_PER_DAY = SECONDS_PER_HOUR | times: 24 %}

{% assign remainder = resolved_at_or_now | minus: started_at | modulo: SECONDS_PER_DAY %}
{% assign days = resolved_at_or_now | minus: started_at | divided_by: SECONDS_PER_DAY | floor %}

{% assign hours = remainder | divided_by: SECONDS_PER_HOUR | floor %}
{% assign remainder = remainder | modulo: SECONDS_PER_HOUR %}

{% assign minutes = remainder | divided_by: SECONDS_PER_MINUTE | floor %}
{% assign seconds = remainder | modulo: SECONDS_PER_MINUTE %}

This incident has been active for {{ days }}d {{ hours }}h {{ minutes }}m {{ seconds }}s

Print all responders' names, emails, and roles

  • Summary: Return all responders' information. This information is available in other places today like the Command Center or any Notify messages in Slack, but could be useful in e.g. an email.
  • Usage: The Send an email notification runbook step, in Jira/Confluence step descriptions, etc.
{% for role in incident.role_assignments -%}
  **{{ role.incident_role.name }}**: {{ role.user.name }} \<{{ role.user.email }}\>
{% endfor %}

Print overview message of current information and next update ETA

  • Summary: Using Liquid's built in time mechanics, we do time conversions using simple math and then display with formatting.
  • Usage: Anywhere, but likely Email or Custom Message steps
{% assign started = incident.milestones | where: "type", "started" | first %}

**CURRENT STATUS**: {{ incident.current_milestone }}
**SEVERITY**: {{ incident.severity }}
**DESCRIPTION**: {{ incident.description }}
**START TIME**: {{ started.occurred_at | date: "%s" | minus: 28800 | date: "%Y-%m-%d %H:%M" }}

**LAST UPDATE**:
  - At: {{ incident.last_note.created_at | date: "$s" | minus: 28800 | date: "%Y-%m-%d %H:%M" }}
  - Note: {{ incident.last_note.body }}

**NEXT UPDATE**: {{ incident.last_note.created_at | date: "%s" | minus: 27000 | date: "%Y-%m-%d %H:%M" }}

In the example above, updates are posted in 30-minute intervals and in PST. Dates are stored in UTC, so we first convert them to a date object that Liquid can work with using date, and then we subtract seconds from the time to convert from UTC to PST with minus before formatting the output to print.

Other Resources