オートメーション

このガイドでは、GitLab における Zendesk オートメーションの作成、編集、管理方法について説明します。管理者は管理者タスクセクションを確認してください。

エージェントが手動で適用するマクロや、チケットイベントで即座に発火するトリガーとは異なり、オートメーションは時間ベースのスケジュールで実行されます。

オートメーションを理解する

オートメーションとは

Zendesk によると:

オートメーションはトリガーに似ています。両者ともチケットのプロパティを変更し、オプションで顧客やエージェントにメール通知を送信する条件とアクションを定義するためです。両者の違いは、オートメーションはチケットが作成または更新された直後ではなく、チケットのプロパティが設定または更新された後に時間イベントが発生したときに実行されることです。

簡単に言えば、オートメーションは即座に実行されないトリガーです。イベントベースではなく時間ベースです。

Zendesk でオートメーションが実行されるタイミング

公式には、Zendesk のオートメーションは 1 時間に 1 回実行されます。正確なタイミングは確定的ではありませんが、私たちの Zendesk の使用経験では、これはインスタンスのタイムゾーンで毎時の開始時（5 分程度以内）に発生することが示されています。

オートメーションは条件ロジックを使用する

オートメーションは条件ロジックを使用します:

• all: 配列内のすべての条件が true である必要があります（AND ロジック）
• any: 少なくとも 1 つの条件が true である必要があります（OR ロジック）
• 1 つのセットだけ、または両方のセットを使用できます（ただし少なくとも 1 つのセットを使用する必要があります）

私たちのオートメーションの管理方法

Zendesk は UI を通じてオートメーションを完全に管理する方法を提供していますが、私たちはよりバージョン管理されたメソドロジーを採用しています。これにより、定められたレビュープロセス、必要に応じたロールバック実行などが可能になります。

そのため、私たちは同期リポジトリと管理コンテンツリポジトリを利用しています。

同期リポジトリの仕組み

同期リポジトリのワークフローは以下のプロセスに従います:

graph TD;
  A-->C;
  B-->C;
  C-->D;
  A(Scheduled time for pipeline to run)
  B(Scheduled pipeline triggered manually)
  C(bin/sync runs)
  D(Changes synced to Zendesk)

人間が読みやすい置換

現在、同期リポジトリは、人間が読みやすい項目から「Zendesk」相当の項目への、さまざまな項目の置換を実行できます。これには次のものが含まれます:

例として、Preferred Region for Support フィールドの値を AMER に変更するオートメーションを作成したい場合は、置換を使用して次のようにします:

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

別の例として、チケットのフォームが SaaS フォームではないかをチェックする条件が必要な場合は、次のようにします:

- field: 'ticket_form_id'
  operator: 'is_not'
  value: 'Form: SaaS'

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

同期リポジトリで MR が作成されると、（bin/compare スクリプト経由で）比較アクションが実行されます。これは次のことを行います:

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

Zendesk への同期

同期リポジトリは、プロジェクトのスケジュールパイプラインが実行される（正しいタイミングまたは手動で実行される）と同期タスクを実行します。

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

• Creates
• Updates

孤立した管理コンテンツファイルのレポート

2 月、5 月、8 月、11 月の 1 日に、スケジュールパイプラインにより、同期リポジトリは Support リーダーシップチームがすべての孤立した管理コンテンツファイルをレビューするための Issue を作成します。

これは同期リポジトリの bin/find_orphaned_files スクリプト経由で行われ、次のことを行います:

1. 管理コンテンツリポジトリのクローンを実行します
2. 管理コンテンツリポジトリの active および inactive フォルダ内のすべてのファイルをレビューして、state（つまり active または inactive）、path、title を判定します
3. 同期リポジトリ自体の active および inactive フォルダ内のすべてのファイルをレビューして、次のことを判定します:
   • ファイルが管理コンテンツファイルを使用しているか
   • 管理コンテンツファイルがあるか
4. 同期リポジトリのファイルなしで管理コンテンツファイルが見つかった場合、それを Customer Support リーダーシップにレポートする Issue を作成します

管理者以外の立場でオートメーションを作成する

オートメーションの作成については、Feature Request issue を作成してください（Customer Support Operations チームによる手動対応が必要なため）。

管理者以外の立場でオートメーションを編集する

オートメーションで使用するコメントの文言を変更する

オートメーション内のコメントの文言を編集するには、管理コンテンツリポジトリの対応するファイルを変更します。master ブランチにマージされると、次のデプロイメントサイクルで取り込まれて Zendesk にデプロイされます。

オートメーションで使用するペイロードを変更する

オートメーション内のペイロード（管理 Webhook を使用しているもの）を編集するには、管理コンテンツリポジトリの対応するファイルを変更します。master ブランチにマージされると、次のデプロイメントサイクルで取り込まれて Zendesk にデプロイされます。

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

オートメーションの他の項目を変更するには、Feature Request issue を作成してください（Customer Support Operations チームによる手動対応が必要なため）。

管理者以外の立場でオートメーションを非アクティブ化する

オートメーションの非アクティブ化を依頼するには、Feature Request issue を作成してください（Customer Support Operations チームによる手動対応が必要なため）。

管理者タスク

オートメーションの使用情報を確認する

オートメーションの使用情報を確認するには:

1. Zendesk インスタンスの管理パネルに移動します
2. Objects and rules > Business rules > Automations に移動します
3. 「Add automation」ボタンの左側のアイコンをクリックします（AZ が入った円のように見えます）
4. 表示したい使用列をクリックします

オートメーションを作成する

オートメーションを作成するには、同期リポジトリで MR を作成する必要があります。具体的な変更内容は、依頼自体に依存します。利用可能な開始テンプレートは以下のとおりです:

---
title: 'Your::Title::Here'
previous_title: 'Your::Title::Here'
description: 'Your description here'
active: true
position: 1 # Integer representing automation position
actions:
- field: 'the_action_to_perform'
  value: 'the_value_to_use'
conditions:
  all:
  - field: 'the_action_to_perform'
    operator: 'the_operator_to_use'
    value: 'the_value_to_use'
  any:
  - field: 'the_action_to_perform'
    operator: 'the_operator_to_use'
    value: 'the_value_to_use'
contains_managed_content: false
contains_managed_email: false
contains_managed_webhook: false

ピアによるレビューと承認の後、MR をマージできます。次のデプロイメントが行われる際に、Zendesk に同期されます。

オートメーションを編集する

オートメーションを編集するには、同期リポジトリで MR を作成する必要があります。具体的な変更内容は、依頼自体に依存します。

ピアによるレビューと承認の後、MR をマージできます。次のデプロイメントが行われる際に、Zendesk に同期されます。

オートメーションのタイトルを変更する

オートメーションのタイトルを変更する必要がある場合は、現在の値を previous_title 属性にコピーしてから title 属性を変更します。これにより、同期処理が対象のオートメーションを引き続き特定して更新できます。

オートメーションを非アクティブ化する

オートメーションを非アクティブ化するには、同期リポジトリで MR を作成する必要があります。この MR では、対応するオートメーションの YAML ファイルに対して次の操作を行うべきです:

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

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

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

   • Zendesk Global の場合:

     - field: 'current_tags'
       value: 'missing_brand'
     

   • Zendesk US Government の場合:

     - field: 'current_tags'
       value: 'missing_brand'
     

4. conditions の値を次のように変更します:

   • Zendesk Global の場合:

       all:
       - field: 'brand_id'
         operator: 'is_not'
         value: 'GitLab Support'
       - field: 'brand_id'
         operator: 'is_not'
         value: 'GitLab - Internal'
       - field: 'current_tags'
         operator: 'not_includes'
         value: 'missing_brand'
       - field: 'status'
         operator: 'is_not'
         value: 'closed'
       any: []
     

   • Zendesk US Government の場合:

       all:
       - field: 'brand_id'
         operator: 'is_not'
         value: 'GitLab'
       - field: 'brand_id'
         operator: 'is_not'
         value: 'GitLab - Internal'
       - field: 'current_tags'
         operator: 'not_includes'
         value: 'missing_brand'
       - field: 'status'
         operator: 'is_not'
         value: 'closed'
       any: []
     

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

6. contains_managed_webhook 属性の値を false に変更します

ピアによるレビューと承認の後、MR をマージできます。次のデプロイメントが行われる際に、Zendesk に同期されます。

オートメーションを削除する

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

オートメーションを削除するには:

1. Zendesk インスタンスの管理ダッシュボードに移動します
   • Zendesk Global (production)
   • Zendesk Global (sandbox)
   • Zendesk US Government (production)
   • Zendesk US Government (sandbox)
2. Objects and rules > Business rules > Automations に移動します
   • Zendesk Global
   • Zendesk Global (sandbox)
   • Zendesk US Government
   • Zendesk US Government (sandbox)
3. 削除したいオートメーションを見つけ、（Inactive タブで）名前をクリックします
4. ページの下部までスクロールします
5. Submit ボタンの隣のドロップダウンをクリックします
6. Delete をクリックします
7. Submit をクリックして変更を送信します

例外デプロイメントを実行する

オートメーションの例外デプロイメントを実行するには、対象のオートメーション同期プロジェクトに移動し、スケジュールパイプラインのページに移動して、同期項目の再生ボタンをクリックします。これにより、オートメーションの同期ジョブがトリガーされます。

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

マージ後にオートメーションの変更が反映されない

オートメーションは Standard デプロイメントタイプに従うため、通常のデプロイメントサイクル（または例外デプロイメントが行われたとき）にのみデプロイされます。

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