사용자 정의 필드 생성

사용자 정의 필드는 기록에 구조화된 데이터 필드를 추가하여 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

CustomFieldType 값

필드 유형 구성 예제

제약 조건이 있는 숫자 필드

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

필수 권한

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

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

오류 응답

잘못된 필드 유형

{
  "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에 나타나는 대로 명확하고 설명적이어야 함

관련 엔드포인트

• 사용자 정의 필드 목록 - 기존 사용자 정의 필드 보기
• 사용자 정의 필드 업데이트 - 필드 속성 수정
• 사용자 정의 필드 삭제 - 사용자 정의 필드 제거
• 필드 옵션 생성 - 선택 필드에 옵션 추가
• 사용자 정의 필드 값 설정 - 레코드에 값 설정