Using the Liquid Language

1. You are here:
2. Handbook
3. Support Team Handbook
4. Support Operations Team
5. Support Operations Training
6. Using the Liquid Language

On this page

• What this covers
• What is the liquid language
• How we use liquid in Zendesk
• Variable interpolation
• Code blocks
• Common variables
• Common functions
• Common tags
• Conditionals
• Loops
• Examples
  • Create documentation issue trigger
  • New ticket confirmation email trigger
  • SSAT Issue Creation trigger
• Useful links

What this covers

This training material will cover the following topics:

• a broad overview of what the liquid language is.
• how we use liquid in Zendesk.
• common liquid variables.
• common liquid functions.
• some real-life examples.

What is the liquid language

Liquid is an open-source template language created by Shopify and written in ruby. It is used to allow for more dynamic content on themes, pages, etc.

How we use liquid in Zendesk

In Zendesk, we utilize liquid most commonly in triggers, automations, and extensions. We utilize this to allow for more dynamic messaging (comments, URLs, etc.). It can take time to learn how to fully utilize the liquid language, especially as there is a lot to it and it gets added to frequently.

Variable interpolation

To insert a value into a text/output, you would use double curly bracks around the name of the variable/function/value.

As an example, to output a ticket requester's name, you might do something like Greetings {{ticket.requester.name}}.

You can also use functions in this manner. As an example, if you wanted to put your role into a message, but ensure it was capitalized, you might do something like My role is {{current_user.role | capitalize }}.

Code blocks

To use code blocks (common for loops, assignment, conditionals, etc.), you would start the line with {% and end it with %}

As an example, if you wanted to start a loop on ticket comments, you might do something like {% for comment in ticket.comments %}.

Common variables

There are many more that can be used, these are by far just the most common used at GitLab.

Common functions

Common tags

Conditionals

Loops

Examples

Create documentation issue trigger

We use this in a trigger to determine the author, title, and description of the most recent comment to create a documentation issue.

{% for comment in ticket.comments limit:1 offset:0 %}
  {% assign author = comment.author.custom_fields.gitlab_user_id %}
  {% assign lines = comment | url_encode | split: "%0A" %}
  {% for line in lines %}
    {% assign first_five = line | slice: 0,5 %}
    {% if first_five == 'Title' %}
      {% assign title = line | url_decode | split: ': ' | last %}
    {% endif %}
  {% endfor %}
  {% assign description = comment | split: 'Description:' | last | join: '\n' %}
{% endfor %}

Line by line breakdown:

1. Start a for loop on the ticket comments, setting a limit of 1 iteration (meaning only grab the most recent one)
2. Assign a value to the variable author
   • The value should be the comment's author GitLab user ID (a custom user field)
3. Assign a value to the variable lines
   • This passes the comment into the function url_encode, to encode the string into a URL safe format
   • This passed the url_encoded string into the split function, which turns it into an array split by the separate %0A
4. Start a for loop on the array stored in the lines variable
5. Assign a value to the variable first_five
   • This passes line into the slice function, return the first 5 characters
6. Declare an if block, with the condition being the value of first_five is Title
7. Assign a value to the variable title
   • This passes the line into the function url_decode, to undo what url_encode previously did
   • This is passed into the split function, which turns it into an array split by the separator :
   • This is passed into the last function, to return the last item in the array
8. Ends the if block
9. Ends for second for loop
10. Assign a value to the variable description
    • This passes the comment into the split function, which turns it into an array split by the separator 'Description:'
    • This is passed into the last function, to return the last item in the array
    • This is passed into the join function, to join the items using the separator \n
11. Ends for the first for loop

New ticket confirmation email trigger

We use this to determine is a block of text should display based on if the ticket is currently within business hours or not.

{% if ticket.in_business_hours == 'false' %}
  <li>You indicated in this ticket, #{{ticket.id}}, a "Preferred Region for Support." The current time is outside of that region's standard business hours. You can rest assured that this ticket will be addressed by the next available engineer in the selected region. It is important that you understand when you may expect a reply regarding this case. Please see the linked handbook section for more information regarding the <a href='https://about.gitlab.com/support/#effect-on-support-hours-if-a-preferred-region-for-support-is-chosen' target='_blank'>effect of using Preferred Region</a>.<br />During the course of this ticket if you require assistance outside of the selected region's standard business hours please feel free to reply asking one of our support engineers to set this ticket's preferred region to "All regions".</li>
{% endif %}

Line by line breakdown:

1. Declare an if block, with the condition being if the ticket is not within business hours
2. Display a block of text
   • This inserts the ticket's ID using a liquid variable via {{ticket.id}}
3. Ends the if block

SSAT Issue Creation trigger

We use this as part of the triggers that create issues based on SSAT ratings customers leave us. This is used to determine the form the ticket is using and set a variable to be used containing the GitLab issue tag that corresponds to the ticket form.

{% assign form = ticket.ticket_form %}

{% if form == 'Gitlab.com (SaaS) User Accounts and Login Issues' %}
  {% assign form = 'form::GitLab.com' %}
{% elsif form == 'Support for GitLab.com (SaaS)' %}
  {% assign form = 'form::GitLab.com' %}
{% elsif form == 'Support for a self-managed GitLab instance' %}
  {% assign form = 'form::Self-managed' %}
{% elsif form == 'Licensing and Renewals Problems' %}
  {% assign form = 'form::Upgrades & Renewals' %}
{% elsif form == 'Contact the Security team' %}
  {% assign form = 'form::Security' %}
{% elsif form == 'Other Request' %}
  {% assign form = 'form::Other' %}
{% else %}
  {% assign form = 'form::GitLab Community Edition' %}
{% endif %}

Line by line breakdown:

1. Assign a value to the variable form
   • The value should be the ticket's form
2. A blank line for spacing (not required, just makes it look nicer)
3. Declare an if block, with the condition being if the value of form is Gitlab.com (SaaS) User Accounts and Login Issues
4. Assign a value to the variable form
5. Declare an elsif block, with the condition being if the value of form is Support for GitLab.com (SaaS)
6. Assign a value to the variable form
7. Declare an elsif block, with the condition being if the value of form is Support for a self-managed GitLab instance
8. Assign a value to the variable form
9. Declare an elsif block, with the condition being if the value of form is Licensing and Renewals Problems
10. Assign a value to the variable form
11. Declare an elsif block, with the condition being if the value of form is Contact the Security team
12. Assign a value to the variable form
13. Declare an elsif block, with the condition being if the value of form is Other Request
14. Assign a value to the variable form
15. Declare an else block
16. Assign a value to the variable form
17. Ends the if block

Useful links

• Liquid GitHub repo
• Liquid documentation
• Zendesk placeholders reference