チケットフォーム

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

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

チケットフォームとは

チケットフォームは、ユーザーがチケットを作成する際に使用するフォームです（Web UI 使用時）。これらはフォーム上の応答をチケットメタデータに変換します。

これらは以下の 2 つのタイプのいずれかに分類されます。

• Public - エージェントとエンドユーザーの両方が閲覧可能
• Internal - エージェントのみが閲覧可能

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

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: エージェントが見るフィールドと、それらが必須となるタイミングを制御

親フィールドが特定の値を持つ場合、子フィールドが表示されます（オプションで必須にもできます）。例: 「Product Category が ‘GitLab.com’ の場合、‘GitLab.com User 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'
  

管理者ではない者がチケットフォームを作成する

チケットフォームの作成については、Feature Request の Issue を作成してください（カスタマーサポートオペレーションチームによる手動対応が必要となるため）。

管理者ではない者がチケットフォームを編集する

チケットフォームの変更については、Feature Request の Issue を作成してください（カスタマーサポートオペレーションチームによる手動対応が必要となるため）。

管理者ではない者がチケットフォームを非アクティブ化する

チケットフォームの非アクティブ化を依頼するには、Feature Request の Issue を作成してください（カスタマーサポートオペレーションチームによる手動対応が必要となるため）。

人間が読める形式の置換

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

そのため、Preferred Region for Support という値を見つけた場合、そのタイトルのチケットフィールドを特定し、その配下にあったチケットフォーム属性の必要なテキストに変換することを認識します。ブランドについても同じです（ただし name 属性を使用）。

現在のフォーム

Zendesk Global の現在のフォーム

Zendesk US Government の現在のフォーム

管理者タスク

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

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

1. Zendesk インスタンスの管理パネルに移動
   • Zendesk Global (production)
   • Zendesk Global (sandbox)
   • Zendesk US Government (production)
   • Zendesk US Government (sandbox)
2. Objects and rules > Tickets > forms に移動
   • Zendesk Global
   • Zendesk Global (sandbox)
   • Zendesk US Government
   • Zendesk US Government (sandbox)

注意: 非アクティブのチケットフォームを表示したい場合は、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 をマージできます。次のデプロイ時に、Zendesk に同期されます。

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

チケットフォームを編集するには、同期リポジトリで 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 をマージできます。次のデプロイ時に、Zendesk に同期されます。

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

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

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

1. Zendesk インスタンスの管理パネルに移動
   • Zendesk Global (production)
   • Zendesk Global (sandbox)
   • Zendesk US Government (production)
   • Zendesk US Government (sandbox)
2. Objects and rules > Tickets > forms に移動
   • Zendesk Global
   • Zendesk Global (sandbox)
   • Zendesk US Government
   • Zendesk US Government (sandbox)
3. フィルターを Inactive に変更
4. 削除するチケットフォームを見つけてその名前をクリック
5. 縦の 3 つの点（チケットフォームデータの右上）をクリック
6. Delete をクリック
7. Delete をクリックして変更を送信

例外デプロイを実施する

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

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

マージ後にチケットフォームの変更が見えない

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

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