---

創建記錄

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	否	要添加記錄的待辦列表的 ID。如果未提供，則使用項目中的第一個待辦列表
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	否	新標籤的十六進制顏色（默認為 #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	相關的待辦列表詳細信息
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"
    }
  }]
}

何時：待辦列表已經包含 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"
    }
  }]
}

何時：自定義字段值未通過驗證（例如，無效的電話號碼、評分超出範圍）。

重要注意事項

性能

• 每個待辦列表最多可以包含 100,000 條記錄
• 創建記錄會觸發多個後台過程（網絡鉤子、自動化、搜索索引）
• 批量操作比逐個創建記錄更有效

業務邏輯

• 位置處理：當既未指定 position 也未指定 placement 時，默認位置為 65535.0
• 日期邏輯：
  • 如果僅提供 duedAt，則 startedAt 設置為那一天的開始
  • 如果僅提供 startedAt，則 duedAt 設置為相同的值
• 標籤創建：如果指定的標題/顏色不存在，則自動創建新標籤
• 列表選擇：如果未提供 todoListId，則使用項目中的第一個待辦列表

副作用

創建記錄會觸發：

• 活動日誌條目創建
• 網絡鉤子通知
• 搜索索引更新
• 自動化規則執行（如果配置）
• 電子郵件/推送通知（如果 notify: true）
• 公式和時間持續自定義字段計算
• 分析和圖表更新

相關端點

• 列出記錄：查詢待辦事項以檢索現有記錄
• 更新記錄：使用 updateTodo 突變來修改記錄
• 列出自定義字段：查詢以獲取可用的自定義字段 ID
• 列出標籤：查詢以獲取現有標籤 ID
• 列出待辦列表：查詢以獲取可用的待辦列表 ID