---

概要

カスタムフィールドを使用すると、Blueの標準レコード構造にビジネスニーズに特化した追加データフィールドを拡張できます。これにより、タイトル、説明、期限などの組み込みフィールドを超えて構造化データをキャプチャする強力な方法が提供されます。

カスタムフィールドはプロジェクトレベルで定義され、そのプロジェクト内のすべてのレコード（todo）で使用できます。各フィールドには、その検証ルール、入力形式、および表示動作を決定する特定のタイプがあります。

利用可能な操作

コアフィールド管理

操作	説明	リンク
List Custom Fields	カスタムフィールドのクエリとフィルタリング	View Details →
Create Custom Field	プロジェクトに新しいカスタムフィールドを追加	View Details →
Delete Custom Field	適切なクリーンアップを伴うカスタムフィールドの削除	View Details →

フィールド値

操作	説明	リンク
Set Field Values	レコード上のカスタムフィールド値の設定と更新	View Details →

カスタムフィールドタイプ

テキストフィールド

タイプ	説明	使用例	リンク
TEXT_SINGLE	単一行テキスト入力	Names, titles, short descriptions	View Details →
TEXT_MULTI	複数行テキストエリア	長い説明、ノート、コメント	View Details →

選択フィールド

タイプ	説明	使用例	リンク
SELECT_SINGLE	単一選択ドロップダウン	Status, priority, category	View Details →
SELECT_MULTI	複数選択ドロップダウン	Tags, skills, categories	View Details →
CHECKBOX	ブールチェックボックスフィールド	Flags, approvals, confirmations	View Details →

数値フィールド

タイプ	説明	使用例	リンク
NUMBER	数値入力	Quantities, scores, measurements	View Details →
CURRENCY	通貨額	Budgets, costs, pricing	View Details →
PERCENT	パーセンテージ値	Completion rates, discounts	View Details →
RATING	カスタムスケールによる星評価	Performance ratings, satisfaction	View Details →
FORMULA	他のフィールドに基づく計算フィールド	Totals, computations, aggregations	View Details →

連絡先フィールド

タイプ	説明	使用例	リンク
EMAIL	検証付きのメールアドレス	連絡先情報、通知	View Details →
PHONE	国際フォーマットの電話番号	Contact details, emergency contacts	View Details →
URL	検証付きのWeb URL	Links, references, resources	View Details →

日付と時刻フィールド

タイプ	説明	使用例	リンク
DATE	日付ピッカー	Deadlines, milestones, events	View Details →
TIME_DURATION	時間追跡フィールド	Work hours, duration estimates	View Details →

位置と地理

タイプ	説明	使用例	リンク
LOCATION	地理的位置（緯度/経度）	Addresses, venues, service areas	View Details →
COUNTRY	国選択	Regional assignments, localization	View Details →

ファイルとメディア

タイプ	説明	使用例	リンク
FILE	ファイル添付	Documents, images, resources	View Details →

システムフィールド

タイプ	説明	使用例	リンク
UNIQUE_ID	自動生成された一意の識別子	Ticket numbers, order IDs	View Details →
REFERENCE	別のプロジェクトのレコードへのリンク	Cross-project relationships	View Details →
LOOKUP	参照されたレコードからデータを取得	Aggregate data from related records	View Details →

インタラクティブフィールド

タイプ	説明	使用例	リンク
BUTTON	アクション可能なボタンフィールド	Triggers, actions, workflows	View Details →
CURRENCY_CONVERSION	通貨変換フィールド	Multi-currency calculations	View Details →

主要概念

フィールド定義

• カスタムフィールドはプロジェクトレベルで定義されます
• 各フィールドには一意の名前とタイプがあります
• フィールドには検証ルールや制約を含めることができます
• 設定オプションはフィールドタイプによって異なります

フィールド値

• 値は個々のレコード（todo）に保存されます
• 各レコードは同じフィールドに異なる値を持つことができます
• オプションフィールドには空/nullの値が許可されます
• 値はフィールドタイプのルールに従って検証されます

権限モデル

カスタムフィールドはプロジェクトレベルの権限を尊重します：

役割	フィールド作成	フィールド編集*	値設定	値表示
OWNER	✅ はい	✅ はい	✅ はい	✅ はい
ADMIN	✅ はい	✅ はい	✅ はい	✅ はい
MEMBER	❌ いいえ	❌ いいえ	✅ はい	✅ はい
CLIENT	❌ いいえ	❌ いいえ	✅ 限定	✅ 限定

*フィールド編集はフィールド設定（名前、タイプ、オプション、検証ルール）の変更を指し、レコード上のフィールド値の設定ではありません。

カスタムロールの権限

• プロジェクトにはフィールド固有の権限を持つカスタムロールを設定できます
• フィールドはロールごとに編集可能/非編集可能としてマークできます
• カスタムロールは特定のフィールドへのアクセスを制限できます

一般的なパターン

基本的なカスタムフィールドの作成

mutation CreateCustomField {
  createCustomField(input: {
    name: "Priority Level"
    type: SELECT_SINGLE
    description: "Task priority level"
    customFieldOptions: [
      { title: "Low", color: "#28a745" }
      { title: "Medium", color: "#ffc107" }
      { title: "High", color: "#fd7e14" }
      { title: "Critical", color: "#dc3545" }
    ]
  }) {
    id
    name
    type
    customFieldOptions {
      id
      title
      color
    }
  }
}

レコード上のフィールド値の設定

mutation SetFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionId: "option_789"  # For SELECT_SINGLE
  })
}

カスタムフィールドを使用したレコードのクエリ

query GetTodosWithCustomFields {
  todos(projectId: "project_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      # Type-specific value fields
      text           # TEXT_SINGLE, TEXT_MULTI, EMAIL, etc.
      number         # NUMBER, CURRENCY, PERCENT, RATING
      selectedOption # SELECT_SINGLE
      selectedOptions # SELECT_MULTI
      checked        # CHECKBOX
      date           # DATE
    }
  }
}

カスタムフィールド値を使用したレコードの作成

mutation CreateTodoWithCustomFields {
  createTodo(input: {
    title: "New task"
    todoListId: "list_123"
    customFields: [
      { customFieldId: "priority_field", value: "high_priority_option" }
      { customFieldId: "budget_field", value: "5000" }
      { customFieldId: "notes_field", value: "Additional context here" }
    ]
  }) {
    id
    title
    customFields {
      customField { name }
      value
    }
  }
}

ベストプラクティス

フィールドデザイン

1. 説明的な名前を使用する - フィールドの目的を明確にする
2. 適切なタイプを選択する - データ要件にフィールドタイプを一致させる
3. 検証ルールを設定する - 最小/最大値、必須フィールドを使用する
4. 論理的に整理する - 関連するフィールドをグループ化する

パフォーマンスの考慮事項

1. フィールド数を制限する - フィールドが多すぎるとパフォーマンスに影響を与える可能性があります
2. ページネーションを使用する - 大規模データセットをクエリする際
3. キーとなるフィールドにインデックスを付ける - フィルタリング/ソートに使用されるフィールドに対して
4. 深いネストを避ける - フィールドの関係をシンプルに保つ

データ品質

1. 入力を検証する - 検証付きの適切なフィールドタイプを使用する
2. デフォルトを提供する - 適切なデフォルト値を設定する
3. 一貫したフォーマットを使用する - データ入力パターンを標準化する
4. 定期的なクリーンアップ - 未使用のフィールドやオプションを削除する

ユーザーエクスペリエンス

1. 明確な説明 - 有用なフィールド説明を提供する
2. 論理的な順序 - フィールドを自然なワークフローの順序で配置する
3. 視覚的階層 - 色やフォーマットを効果的に使用する
4. 漸進的開示 - 関連する場合にフィールドを表示する

エラーハンドリング

カスタムフィールドを操作する際の一般的なエラー：

エラーコード	説明	解決策
CUSTOM_FIELD_NOT_FOUND	フィールドが存在しない	Verify field ID and project access
VALIDATION_ERROR	値がフィールドタイプと一致しない	Check format and validation rules
UNAUTHORIZED	権限が不十分	Ensure proper role level
CUSTOM_FIELD_VALUE_PARSE_ERROR	無効な値フォーマット	Review field type requirements

関連リソース

• レコードAPI - カスタムフィールドを含むレコードの操作
• プロジェクトAPI - カスタムフィールドを含むプロジェクトの管理
• 自動化API - カスタムフィールドトリガーを使用したワークフローの自動化
• ユーザー管理API - カスタムフィールドの権限管理