레코드 생성

선택적 사용자 정의 필드, 태그 및 할당을 사용하여 Blue에 새 레코드(할 일)를 생성합니다.

레코드 생성

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)
수식 및 시간 기간 사용자 정의 필드 계산
분석 및 차트 업데이트