チケットフォーム

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

チケットフォームを理解する

チケットフォームとは

チケットフォームは、ユーザーがチケットを作成するために使用するフォームです（Web UI を使用する場合）。フォーム上の回答は、チケットのメタデータに変換されます。

これらは次の 2 種類のいずれかです:

• パブリック: エージェントとエンドユーザーの両方が閲覧できます
• 内部: エージェントのみが閲覧できます

チケットフォームの管理方法

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)

チケットフォームは条件ロジックを使用します

チケットフォームでは、条件を使用してフィールドを動的に表示または非表示にできます:

• end_user_conditions: エンドユーザーが選択内容に基づいて表示するフィールドを制御します
• agent_conditions: エージェントに表示するフィールドと必須になるタイミングを制御します

親フィールドが特定の値を持つ場合、子フィールドが表示されます（必要に応じて必須にできます）。例: 「プロダクトカテゴリが「GitLab.com」の場合、「GitLab.com ユーザー ID」フィールドを表示する」

チケットフォームで条件を使用する必要はありません。条件がない場合、フォームデータで詳述されたすべてのフィールドが表示されます。

これは、チケットフォームで_条件付き要件_を設定する方法でもあります。

UI では、エンドユーザー条件の形式は次のとおりです:

TICKET_FIELD の値が VALUE の場合、LIST_OF_TICKET_FIELDS を表示する

LIST_OF_TICKET_FIELDS の各項目では、何らかの方法でチケットフィールド項目を必須にするオプションがあります。

2 種類のバックエンドは、要件定義の主な違いを除けば類似しています。

エンドユーザー条件

エンドユーザー条件のバックエンド値の形式は次のとおりです:

- parent_field_id: 'Field title'
  value: 'tag_or_value_used_by_field'
  child_fields:
  - id: 'Field title 2'
    is_required: true

内訳は次のとおりです:

• parent_field_id は、値を確認する field です
• value は、確認する field の値です
• child_fields は表示するフィールドのリストで、各項目には次が含まれます:
  • id は表示するフィールドです
  • is_required は、新しく表示されたフィールドが送信時に必須かどうかを詳述します

エージェント条件

エージェント条件のバックエンド値の形式は、次の 2 つの形式のいずれかです:

- parent_field_id: 'Field title'
  value: 'tag_or_value_used_by_field'
  child_fields:
  - id: 'Field title 2'
    is_required: true
    required_on_statuses:
      type: 'ALL_STATUSES'

- parent_field_id: 'Field title'
  value: 'tag_or_value_used_by_field'
  child_fields:
  - id: 'Field title 2'
    is_required: true
    required_on_statuses:
      type: 'SOME_STATUSES'
      statuses:
      - 'pending'
      - 'hold'
      - 'solved'

内訳は次のとおりです:

• parent_field_id は、値を確認する field です
• value は、確認する field の値です
• child_fields は表示するフィールドのリストで、各項目には次が含まれます:
  • id は表示するフィールドです
  • is_required は、新しく表示されたフィールドが何らかの方法で必須かどうかを詳述します

違いを決めるのは、新しいフィールドが_必須_かどうか、および必須となる方法です:

• すべてのステータスで必須にする場合:

  - id: 'Field title 2'
    is_required: true
    required_on_statuses:
      type: 'ALL_STATUSES'
  

• どのステータスでも必須にしない場合（つまり必須にしない場合）:

  - id: 'Field title 2'
    is_required: true
    required_on_statuses:
      type: 'NO_STATUSES'
  

• 特定のステータスでのみ必須にする場合:

  - id: 'Field title 2'
    is_required: true
    required_on_statuses:
      type: 'SOME_STATUSES'
      statuses:
      - 'list'
      - 'of'
      - 'statuses'
  

管理者以外としてチケットフォームを作成する

チケットフォームを作成するには、機能リクエスト Issueを作成してください（Customer Support Systems チームによる手動介入が必要になるためです）。

管理者以外としてチケットフォームを編集する

チケットフォームを変更するには、機能リクエスト Issueを作成してください（Customer Support Systems チームによる手動介入が必要になるためです）。

管理者以外としてチケットフォームを非アクティブ化する

チケットフォームの非アクティブ化をリクエストするには、機能リクエスト Issueを作成してください（Customer Support Systems チームによる手動介入が必要になるためです）。

人が読める形式の置換

現在、同期リポジトリでは、人が読める形式（つまりチケットフィールドの title 属性）からチケットフィールドとブランドの置換を実行できます。

そのため、Preferred Region for Support という値を検出すると、そのタイトルを持つチケットフィールドを特定し、それが含まれていたチケットフォーム属性に必要なテキストに変換することを認識します。ブランドについても同様です（ただし、name 属性を使用します）。

現在のフォーム

Zendesk Global の現在のフォーム

Zendesk US Government の現在のフォーム

管理者タスク

チケットフォームを表示する

Zendesk でチケットフォームを表示するには:

1. Zendesk インスタンスの管理パネルに移動します
   • Zendesk Global（本番環境）
   • Zendesk Global（サンドボックス）
   • Zendesk US Government（本番環境）
   • Zendesk US Government（サンドボックス）
2. Objects and rules > Tickets > forms に移動します
   • Zendesk Global
   • Zendesk Global（サンドボックス）
   • Zendesk US Government
   • Zendesk US Government（サンドボックス）

注記: 非アクティブなチケットフォームを表示する場合は、Filter ボタンをクリックしてアクティブなフィルターを変更する必要がある場合があります

チケットフォームを作成する

チケットフォームを作成するには、同期リポジトリで MR を作成する必要があります。正確な変更内容はリクエスト自体によって異なります。使用できる開始テンプレートは次のとおりです:

---
name: 'Your form name here'
previous_name: 'Your form name here'
display_name: 'Customer visible name'
raw_display_name: 'Customer visible name' # Dynamic content placeholder can be used here
active: true
position: 1 # Integer representing ticket form position
ticket_field_ids:
- 'Field title'
- 'Field title 2'
- 'Field title 3'
- 'Field title 4'
default: false # Is the form the default form for this account
in_all_brands: false # Is the form available for use in all brands on this account (should always be false)
restricted_brand_ids:
- 'Brand name'
end_user_conditions:
- parent_field_id: 'Field title'
  value: 'tag_or_value_used_by_field'
  child_fields:
  - id: 'Field title 2'
    is_required: true
  - id: 'Field title 3'
    is_required: false
agent_conditions:
- parent_field_id: 'Field title'
  value: 'tag_or_value_used_by_field'
  child_fields:
  - id: 'Field title 2'
    is_required: true
    required_on_statuses:
      type: 'ALL_STATUSES'
  - id: 'Field title 3'
    is_required: true
    required_on_statuses:
      type: 'NO_STATUSES'
  - id: 'Field title 4'
    is_required: true
    required_on_statuses:
      type: 'SOME_STATUSES'
      statuses:
      - 'pending'
      - 'hold'
      - 'solved'

チケットフォームはゼロから作成すると非常に複雑になる可能性があるため、迷った場合は同期リポジトリ内の既存のものを有効な例として使用してください。

ピアが MR をレビューして承認した後、MR をマージできます。次回のデプロイ時に Zendesk に同期されます。

チケットフォームを編集する

チケットフォームを編集するには、同期リポジトリで MR を作成する必要があります。正確な変更内容はリクエスト自体によって異なります。

ピアが MR をレビューして承認した後、MR をマージできます。次回のデプロイ時に Zendesk に同期されます。

チケットフォームの名前を変更する

チケットフォームのタイトルを変更する必要がある場合は、現在の値を previous_name 属性にコピーしてから、name 属性を変更します。これにより、同期は更新対象のチケットフォームを引き続き特定できます。

チケットフォームを非アクティブ化する

チケットフォームを非アクティブ化するには、同期リポジトリで MR を作成する必要があります。この MR では、対応するチケットフォームの YAML ファイルに対して次を実行してください:

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

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

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

   - 'Status'
   - 'Group'
   - 'Assignee'
   - 'Ticket status'
   - 'Subject'
   - 'Description'
   

4. end_user_conditions の値を空の配列（つまり []）に変更します

5. agent_conditions の値を空の配列（つまり []）に変更します

ピアが MR をレビューして承認した後、MR をマージできます。次回のデプロイ時に Zendesk に同期されます。

チケットフォームを削除する

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

チケットフォームを削除するには:

1. Zendesk インスタンスの管理パネルに移動します
   • Zendesk Global（本番環境）
   • Zendesk Global（サンドボックス）
   • Zendesk US Government（本番環境）
   • Zendesk US Government（サンドボックス）
2. Objects and rules > Tickets > forms に移動します
   • Zendesk Global
   • Zendesk Global（サンドボックス）
   • Zendesk US Government
   • Zendesk US Government（サンドボックス）
3. フィルターを Inactive に変更します
4. 削除するチケットフォームを特定し、その名前をクリックします
5. 3 つの縦並びのドットをクリックします（チケットフォームデータの右上）
6. Delete をクリックします
7. Delete をクリックして変更を送信します

例外デプロイを実行する

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

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

マージ後にチケットフォームの変更が表示されない

チケットフォームは Standard デプロイタイプに従うため、通常のデプロイサイクル中（または例外デプロイが実行された場合）にのみデプロイされます

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