사용자 정의 필드를 관리하기 위한 전체 API 참조 - 데이터 구조를 확장하기 위해 사용자 정의 필드를 생성, 구성 및 사용
개요
사용자 정의 필드는 귀하의 비즈니스 요구에 맞는 추가 데이터 필드로 Blue의 표준 레코드 구조를 확장할 수 있게 해줍니다. 이들은 제목, 설명 및 마감일과 같은 기본 제공 필드를 넘어 구조화된 데이터를 캡처하는 강력한 방법을 제공합니다.
사용자 정의 필드는 프로젝트 수준에서 정의되며 해당 프로젝트 내의 모든 레코드(할 일)에서 사용할 수 있습니다. 각 필드는 유효성 검사 규칙, 입력 형식 및 표시 동작을 결정하는 특정 유형을 가지고 있습니다.
사용 가능한 작업
핵심 필드 관리
필드 값
사용자 정의 필드 유형
텍스트 필드
선택 필드
| 유형 |
설명 |
사용 사례 |
링크 |
| SELECT_SINGLE |
단일 선택 드롭다운 |
Status, priority, category |
View Details → |
| SELECT_MULTI |
다중 선택 드롭다운 |
Tags, skills, categories |
View Details → |
| CHECKBOX |
불리언 체크박스 필드 |
Flags, approvals, confirmations |
View Details → |
숫자 필드
연락처 필드
날짜 및 시간 필드
| 유형 |
설명 |
사용 사례 |
링크 |
| DATE |
날짜 선택기 |
Deadlines, milestones, events |
View Details → |
| TIME_DURATION |
시간 추적 필드 |
Work hours, duration estimates |
View Details → |
위치 및 지리
| 유형 |
설명 |
사용 사례 |
링크 |
| LOCATION |
지리적 위치 (위도/경도) |
Addresses, venues, service areas |
View Details → |
| COUNTRY |
국가 선택기 |
Regional assignments, localization |
View Details → |
파일 및 미디어
시스템 필드
| 유형 |
설명 |
사용 사례 |
링크 |
| UNIQUE_ID |
자동 생성된 고유 식별자 |
Ticket numbers, order IDs |
View Details → |
| REFERENCE |
다른 프로젝트의 레코드 링크 |
Cross-project relationships |
View Details → |
| LOOKUP |
참조된 레코드에서 데이터 가져오기 |
Aggregate data from related records |
View Details → |
인터랙티브 필드
| 유형 |
설명 |
사용 사례 |
링크 |
| BUTTON |
실행 가능한 버튼 필드 |
Triggers, actions, workflows |
View Details → |
| CURRENCY_CONVERSION |
통화 변환 필드 |
Multi-currency calculations |
View Details → |
주요 개념
필드 정의
- 사용자 정의 필드는 프로젝트 수준에서 정의됩니다.
- 각 필드는 고유한 이름과 유형을 가집니다.
- 필드는 유효성 검사 규칙 및 제약 조건을 포함할 수 있습니다.
- 구성 옵션은 필드 유형에 따라 다릅니다.
필드 값
- 값은 개별 레코드(할 일)에 저장됩니다.
- 각 레코드는 동일한 필드에 대해 다른 값을 가질 수 있습니다.
- 선택적 필드에 대해서는 빈/null 값이 허용됩니다.
- 값은 필드 유형 규칙에 따라 검증됩니다.
권한 모델
사용자 정의 필드는 프로젝트 수준의 권한을 존중합니다:
| 역할 |
필드 생성 |
필드 편집* |
값 설정 |
값 보기 |
| OWNER |
✅ 예 |
✅ 예 |
✅ 예 |
✅ 예 |
| ADMIN |
✅ 예 |
✅ 예 |
✅ 예 |
✅ 예 |
| MEMBER |
❌ 아니오 |
❌ 아니오 |
✅ 예 |
✅ 예 |
| CLIENT |
❌ 아니오 |
❌ 아니오 |
✅ 제한됨 |
✅ 제한됨 |
*필드 편집은 필드 설정(이름, 유형, 옵션, 유효성 검사 규칙)을 수정하는 것을 의미하며, 레코드에서 필드 값을 설정하는 것은 아닙니다.
사용자 정의 역할 권한
- 프로젝트는 필드별 권한이 있는 사용자 정의 역할을 가질 수 있습니다.
- 역할별로 필드를 편집 가능/비편집 가능으로 표시할 수 있습니다.
- 사용자 정의 역할은 특정 필드에 대한 접근을 제한할 수 있습니다.
일반 패턴
기본 사용자 정의 필드 생성
mutation CreateCustomField {
createCustomField(input: {
name: "Priority Level"
type: SELECT_SINGLE
description: "Task priority level"
customFieldOptions: [
{ title: "Low", color: "#28a745" }
{ title: "Medium", color: "#ffc107" }
{ title: "High", color: "#fd7e14" }
{ title: "Critical", color: "#dc3545" }
]
}) {
id
name
type
customFieldOptions {
id
title
color
}
}
}
레코드에서 필드 값 설정
mutation SetFieldValue {
setTodoCustomField(input: {
todoId: "todo_123"
customFieldId: "field_456"
customFieldOptionId: "option_789" # For SELECT_SINGLE
})
}
사용자 정의 필드로 레코드 쿼리
query GetTodosWithCustomFields {
todos(projectId: "project_123") {
id
title
customFields {
id
customField {
name
type
}
# Type-specific value fields
text # TEXT_SINGLE, TEXT_MULTI, EMAIL, etc.
number # NUMBER, CURRENCY, PERCENT, RATING
selectedOption # SELECT_SINGLE
selectedOptions # SELECT_MULTI
checked # CHECKBOX
date # DATE
}
}
}
사용자 정의 필드 값으로 레코드 생성
mutation CreateTodoWithCustomFields {
createTodo(input: {
title: "New task"
todoListId: "list_123"
customFields: [
{ customFieldId: "priority_field", value: "high_priority_option" }
{ customFieldId: "budget_field", value: "5000" }
{ customFieldId: "notes_field", value: "Additional context here" }
]
}) {
id
title
customFields {
customField { name }
value
}
}
}
모범 사례
필드 디자인
- 설명적인 이름 사용 - 필드 목적을 명확히 하세요.
- 적절한 유형 선택 - 데이터 요구 사항에 맞는 필드 유형을 선택하세요.
- 유효성 검사 규칙 설정 - 최소/최대 값, 필수 필드를 사용하세요.
- 논리적으로 조직 - 관련 필드를 함께 그룹화하세요.
성능 고려 사항
- 필드 수 제한 - 너무 많은 필드는 성능에 영향을 줄 수 있습니다.
- 페이지네이션 사용 - 대량 데이터 세트를 쿼리할 때.
- 주요 필드 인덱스 - 필터링/정렬에 사용되는 필드에 대해.
- 깊은 중첩 피하기 - 필드 관계를 간단하게 유지하세요.
데이터 품질
- 입력 검증 - 유효성 검사가 있는 적절한 필드 유형을 사용하세요.
- 기본값 제공 - 적절한 기본값을 설정하세요.
- 일관된 형식 사용 - 데이터 입력 패턴을 표준화하세요.
- 정기적인 정리 - 사용하지 않는 필드 및 옵션을 제거하세요.
사용자 경험
- 명확한 설명 - 유용한 필드 설명을 제공하세요.
- 논리적 순서 - 자연스러운 작업 흐름 순서로 필드를 배치하세요.
- 시각적 계층 구조 - 색상과 형식을 효과적으로 사용하세요.
- 점진적 공개 - 관련 있을 때 필드를 표시하세요.
오류 처리
사용자 정의 필드 작업 시 발생할 수 있는 일반적인 오류:
| 오류 코드 |
설명 |
해결책 |
CUSTOM_FIELD_NOT_FOUND |
필드가 존재하지 않음 |
Verify field ID and project access |
VALIDATION_ERROR |
값이 필드 유형과 일치하지 않음 |
Check format and validation rules |
UNAUTHORIZED |
권한 부족 |
Ensure proper role level |
CUSTOM_FIELD_VALUE_PARSE_ERROR |
잘못된 값 형식 |
Review field type requirements |
관련 리소스