회원가입
문의 로그인 회원가입
시스템 상태

유형별 구성으로 프로젝트의 데이터 구조를 확장하기 위해 새로운 사용자 정의 필드를 추가합니다.

사용자 정의 필드 생성

사용자 정의 필드는 기록에 구조화된 데이터 필드를 추가하여 Blue를 특정 비즈니스 요구에 맞게 조정할 수 있게 해줍니다. 이 엔드포인트는 각 필드 유형에 특정한 구성을 가진 새로운 사용자 정의 필드를 생성합니다.

기본 예제

mutation CreateTextField {
  createCustomField(input: {
    name: "Customer Name"
    type: TEXT_SINGLE
    description: "Primary customer contact name"
  }) {
    id
    uid
    name
    type
    position
  }
}

고급 예제

mutation CreateAdvancedField {
  createCustomField(input: {
    name: "Project Budget"
    type: CURRENCY
    description: "Total allocated budget for this project"
    currency: "USD"
    min: 0
    max: 1000000
  }) {
    id
    uid
    name
    type
    currency
    min
    max
    position
    createdAt
  }
}

입력 매개변수

CreateCustomFieldInput

매개변수 유형 필수 설명
name String! ✅ 예 사용자 정의 필드의 표시 이름
type CustomFieldType! ✅ 예 필드 유형 (아래 유형 참조)
description String 아니오 필드의 목적을 설명하는 선택적 설명
min Float 아니오 NUMBER, RATING, PERCENT 필드의 최소값
max Float 아니오 NUMBER, RATING, PERCENT 필드의 최대값
currency String 아니오 CURRENCY 필드의 ISO 통화 코드
prefix String 아니오 UNIQUE_ID 필드의 텍스트 접두사
isDueDate Boolean 아니오 DATE 필드가 마감일을 나타내는지 여부
formula JSON 아니오 FORMULA 필드의 공식 구성
referenceProjectId String 아니오 REFERENCE 필드의 대상 프로젝트 ID
referenceMultiple Boolean 아니오 REFERENCE 필드에서 여러 선택 허용
referenceFilter TodoFilterInput 아니오 REFERENCE 필드의 필터 옵션
lookupOption CustomFieldLookupOptionInput 아니오 LOOKUP 필드의 구성
timeDurationDisplay CustomFieldTimeDurationDisplayType 아니오 TIME_DURATION의 표시 형식
timeDurationTargetTime Float 아니오 TIME_DURATION의 초 단위 목표 시간
timeDurationStartInput CustomFieldTimeDurationInput 아니오 TIME_DURATION의 시작 트리거
timeDurationEndInput CustomFieldTimeDurationInput 아니오 TIME_DURATION의 종료 트리거
buttonType String 아니오 BUTTON 필드의 버튼 동작 유형
buttonConfirmText String 아니오 BUTTON 필드의 확인 프롬프트
useSequenceUniqueId Boolean 아니오 UNIQUE_ID에 대한 순차 번호 사용
sequenceDigits Int 아니오 시퀀스의 자릿수 (예: 5 → 00001)
sequenceStartingNumber Int 아니오 시퀀스의 시작 번호
currencyFieldId String 아니오 CURRENCY_CONVERSION의 참조 통화 필드
conversionDate String 아니오 CURRENCY_CONVERSION의 변환 날짜
conversionDateType String 아니오 CURRENCY_CONVERSION의 변환 날짜 유형
metadata JSON 아니오 사용자 정의 필드에 대한 추가 메타데이터

CustomFieldType 값

값 설명 필수 매개변수
TEXT_SINGLE 단일 행 텍스트 입력 없음
TEXT_MULTI 다중 행 텍스트 영역 없음
SELECT_SINGLE 단일 선택 드롭다운 Create options separately
SELECT_MULTI 다중 선택 드롭다운 Create options separately
CHECKBOX 불리언 체크박스 없음
RATING 별점 필드 Optional: max (default: 5)
PHONE 유효성 검사와 함께 전화번호 없음
NUMBER 숫자 입력 Optional: min, max
CURRENCY 통화 금액 Optional: currency, min, max
PERCENT 백분율 (0-100) Optional: min, max
EMAIL 유효성 검사와 함께 이메일 없음
URL 유효성 검사와 함께 웹 URL 없음
UNIQUE_ID 자동 생성된 식별자 Optional: prefix, useSequenceUniqueId
LOCATION 지리적 좌표 없음
FILE 파일 첨부 없음
DATE 날짜 선택기 Optional: isDueDate
COUNTRY 국가 선택기 없음
FORMULA 계산된 필드 Required: formula
REFERENCE 다른 기록에 대한 링크 Required: referenceProjectId
LOOKUP 참조에서 데이터 가져오기 Required: lookupOption
TIME_DURATION 시간 추적 Required: duration inputs (see below)
BUTTON 액션 버튼 Optional: buttonType, buttonConfirmText
CURRENCY_CONVERSION 통화 변환기 Special configuration

필드 유형 구성 예제

제약 조건이 있는 숫자 필드

mutation CreateQuantityField {
  createCustomField(input: {
    name: "Quantity"
    type: NUMBER
    description: "Number of items"
    min: 1
    max: 999
  }) {
    id
    name
    min
    max
  }
}

통화 필드

mutation CreateBudgetField {
  createCustomField(input: {
    name: "Budget"
    type: CURRENCY
    currency: "EUR"
    min: 0
  }) {
    id
    name
    currency
    min
  }
}

마감일 플래그가 있는 날짜 필드

mutation CreateDeadlineField {
  createCustomField(input: {
    name: "Project Deadline"
    type: DATE
    isDueDate: true
    description: "When this project must be completed"
  }) {
    id
    name
    isDueDate
  }
}

참조 필드

mutation CreateRelatedTasksField {
  createCustomField(input: {
    name: "Dependencies"
    type: REFERENCE
    referenceProjectId: "proj_abc123"
    referenceMultiple: true
    referenceFilter: {
      statusIds: ["status_open", "status_inprogress"]
    }
  }) {
    id
    name
    referenceProjectId
    referenceMultiple
  }
}

조회 필드

mutation CreateLookupField {
  createCustomField(input: {
    name: "Customer Email"
    type: LOOKUP
    lookupOption: {
      referenceId: "field_customer_ref"
      lookupId: "field_email"
      lookupType: TODO_CUSTOM_FIELD
    }
  }) {
    id
    name
    customFieldLookupOption {
      referenceId
      lookupId
      lookupType
    }
  }
}

시퀀스가 있는 고유 ID

mutation CreateOrderNumberField {
  createCustomField(input: {
    name: "Order Number"
    type: UNIQUE_ID
    prefix: "ORD-"
    useSequenceUniqueId: true
    sequenceDigits: 6
    sequenceStartingNumber: 1000
  }) {
    id
    name
    prefix
  }
}

시간 지속 필드

mutation CreateTimeTrackingField {
  createCustomField(input: {
    name: "Time to Resolution"
    type: TIME_DURATION
    timeDurationDisplay: FULL_DATE_STRING
    timeDurationStartInput: {
      type: TODO_CREATED_AT
      condition: FIRST
    }
    timeDurationEndInput: {
      type: TODO_MARKED_AS_COMPLETE
      condition: FIRST
    }
  }) {
    id
    name
  }
}

유효한 시간 지속 유형

  • TODO_CREATED_AT - 레코드가 생성된 시간
  • TODO_CUSTOM_FIELD - 사용자 정의 필드가 변경될 때
  • TODO_DUE_DATE - 마감일이 설정/변경될 때
  • TODO_MARKED_AS_COMPLETE - 레코드가 완료로 표시될 때
  • TODO_MOVED - 레코드가 다른 목록으로 이동될 때
  • TODO_TAG_ADDED - 태그가 추가될 때
  • TODO_ASSIGNEE_ADDED - 담당자가 추가될 때

선택 옵션 생성

SELECT_SINGLE 또는 SELECT_MULTI 필드를 생성한 후 옵션을 추가합니다:

mutation CreateSelectOptions {
  createCustomFieldOptions(input: {
    customFieldId: "field_xyz789"
    customFieldOptions: [
      { title: "High", color: "#FF0000", position: 1 }
      { title: "Medium", color: "#FFA500", position: 2 }
      { title: "Low", color: "#00FF00", position: 3 }
    ]
  }) {
    id
    title
    color
    position
  }
}

응답 필드

CustomField

필드 유형 설명
id String! 고유 식별자
uid String! 사용자 친화적인 고유 ID
name String! 표시 이름
type CustomFieldType! 필드 유형
description String 필드 설명
position Float! 표시 순서 위치
createdAt DateTime! 생성 타임스탬프
updatedAt DateTime! 마지막 업데이트 타임스탬프
min Float 최소값 (해당되는 경우)
max Float 최대값 (해당되는 경우)
currency String 통화 코드 (CURRENCY 유형)
prefix String ID 접두사 (UNIQUE_ID 유형)
isDueDate Boolean 마감일 플래그 (DATE 유형)
formula JSON 공식 구성 (FORMULA 유형)
referenceProjectId String 참조된 프로젝트 (REFERENCE 유형)
customFieldLookupOption CustomFieldLookupOption 조회 구성 (LOOKUP 유형)

필수 권한

사용자 정의 필드를 생성하려면 프로젝트 접근이 필요합니다:

역할 사용자 정의 필드 생성 가능
OWNER ✅ 예
ADMIN ✅ 예
MEMBER ✅ 예
CLIENT ❌ 아니오

참고: 사용자 정의 역할은 필드 관리에 대한 추가 제한이 있을 수 있습니다.

오류 응답

잘못된 필드 유형

{
  "errors": [{
    "message": "Variable \"$input\" got invalid value \"INVALID\" at \"input.type\"; Value \"INVALID\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

참조 프로젝트를 찾을 수 없음

{
  "errors": [{
    "message": "Reference project not found or access denied",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

필수 구성 누락

{
  "errors": [{
    "message": "REFERENCE fields require referenceProjectId",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

중요 사항

  • 필드 위치: 기존 필드의 끝에 나타나도록 자동으로 계산됨
  • 필드 제한: 프로젝트는 사용자 정의 필드의 수에 제한이 있을 수 있음
  • 즉시 사용 가능: 생성된 필드는 즉시 사용 가능
  • 부작용: 필드를 생성하면 다음이 발생함:
    • 활동 로그 항목
    • 연결된 사용자에 대한 실시간 업데이트
    • 웹훅 알림
    • FORMULA, LOOKUP 및 UNIQUE_ID 필드에 대한 백그라운드 작업
  • 특별 고려 사항:
    • REFERENCE 필드는 대상 프로젝트에 대한 접근이 필요함
    • LOOKUP 필드는 기존 REFERENCE 필드에 의존함
    • FORMULA 필드는 자신을 참조할 수 없음
    • UNIQUE_ID 시퀀스는 비동기적으로 처리됨
    • SELECT 필드는 별도로 옵션을 생성해야 함
  • 명명: 필드 이름은 UI에 나타나는 대로 명확하고 설명적이어야 함

관련 엔드포인트

© Blue | 사랑으로 디자인 ❤ 전체에 걸쳐

AI 어시스턴트

응답은 AI를 사용하여 생성되며 오류가 포함될 수 있습니다.

어떻게 도와드릴까요?

Blue 또는 이 문서에 대해 궁금한 점이 있으면 무엇이든 물어보세요.

전송하려면 Enter • 새 줄을 추가하려면 Shift+Enter • ⌘I를 눌러 열기