Установить значения пользовательских полей

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

Установить значения пользовательских полей

Пользовательские поля расширяют стандартную структуру записей Blue специфическими для бизнеса данными. Этот конечный пункт позволяет вам установить или обновить значения для любого пользовательского поля в записи. Каждый тип поля требует специфических параметров для обеспечения целостности данных и правильной валидации.

Простой пример

mutation SetTextFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_xyz789"
    text: "Project specification document"
  })
}

Расширенный пример

mutation SetMultipleFieldTypes {
  # Set a date range field
  dateField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_date_001"
    startDate: "2024-01-15T09:00:00Z"
    endDate: "2024-01-31T17:00:00Z"
    timezone: "America/New_York"
  })
  
  # Set a multi-select field
  selectField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_select_002"
    customFieldOptionIds: ["option_high", "option_urgent", "option_client"]
  })
  
  # Set a location field
  locationField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_location_003"
    latitude: 40.7128
    longitude: -74.0060
  })
}

Входные параметры

SetTodoCustomFieldInput

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	Идентификатор записи для обновления
`customFieldId`	String!	✅ Да	Идентификатор пользовательского поля
`text`	String	Нет	Для TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
`number`	Float	Нет	Для NUMBER, PERCENT, RATING
`currency`	String	Нет	Код валюты для типа CURRENCY (например, "USD")
`checked`	Boolean	Нет	Для полей CHECKBOX
`startDate`	DateTime	Нет	Дата начала для полей DATE
`endDate`	DateTime	Нет	Дата окончания для полей диапазона DATE
`timezone`	String	Нет	Часовой пояс для полей DATE (например, "America/New_York")
`latitude`	Float	Нет	Широта для полей LOCATION
`longitude`	Float	Нет	Долгота для полей LOCATION
`regionCode`	String	Нет	Код региона для полей PHONE
`countryCodes`	[String!]	Нет	ISO коды стран для полей COUNTRY
`customFieldOptionId`	String	Нет	Идентификатор опции для полей SELECT_SINGLE
`customFieldOptionIds`	[String!]	Нет	Идентификаторы опций для полей SELECT_MULTI
`customFieldReferenceTodoIds`	[String!]	Нет	Идентификаторы записей для полей REFERENCE

Примеры типов полей

Текстовые поля

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_description"
    text: "Detailed project requirements and specifications"
  })
}

Числовые поля

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_budget"
    number: 15000.50
  })
}

Поля выбора

# Single Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_priority"
    customFieldOptionId: "option_high"
  })
}

# Multi Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_tags"
    customFieldOptionIds: ["option_frontend", "option_urgent", "option_v2"]
  })
}

Дата

# Single Date
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_deadline"
    startDate: "2024-12-31T23:59:59Z"
  })
}

# Date Range
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_project_timeline"
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-03-31T23:59:59Z"
    timezone: "UTC"
  })
}

Поля местоположения

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_office_location"
    latitude: 37.7749
    longitude: -122.4194
  })
}

Поля валюты

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_invoice_amount"
    number: 5000
    currency: "USD"
  })
}

Поля файлов

Поля файлов используют отдельные мутации:

# Add a file
mutation {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

# Remove a file
mutation {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

Установка значений при создании записи

Вы можете установить значения пользовательских полей при создании новой записи:

mutation {
  createTodo(input: {
    todoListId: "list_project_123"
    title: "New Feature Development"
    customFields: [
      {
        customFieldId: "field_priority"
        value: "high"
      },
      {
        customFieldId: "field_estimate"
        value: "8"
      }
    ]
  }) {
    id
    customFields {
      customField {
        name
      }
      value
    }
  }
}

Поля ответа

Мутация возвращает логическое значение, указывающее на успех:

Поле	Тип	Описание
`setTodoCustomField`	Boolean!	True, если операция успешна

Обязательные разрешения

Пользователи должны иметь разрешение на редактирование как записи, так и конкретного пользовательского поля:

Роль	Может устанавливать значения полей
`OWNER`	✅ Да
`ADMIN`	✅ Да
`MEMBER`	✅ Да (если не ограничено пользовательской ролью)
`CLIENT`	✅ Да (если не ограничено пользовательской ролью)

Для пользователей с пользовательскими ролями проекта система выполняет двухуровневую проверку:

Сначала проверяется, есть ли у пользователя доступ на уровне проекта
Затем проверяется, отмечено ли конкретное поле как editable в их конфигурации пользовательской роли

Это означает, что у пользователя может быть общий доступ к проекту, но он все равно может быть ограничен в редактировании определенных полей в зависимости от своей пользовательской роли.

Ответы об ошибках

Пользовательское поле не найдено

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Неавторизованный доступ

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Неверное значение поля

{
  "errors": [{
    "message": "Invalid value for field type NUMBER",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Важные заметки

Поведение Upsert: Мутация создает новое значение поля, если оно не существует, или обновляет существующее значение
Безопасность типов: Предоставляйте только параметры, которые соответствуют типу поля (например, не отправляйте text для поля NUMBER)
Побочные эффекты: Установка значений вызывает:
- Пересчеты формульных полей
- Правила автоматизации
- Уведомления вебхуков
- Записи в журнале активности
- Обновления графиков
Специальные поведения:
- Поля CURRENCY автоматически обрабатывают расчеты конверсии
- Поля REFERENCE обновляют двунаправленные отношения
- Поля FORMULA являются только для чтения и не могут быть установлены напрямую (они рассчитываются автоматически)
- Поля LOOKUP являются только для чтения и не могут быть установлены напрямую (они извлекают данные из ссылочных записей)
- Поля BUTTON вызывают события автоматизации при "нажатии"
Валидация: API проверяет, что:
- Запись существует в проекте
- Пользовательское поле существует в том же проекте
- У пользователя есть разрешения на редактирование
- Значение соответствует требованиям типа поля

Справочник формата значений

Тип поля	Параметр	Формат	Пример
`TEXT_SINGLE`	`text`	String	`"Project Alpha"`
`TEXT_MULTI`	`text`	String with newlines	`"Line 1\nLine 2"`
`NUMBER`	`number`	Float	`42.5`
`CURRENCY`	`number` + `currency`	Float + ISO code	`1000.00` + `"USD"`
`PERCENT`	`number`	Float (0-100)	`75`
`RATING`	`number`	Float (within min/max)	`4.5`
`CHECKBOX`	`checked`	Boolean	`true`
`DATE`	`startDate`	ISO 8601 DateTime	`"2024-01-15T00:00:00Z"`
`DATE` (range)	`startDate` + `endDate`	ISO 8601 DateTimes	See example above
`SELECT_SINGLE`	`customFieldOptionId`	Option ID	`"option_123"`
`SELECT_MULTI`	`customFieldOptionIds`	Array of Option IDs	`["opt_1", "opt_2"]`
`PHONE`	`text`	String	`"+1-555-123-4567"`
`EMAIL`	`text`	String	`"user@example.com"`
`URL`	`text`	String	`"https://example.com"`
`LOCATION`	`latitude` + `longitude`	Floats	`40.7128, -74.0060`
`COUNTRY`	`countryCodes`	ISO 3166 codes	`["US", "CA"]`
`REFERENCE`	`customFieldReferenceTodoIds`	Array of record IDs	`["todo_1", "todo_2"]`
`FORMULA`	N/A	Read-only - calculated automatically	N/A
`LOOKUP`	N/A	Read-only - pulls from references	N/A

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

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