レコードの作成

Blueで新しいレコード（todo）を作成し、オプションのカスタムフィールド、タグ、および割り当てを追加します。

レコードの作成

createTodoミューテーションを使用すると、カスタムフィールド、タグ、割り当てなどの包括的な設定オプションを使用して、Blueに新しいレコードを作成できます。レコードは特定のリストに作成することも、デフォルトのリストに自動的に配置することもできます。

基本的な例

タイトルだけのシンプルなレコードを作成します：

mutation CreateRecord {
  createTodo(
    input: {
      title: "New Task"
    }
  ) {
    id
    title
    position
  }
}

高度な例

利用可能なすべてのオプションを使用してレコードを作成します：

mutation CreateRecordAdvanced {
  createTodo(
    input: {
      todoListId: "clm4n8qwx000008l0g4oxdqn7"
      title: "Product Launch Planning"
      placement: TOP
      description: "<p>Complete product launch preparation including marketing materials and documentation.</p>"
      startedAt: "2025-01-15T09:00:00Z"
      duedAt: "2025-02-01T17:00:00Z"
      notify: true
      assigneeIds: ["user_123", "user_456"]
      tags: [
        { id: "tag_existing_123" }
        { title: "Priority", color: "#ff4b4b" }
        { title: "Marketing" }
      ]
      customFields: [
        {
          customFieldId: "cf_budget_123"
          value: "50000 USD"
        }
        {
          customFieldId: "cf_status_456"
          value: "In Progress"
        }
      ]
      checklists: [
        {
          title: "Pre-launch Checklist"
          position: 1
        }
      ]
    }
  ) {
    id
    uid
    title
    position
    startedAt
    duedAt
    todoList {
      id
      title
    }
    users {
      id
      fullName
    }
    tags {
      id
      title
      color
    }
  }
}

入力パラメータ

CreateTodoInput

パラメータ	型	必須	説明
`todoListId`	String	いいえ	レコードを追加するtodoリストのID。指定しない場合は、プロジェクト内の最初のtodoリストを使用します
`title`	String!	✅ はい	レコードのタイトル（必須）
`position`	Float	いいえ	リスト内のカスタム位置。指定しない場合は配置パラメータを使用します
`placement`	CreateTodoInputPlacement	いいえ	位置が指定されていない場合にレコードを配置する場所（TOPまたはBOTTOM）
`startedAt`	DateTime	いいえ	レコードの開始日時
`duedAt`	DateTime	いいえ	レコードの期限日時
`notify`	Boolean	いいえ	このレコード作成の通知を送信するかどうか
`description`	String	いいえ	HTML説明コンテンツ（サニタイズされます）
`assigneeIds`	[String!]	いいえ	このレコードに割り当てるユーザーIDの配列
`checklists`	[CreateChecklistWithoutTodoInput!]	いいえ	レコードと共に作成するチェックリストの配列
`customFields`	[CreateTodoInputCustomField]	いいえ	カスタムフィールド値の配列
`tags`	[CreateTodoTagInput!]	いいえ	レコードに添付するタグの配列

CreateTodoInputPlacementの値

値	説明
`TOP`	リストの先頭に配置（最高位置）
`BOTTOM`	リストの末尾に配置（最低位置）

CreateTodoTagInput

パラメータ	型	必須	説明
`id`	String	いいえ*	接続する既存のタグのID
`title`	String	いいえ*	タグのタイトル（存在しない場合は新規作成）
`color`	String	いいえ	新しいタグの16進色（デフォルトは#4a9fff）

*注：id（既存のタグ用）またはtitle（タイトルで作成/検索するため）のいずれかを提供する必要があります。

CreateTodoInputCustomField

パラメータ	型	必須	説明
`customFieldId`	String	いいえ	カスタムフィールドのID
`value`	String	いいえ	カスタムフィールドの値（以下のフォーマットガイドを参照）

CreateChecklistWithoutTodoInput

パラメータ	型	必須	説明
`title`	String!	✅ はい	チェックリストのタイトル
`position`	Float	いいえ	レコード内のチェックリストの位置

カスタムフィールド値のフォーマット

カスタムフィールド値を設定する際は、フィールドタイプに基づいてこれらのフォーマットを使用します：

フィールドタイプ	フォーマット	例
`CHECKBOX`	"true", "1", or "checked" for checked	`"true"`
`COUNTRY`	Country name or ISO code	`"United States"` or `"US"`
`CURRENCY`	Amount with optional currency	`"50000 USD"`
`DATE`	YYYY-MM-DD or date range	`"2025-01-15"` or `"2025-01-15,2025-01-20"`
`NUMBER`	Numeric value	`"42"`
`PERCENT`	Numeric value (% optional)	`"75"` or `"75%"`
`RATING`	Numeric value within range	`"4"` (if max is 5)
`PHONE`	International phone format	`"+1234567890"`
`SELECT_SINGLE`	Custom field option ID	`"option_123"`
`SELECT_MULTI`	Comma-separated option IDs	`"option_1,option_2"`
`LOCATION`	Latitude,longitude	`"40.7128,-74.0060"`
`EMAIL`	Valid email address	`"user@example.com"`
`URL`	Valid URL	`"https://example.com"`
`TEXT`	Plain text value	`"Any text content"`

レスポンスフィールド

このミューテーションは、包括的なレコード詳細を持つTodoオブジェクトを返します：

フィールド	型	説明
`id`	String!	レコードの一意の識別子
`uid`	String!	代替の一意の識別子
`title`	String!	レコードのタイトル
`position`	Float!	リスト内の位置
`done`	Boolean!	完了状況
`startedAt`	DateTime	開始日時
`duedAt`	DateTime	期限日時
`todoList`	TodoList	関連するtodoリストの詳細
`users`	[User!]	割り当てられたユーザー
`tags`	[Tag!]	関連するタグ
`checklists`	[Checklist!]	関連するチェックリスト
`customFields`	[CustomFieldValue!]	カスタムフィールド値

必要な権限

ユーザーはレコードを作成するために適切なプロジェクトアクセスを持っている必要があります：

アクセスレベル	レコードを作成できる
`OWNER`	✅ はい
`ADMIN`	✅ はい
`MEMBER`	✅ はい
`CLIENT`	✅ はい
`COMMENT_ONLY`	❌ いいえ
`VIEW_ONLY`	❌ いいえ

このミューテーションは、ユーザーのプロジェクトアクセスレベルがOWNER、ADMIN、MEMBER、またはCLIENTである必要があります。VIEW_ONLYまたはCOMMENT_ONLYの役割を持つユーザーは、レコードを作成できません。

エラー応答

ProjectNotFoundError

{
  "errors": [{
    "message": "Project was not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

いつ: ユーザーにプロジェクトコンテキストが利用できない場合。

TodoListCreateTodoLimitError

{
  "errors": [{
    "message": "Todo list has reached the maximum number of todos.",
    "extensions": {
      "code": "TODO_LIST_CREATE_TODO_LIMIT_ERROR"
    }
  }]
}

いつ: todoリストにすでに100,000レコードが含まれている場合（最大制限）。

TodoListNotFoundError

{
  "errors": [{
    "message": "Todo list was not found.",
    "extensions": {
      "code": "TODO_LIST_NOT_FOUND"
    }
  }]
}

いつ: 指定されたtodoListIdが存在しないか、ユーザーにアクセス権がない場合。

CustomFieldValueParseError

{
  "errors": [{
    "message": "Invalid phone number format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

いつ: カスタムフィールド値が検証に失敗した場合（例：無効な電話番号、評価が範囲外）。

重要な注意事項

パフォーマンス

各todoリストには最大100,000レコードを含めることができます
レコードを作成すると、複数のバックグラウンドプロセス（Webhook、オートメーション、検索インデックス）がトリガーされます
バッチ操作は、1つずつレコードを作成するよりも効率的です

ビジネスロジック

位置処理: 指定されていない場合、デフォルトの位置は65535.0です。positionまたはplacementが指定されていない場合
日付ロジック:
- もしduedAtのみが提供された場合、startedAtはその日の始まりに設定されます
- もしstartedAtのみが提供された場合、duedAtは同じ値に設定されます
タグ作成: 指定されたタイトル/色が存在しない場合、新しいタグが自動的に作成されます
リスト選択: todoListIdが提供されていない場合、プロジェクト内の最初のtodoリストが使用されます

副作用

レコードを作成すると、以下がトリガーされます：

アクティビティログエントリの作成
Webhook通知
検索インデックスの更新
オートメーションルールの実行（設定されている場合）
メール/プッシュ通知（notify: trueが指定されている場合）
フォーミュラおよび時間のカスタムフィールド計算
分析およびチャートの更新