マクロ

このガイドでは、GitLab で Zendesk マクロを作成、編集、管理する方法について説明します。単純なマクロを作成したいサポートエージェントは、管理者以外としてマクロを作成するを参照してください。管理者は、管理者のタスクセクションを確認してください。

マクロを理解する

マクロとは

Zendeskによると:

マクロとは、エージェントがチケットを作成または更新する際に手動で適用できる、あらかじめ用意された応答またはアクションです。マクロには、チケットのプロパティを更新できるアクションが含まれます。

トリガーや自動化とは異なり、マクロには条件ではなくアクションのみが含まれます。マクロを適用すべきかどうかを判断するためにチケットを自動評価するものがないため、条件は使用しません。エージェントがチケットを評価し、必要に応じて手動でマクロを適用します。

マクロの分類

Zendesk のマクロには分類がありますが、UI では明確に示されません。代わりに、分類はマクロ自体の名前に基づいて決まります。基本的に、単語の各グループがマクロのドロップダウンセレクター内の一種の「フォルダー」になります。Zendesk が現在使用している区切り文字はコロン 2 つ（::）です。

単純なマクロと高度なマクロ

単純なマクロとは、次の項目のみを変更するマクロです。

• チケットの割り当て（または割り当て解除）
• チケットへのタグの追加
• チケットへのパブリックまたはプライベートコメントの追加
• チケットのステータスの変更

マクロが上記以外の操作を行う場合、現時点では「高度な」マクロと見なされます。

Zendesk でマクロを使用する

マクロをチケットに適用する方法は 2 つあります。

• スラッシュコマンド経由
• マクロ選択ドロップダウン経由

詳細については、Zendesk のドキュメントを参照してください。

マクロの管理方法

Zendesk では UI を通じたマクロ管理を完全に行えますが、私たちはよりバージョン管理された方法を採用しています。これにより、定められたレビュー手順、必要に応じたロールバックの実行機能などを得られます。

そのため、Zendesk 内部フォーム、同期リポジトリ、管理対象コンテンツリポジトリを利用します。

同期リポジトリの仕組み

同期リポジトリのワークフローは、次のプロセスに従います。

graph TD;
  A-->|Webhook fires| E;
  B-->E;
  C-->D;
  D-->|MR merged| E;
  E-->F;
  G-->H;
  H-->|Trigger runs| I
  I-->|If using managed content| A;
  I-->|Sleeps 5 min if managed content file was created| B;
  A(Commit to master in managed content repo)
  B(Commit to master in sync repo)
  C(MR created or updated on sync repo)
  D(bin/compare runs)
  E(bin/sync runs)
  F(Changes synced to Zendesk)
  G(Zendesk internal form submission)
  H(Ticket created)
  I(Ticket processor runs)

人が読みやすい形式への置換

現在、同期リポジトリでは、さまざまな項目を人が読みやすい項目から「Zendesk」相当の項目へ置換できます。対象は次のとおりです。

たとえば、フィールド Preferred Region for Support の値を AMER に変更するマクロを作成する場合、次のようにして置換を使用します。

- field: 'Field: Preferred Region for Support'
  value: 'AMER'

同期リポジトリで MR を作成する場合

同期リポジトリで MR が作成されると、bin/compare スクリプトを介して比較アクションが実行され、次の処理を行います。

1. 管理対象コンテンツリポジトリのクローンを実行します。
2. Zendesk インスタンスからすべてのブランド、チケットフィールド、チケットフォーム、グループ、スケジュール、満足理由、マクロを取得します。
3. 同期リポジトリ内のすべての YAML ファイルを確認して、マクロオブジェクトを生成します。
   • また、同期リポジトリファイルに次の問題がないことを確認します。
     • タイトルが欠落している。
     • active 属性が false のファイルが active フォルダーにある。
     • active 属性が true のファイルが inactive フォルダーにある。
     • title 属性が重複して使用されている。
     • contains_managed_content 属性が true のファイルに一致する管理対象コンテンツファイルがある。
4. YAML ファイルからのすべてのマクロオブジェクトを、対応する Zendesk 項目と比較します（title および previous_title 属性の値を確認して判定します）。
   • 存在しない場合は、後で使用するために作成オブジェクトを変数に保存します。
   • 存在するが属性値が異なる場合は、後で使用するために更新オブジェクトを変数に保存します。
5. 比較レポートを出力します。

Zendesk への同期

同期リポジトリでは、次の 2 つのイベントのいずれかが発生した場合に同期タスクを実行します。

• 管理対象コンテンツリポジトリがプロジェクト Webhookを介してシグナルを送信する場合（管理対象コンテンツリポジトリの master ブランチでコミットが発生した場合に送信するよう設定されています）
• 同期リポジトリの master ブランチでコミットが発生した場合

いずれかのアクションが発生すると、同期は比較アクションを実行し、生成されたオブジェクトを使用して、必要な Zendesk エンドポイントに対するループにより必要な作成および更新を実行します。

• 作成
• 更新

孤立した管理対象コンテンツファイルの報告

2 月、5 月、8 月、11 月の 1 日に、スケジュール済みパイプラインにより、同期リポジトリがサポートリーダーシップチーム向けにすべての孤立した管理対象コンテンツファイルを確認する Issue を作成します。

これは、同期リポジトリ内の bin/find_orphaned_files スクリプトにより行われ、次の処理を実行します。

1. 管理対象コンテンツリポジトリのクローンを実行します。
2. 管理対象コンテンツリポジトリの active および inactive フォルダー内のすべてのファイルを確認し、state（active または inactive）、path、title を判断します。
3. 同期リポジトリ自体の active および inactive フォルダー内のすべてのファイルを確認し、次の事項を判断します。
   • ファイルが管理対象コンテンツファイルを使用しているか。
   • 管理対象コンテンツファイルがあるか。
4. 同期リポジトリファイルがない管理対象コンテンツファイルを見つけた場合、Customer Support リーダーシップに報告する Issue を作成します。

管理者以外としてマクロを作成する

単純なマクロ

単純なマクロを作成するには、インスタンス用の Zendesk 内部フォームを使用します。

• Zendesk Global
• Zendesk US Government

フォームに入力してリクエストを送信すると、チケットプロセッサーが提供された情報を使用して、単純なマクロを作成します。

マクロに管理対象コンテンツファイルが必要で（つまり、マクロがコメントを作成し）、まだ存在しない場合は、管理対象コンテンツリポジトリ内にファイルが作成されます。

高度なマクロ

高度なマクロを作成する場合は、まず SIG チームのメンバーに相談し、このテンプレートを使用して Customer Support Systems チームに Issue を送信してもらってください（Customer Support Systems チームによる手動対応が必要になるためです）。

管理者以外としてマクロを編集する

マクロ内で使用されるコメント文言を変更する

マクロ内のコメント文言を編集するには、管理対象コンテンツリポジトリ内の対応するファイルを変更します。master ブランチにマージされると、同期リポジトリを介して Zendesk インスタンスに同期されます。

タイトル、制限、コメント以外の文言アクションなどを変更する

マクロ内のその他の項目を変更する場合は、まず SIG チームのメンバーに相談し、このテンプレートを使用して Customer Support Systems チームに Issue を送信してもらってください（Customer Support Systems チームによる手動対応が必要になるためです）。

管理者以外としてマクロを無効化する

マクロの無効化を依頼するには、まず SIG チームのメンバーに相談し、このテンプレートを使用して Customer Support Systems チームに Issue を送信してもらってください（Customer Support Systems チームによる手動対応が必要になるためです）。

管理者のタスク

マクロ使用状況の情報を確認する

マクロの使用状況を確認するには、次の手順を実行します。

1. Zendesk インスタンスの管理パネルに移動します。
2. Workspaces > Agent tools > Macros に移動します。
3. マクロリストの右端にあるアイコン（縦長の長方形が 3 つ並んだように見えます）をクリックします。
4. 表示する使用状況の列をクリックします。

マクロを作成する

単純なマクロを作成する場合は、単純なマクロを参照してください。

高度なマクロを作成する場合は、同期リポジトリで MR を作成する必要があります。実際に行う変更は、リクエスト自体によって異なります。使用できる開始テンプレートは次のとおりです。

---
title: 'Your::Title::Here'
previous_title: 'Your::Title::Here'
description: 'Your description here'
active: true
actions:
- field: 'the_action_to_perform'
  value: 'the_value_to_use'
restriction: null
contains_managed_content: false

ピアが MR をレビューして承認した後、MR をマージできます（変更は Zendesk インスタンスに同期されます）。

マクロを編集する

マクロのコメント文言のみを変更する場合は、マクロ内で使用されるコメント文言を変更するを参照してください。

それ以外の場合は、同期リポジトリで MR を作成する必要があります。実際に行う変更は、リクエスト自体によって異なります。

ピアが MR をレビューして承認した後、MR をマージできます（変更は Zendesk インスタンスに同期されます）。

マクロのタイトルを変更する

マクロのタイトルを変更する必要がある場合は、現在の値を previous_title 属性にコピーしてから、title 属性を変更します。これにより、同期は更新対象のマクロを引き続き見つけられます。

マクロを無効化する

マクロを無効化するには、同期リポジトリで MR を作成する必要があります。この MR では、対応するマクロの YAML ファイルに対して次の操作を行います。

1. ファイルを active から inactive のパスに移動します。

2. active 属性の値を false に変更します。

3. actions の値を次のように変更します。

   • Zendesk Global の場合:

     - field: 'brand_id'
       value: 'GitLab Support'
     

   • Zendesk US Government の場合:

     - field: 'brand_id'
       value: 'GitLab'
     

4. contains_managed_content 属性の値を false に変更します。

ピアが MR をレビューして承認した後、MR をマージできます（変更は Zendesk インスタンスに同期されます）。

マクロを削除する

同期リポジトリでは削除が実行されないため、Zendesk 自体でこの操作を行う必要があります。

マクロを削除するには、次の手順を実行します。

1. Zendesk インスタンスの管理ダッシュボードに移動します。
   • Zendesk Global (production)
   • Zendesk Global (sandbox)
   • Zendesk US Government (production)
   • Zendesk US Government (sandbox)
2. Workspaces > Agent tools > Macros に移動します。
   • Zendesk Global
   • Zendesk Global (sandbox)
   • Zendesk US Government
   • Zendesk US Government (sandbox)
3. 削除するマクロを見つけて名前をクリックします。
4. Actions ボタンをクリックします。
5. Delete をクリックします。
6. 確認ボックスで Delete macro をクリックします。

よくある問題とトラブルシューティング

マージ後にマクロの変更が表示されない

同期が完全に実行されるまで通常 5 〜 10 分かかります。その後、ブラウザで Zendesk をハードリフレッシュしてから、変更を確認してください。

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