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:

• Runbook steps
• Jira field mappings
• Command Extensions
• ...and more!

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:

Incident Fields and Variables

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. Visit the sections in the table of contents to the right to see each section's available variables.

General Incident Fields

Milestone Fields

Role and User Assignment Fields

Custom Fields

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 %}

Audiences

Service Catalog Fields

• services (array of objects):

  • id: The ID of the impacted service

  • name: The name of the impacted service

  • labels (object): Object containing key-value pairs of all labels

    • {KEY}: Whatever labels you've configured for a service. For example, if you have a label called region then you would access this via *.labels.region or *.labels['region']

• functionalities (array of objects):

  • id: The ID of the impacted functionality

  • name: The name of the impacted functionality

  • labels (object): Object containing key-value pairs of all labels

    • {KEY}: Whatever labels you've configured for a functionality. For example, if you have a label called region then you would access this via *.labels.region or *.labels['region']

• 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): List of channels attached to the incident

  • 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

• follow_ups (array of objects): List of follow-ups created on the incident

  • id: FireHydrant UUID for this follow-up
  • summary: Title/summary of the follow-up
  • description: The description of the follow-up
  • state: The current state of the follow-up. Possible values are open, in_progress, cancelled, and done
  • type: Will always be follow_up
  • assignees (array of objects):
    • id: FireHydrant UUID for the user
    • name: User's name
    • source: firehydrant_user, bot_user, or patchy. For Follow-Ups, will basically always be firehydrant_user
    • email: User's email address
  • created_by (object):
    • id: FireHydrant UUID for the user
    • name: User's name
    • source: firehydrant_user, bot_user, or patchy. For Follow-Ups, will basically always be firehydrant_user
    • email: User's email address
  • created_at: ISO 8601 datetime representing when the ticket was created
  • updated_at: ISO 8601 datetime representing when the ticket was last updated
  • tag_list (array of strings): List of ticketing tags (not to be confused with incident tags)
  • incident_id: FireHydrant UUID of the incident this follow-up was created for
  • link: Linked external resource, usually a project ticket for follow-ups
    • id: FireHydrant UUID for the attachment
    • type: Always link
    • display_text: The ticket's code (e.g., "ABC-123")
    • href_url: The URL to the external ticket
    • icon_url: Link to the icon FireHydrant uses for the integration
    • editable: Always false for follow-ups
    • deletable: Always false for follow-ups

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.

Limitations

Currently, the use of where: in Liquid templating can only be used to filter on a top-level parameter. For example, given the following JSON object:

[
  {
    "id": "3ebfb4da-e2a4-4ae7-9e44-e34df78589e0",
    "status": "active",
    "created_at": "2025-01-08T00:47:43.587Z",
    "updated_at": "2025-01-08T00:47:43.587Z",
    "incident_role": {
      "id": "a75e35b4-b228-4f1a-b455-6de2aec46a1b",
      "name": "Incident Commander",
      "summary": "The Incident Commander is responsible for overall management, communication, and task delegation during incidents.",
      "description": "The Incident Commander holds the high-level state of an incident and is responsible for overall management, communicating with stakeholders, triaging and delegating work, and most importantly, motivating and driving the team through the situation.",
      "created_at": "2022-02-09T17:18:05.678Z",
      "updated_at": "2023-05-09T16:48:44.554Z",
      "discarded_at": null
    },
    "user": {
      "id": "a561dd61-5ff6-480b-aaaf-87bba4ed6d74",
      "name": "John Doe",
      "email": "[email protected]",
      "slack_user_id": "U032E92MN6S",
      "slack_linked?": true,
      "created_at": "2022-02-09T17:18:06.577Z",
      "updated_at": "2023-10-13T21:25:28.643Z",
      "signals_enabled_notification_types": [
        "sms",
        "apns"
      ]
    }
  }
]

...you can filter on top-level parameters like status = "active", but you would not be able to do checks against any nested parameters (e.g., incident_role.name = "Incident Commander"). This is due to a limitation in the Liquid templating Ruby gem we use underneath the hood.

The recommended workaround is to use more primitive filters like for and if statements. For example:

// DOES NOT WORK
{% assign incidentManagers = incident.role_assignments | where: "incident_role.name", "Incident Mnaager" %}

// DOES WORK
{% for role in incident.role_assignments %}
  {% if role_assignment.incident_role.name == "Incident Manager" %}
    // etc...
  {% endif %}
{% endfor %}

Other Resources

• FireHydrant Liquid playground
• LiquidJS Documentation