Создание пользовательского поля

Добавьте новые пользовательские поля, чтобы расширить структуру данных вашего проекта с конфигурациями, специфичными для типа

Создание пользовательского поля

Пользовательские поля позволяют адаптировать 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	Нет	Код валюты ISO для полей CURRENCY
`prefix`	String	Нет	Текстовый префикс для полей UNIQUE_ID
`isDueDate`	Boolean	Нет	Указывает, представляет ли поле DATE срок исполнения
`formula`	JSON	Нет	Конфигурация формулы для полей FORMULA
`referenceProjectId`	String	Нет	Целевой ID проекта для полей REFERENCE
`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 требуют создания вариантов отдельно
Именование: Имена полей должны быть четкими и описательными, как они отображаются в интерфейсе

Связанные конечные точки

Список пользовательских полей - Просмотр существующих пользовательских полей
Обновить пользовательское поле - Изменить свойства поля
Удалить пользовательское поле - Удалить пользовательское поле
Создать варианты полей - Добавить варианты в поля выбора
Установить значения пользовательских полей - Установить значения в записях