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

Создайте интерактивные поля кнопок, которые запускают автоматизации при нажатии

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

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

Создайте простое поле кнопки, которое запускает автоматизацию:

mutation CreateButtonField {
  createCustomField(input: {
    name: "Send Invoice"
    type: BUTTON
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

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

Создайте кнопку с требованиями подтверждения:

mutation CreateButtonWithConfirmation {
  createCustomField(input: {
    name: "Delete All Attachments"
    type: BUTTON
    projectId: "proj_123"
    buttonType: "hardConfirmation"
    buttonConfirmText: "DELETE"
    description: "Permanently removes all attachments from this task"
  }) {
    id
    name
    type
    buttonType
    buttonConfirmText
    description
  }
}

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

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя кнопки
`type`	CustomFieldType!	✅ Да	Должно быть `BUTTON`
`projectId`	String!	✅ Да	Идентификатор проекта, в котором будет создано поле
`buttonType`	String	Нет	Поведение подтверждения (см. Типы кнопок ниже)
`buttonConfirmText`	String	Нет	Текст, который пользователи должны ввести для жесткого подтверждения
`description`	String	Нет	Помощь, отображаемая пользователям
`required`	Boolean	Нет	Является ли поле обязательным (по умолчанию false)
`isActive`	Boolean	Нет	Является ли поле активным (по умолчанию true)

Тип поля кнопки

Поле buttonType является строкой произвольного формата, которую могут использовать клиенты пользовательского интерфейса для определения поведения подтверждения. Распространенные значения включают:

"" (пусто) - Нет подтверждения
"soft" - Простое диалоговое окно подтверждения
"hard" - Требуется ввод текста подтверждения

Примечание: Это только подсказки для пользовательского интерфейса. API не проверяет и не требует конкретные значения.

Запуск нажатий кнопки

Чтобы запустить нажатие кнопки и выполнить связанные автоматизации:

mutation ClickButton {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
  })
}

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

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	Идентификатор задачи, содержащей кнопку
`customFieldId`	String!	✅ Да	Идентификатор пользовательского поля кнопки

Важно: Поведение API

Все нажатия кнопок через API выполняются немедленно независимо от любых настроек buttonType или buttonConfirmText. Эти поля хранятся для клиентов пользовательского интерфейса, чтобы реализовать диалоговые окна подтверждения, но сам API:

Не проверяет текст подтверждения
Не требует никаких требований к подтверждению
Выполняет действие кнопки немедленно при вызове

Подтверждение является чисто функцией безопасности пользовательского интерфейса на стороне клиента.

Пример: Нажатие различных типов кнопок

# Button with no confirmation
mutation ClickSimpleButton {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "simple_button_id"
  })
}

# Button with soft confirmation (API call is the same!)
mutation ClickSoftConfirmButton {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "soft_confirm_button_id"
  })
}

# Button with hard confirmation (API call is still the same!)
mutation ClickHardConfirmButton {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "hard_confirm_button_id"
  })
}

Все три мутации выше выполнят действие кнопки немедленно при вызове через API, обходя любые требования к подтверждению.

Поля ответа

Ответ пользовательского поля

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для пользовательского поля
`name`	String!	Отображаемое имя кнопки
`type`	CustomFieldType!	Всегда `BUTTON` для полей кнопок
`buttonType`	String	Настройка поведения подтверждения
`buttonConfirmText`	String	Обязательный текст подтверждения (если используется жесткое подтверждение)
`description`	String	Помощь для пользователей
`required`	Boolean!	Является ли поле обязательным
`isActive`	Boolean!	Является ли поле в настоящее время активным
`projectId`	String!	Идентификатор проекта, к которому принадлежит это поле
`createdAt`	DateTime!	Когда поле было создано
`updatedAt`	DateTime!	Когда поле было в последний раз изменено

Как работают поля кнопок

Интеграция автоматизации

Поля кнопок предназначены для работы с системой автоматизации Blue:

Создайте поле кнопки с помощью вышеуказанной мутации
Настройте автоматизации, которые слушают события CUSTOM_FIELD_BUTTON_CLICKED
Пользователи нажимают кнопку в пользовательском интерфейсе
Автоматизации выполняют настроенные действия

Поток событий

Когда кнопка нажата:

User Click → setTodoCustomField mutation → CUSTOM_FIELD_BUTTON_CLICKED event → Automation execution

Нет хранения данных

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

Генерирует событие
Запускает связанные автоматизации
Записывает действие в историю задач
Не изменяет никакое значение поля

Необходимые разрешения

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

Действие	Необходимая роль
Create button field	`OWNER` or `ADMIN` at project level
Update button field	`OWNER` or `ADMIN` at project level
Click button	`OWNER`, `ADMIN`, `MEMBER`, or `CLIENT` (based on field permissions)
Configure automations	`OWNER` or `ADMIN` at project level

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

Доступ запрещен

{
  "errors": [{
    "message": "You don't have permission to edit this custom field",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

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

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

Примечание: API не возвращает конкретные ошибки для отсутствующих автоматизаций или несоответствий подтверждения.

Общие случаи использования

Переходы рабочих процессов
- "Отметить как завершенное"
- "Отправить на утверждение"
- "Архивировать задачу"
Внешние интеграции
- "Синхронизировать с CRM"
- "Сгенерировать счет"
- "Отправить обновление по электронной почте"
Пакетные операции
- "Обновить все подзадачи"
- "Скопировать в проекты"
- "Применить шаблон"
Действия по отчетности
- "Сгенерировать отчет"
- "Экспортировать данные"
- "Создать сводку"

Ограничения

Кнопки не могут хранить или отображать значения данных
Каждая кнопка может только запускать автоматизации, а не прямые вызовы API (однако автоматизации могут включать действия HTTP-запросов для вызова внешних API или собственных API Blue)
Видимость кнопки не может быть условно контролируема
Максимум одно выполнение автоматизации за нажатие (хотя эта автоматизация может запускать несколько действий)

Связанные ресурсы

API автоматизаций - Настройте действия, запускаемые кнопками
Обзор пользовательских полей - Общие концепции пользовательских полей