Liquid 言語

このガイドでは、Zendesk で Liquid テンプレート言語を使用するためのリファレンスを提供します。Liquid はトリガー、オートメーション、テーマでの動的なコンテンツを可能にします。本ページでは一般的な変数、関数、実用的な例について説明します。

Liquid 言語とは

Liquid は Shopify が作成し、Ruby で書かれたオープンソースのテンプレート言語 です。テーマ、ページ等で、より動的なコンテンツを実現するために使用されます。

Zendesk での Liquid の使い方

Zendesk では、Liquid を最も一般的にトリガー、オートメーション、エクステンションで利用しています。これによってより動的なメッセージ (コメント、URL 等) が可能になります。Liquid 言語は機能が豊富で頻繁に更新されるため、フル活用するための学習には時間がかかることがあります。

変数の埋め込み

テキスト/出力に値を挿入するには、変数/関数/値の名前を二重の波括弧で囲みます。

例として、チケット要求者の名前を出力するには、以下のスタイルに従います:

• 入力: Greetings {{ticket.requester.name}}
• 出力: Greetings John Doe

この方法で関数も使用できます。例として、自分のロールをメッセージに入れたいが大文字化されていることを保証したい場合、以下のスタイルに従います:

• 入力: My role is {{current_user.role | capitalize }}
• 出力: My role is Fullstack Engineer

コードブロック

コードブロック (ループ、代入、条件分岐などで一般的) を使用するには、{% で行を始めて %} で終えます。

例として、チケットコメントのループを開始するには {% for comment in ticket.comments %} のように記述します。

一般的な変数

他にも多数 使用可能ですが、これらは GitLab で最も一般的に使用されているものです。

チケットフィールド ID を特定する

これは多くの場合管理者レベルのアクセスが必要となるので、Customer Support Operations チームに支援を求めるのが最善です。

一般的な関数

一般的なタグ

条件文

ループ

例

ドキュメンテーション Issue 作成トリガー

これは、最新コメントの作成者・タイトル・説明を判断してドキュメンテーション 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 %}

行ごとの内訳:

1. チケットコメントに対する for ループを開始し、イテレーション数を 1 に制限する (最新のものだけを取得する意味)
2. 変数 author に値を代入する
   • 値はコメント作成者の GitLab ユーザー ID (カスタムユーザーフィールド) になります
3. 変数 lines に値を代入する
   • これは comment を url_encode 関数に渡して、文字列を URL セーフ形式にエンコードします
   • そして url_encode された文字列を split 関数に渡し、区切り文字 %0A で分割した配列にします
4. lines 変数に格納された配列に対する for ループを開始する
5. 変数 first_five に値を代入する
   • これは line を slice 関数に渡し、最初の 5 文字を返します
6. first_five の値が Title であることを条件とする if ブロックを宣言する
7. 変数 title に値を代入する
   • これは line を url_decode 関数に渡し、url_encode が以前行ったことを取り消します
   • これを split 関数に渡し、区切り文字 : で分割した配列にします
   • これを last 関数に渡し、配列の最後の項目を返します
8. if ブロックを終了する
9. 2 番目の for ループを終了する
10. 変数 description に値を代入する
    • これは comment を split 関数に渡し、区切り文字 ‘Description:’ で分割した配列にします
    • これを last 関数に渡し、配列の最後の項目を返します
    • これを join 関数に渡し、区切り文字 \n で項目を結合します
11. 最初の for ループを終了する

営業時間外メッセージを表示すべきか判断する

これは、チケットが現在営業時間内かどうかに基づいてテキストブロックを表示するか判断するために使用しました。

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

行ごとの内訳:

1. チケットが営業時間外であることを条件とする if ブロックを宣言する
2. テキストのブロックを表示する
   • これは liquid 変数 {{ticket.id}} 経由でチケットの ID を挿入します
3. if ブロックを終了する

SSAT Issue 作成トリガー

これは、顧客が私たちに残す SSAT 評価に基づいて Issue を作成するトリガーの一部として使用しました。これは、チケットが使用しているフォームを判断し、チケットフォームに対応する GitLab Issue タグを含む変数を設定するために使用されます。

{% assign form = ticket.ticket_form %}

{% if form == 'GitLab.com User Accounts and Login Issues' %}
  {% assign form = 'form::GitLab.com' %}
{% elsif form == 'Support for GitLab.com' %}
  {% 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 %}

行ごとの内訳:

1. 変数 form に値を代入する
   • 値はチケットのフォームになります
2. スペース用の空白行 (必須ではなく、見栄えを良くするだけ)
3. form の値が GitLab.com User Accounts and Login Issues であることを条件とする if ブロックを宣言する
4. 変数 form に値を代入する
5. form の値が Support for GitLab.com であることを条件とする elsif ブロックを宣言する
6. 変数 form に値を代入する
7. form の値が Support for a self-managed GitLab instance であることを条件とする elsif ブロックを宣言する
8. 変数 form に値を代入する
9. form の値が Licensing and Renewals Problems であることを条件とする elsif ブロックを宣言する
10. 変数 form に値を代入する
11. form の値が Contact the Security team であることを条件とする elsif ブロックを宣言する
12. 変数 form に値を代入する
13. form の値が Other Request であることを条件とする elsif ブロックを宣言する
14. 変数 form に値を代入する
15. else ブロックを宣言する
16. 変数 form に値を代入する
17. if ブロックを終了する

有用なリンク

• Liquid GitHub repo
• Liquid documentation
• Zendesk placeholders reference

一般的な問題とトラブルシューティング

これは生きたセクションで、必要に応じて項目が追加されていきます。

ページのソースコードを見る - ページの編集 - please contribute.