---

Visão Geral

Os campos personalizados permitem que você estenda a estrutura padrão de registros do Blue com campos de dados adicionais específicos para as necessidades do seu negócio. Eles fornecem uma maneira poderosa de capturar dados estruturados além dos campos embutidos, como título, descrição e data de vencimento.

Os campos personalizados são definidos no nível do projeto e podem ser usados em todos os registros (tarefas) dentro desse projeto. Cada campo tem um tipo específico que determina suas regras de validação, formato de entrada e comportamento de exibição.

Operações Disponíveis

Gerenciamento de Campos Principais

Operação	Descrição	Link
List Custom Fields	Consultar e filtrar campos personalizados	View Details →
Create Custom Field	Adicionar novos campos personalizados a projetos	View Details →
Delete Custom Field	Remover campos personalizados com limpeza adequada	View Details →

Valores de Campo

Operação	Descrição	Link
Set Field Values	Definir e atualizar valores de campos personalizados em registros	View Details →

Tipos de Campos Personalizados

Campos de Texto

Tipo	Descrição	Casos de Uso	Link
TEXT_SINGLE	Entrada de texto em uma linha	Names, titles, short descriptions	View Details →
TEXT_MULTI	Área de texto de múltiplas linhas	Descrições longas, notas, comentários	View Details →

Campos de Seleção

Tipo	Descrição	Casos de Uso	Link
SELECT_SINGLE	Dropdown de seleção única	Status, priority, category	View Details →
SELECT_MULTI	Dropdown de seleção múltipla	Tags, skills, categories	View Details →
CHECKBOX	Campo de checkbox booleano	Flags, approvals, confirmations	View Details →

Campos Numéricos

Tipo	Descrição	Casos de Uso	Link
NUMBER	Entrada numérica	Quantities, scores, measurements	View Details →
CURRENCY	Valor monetário	Budgets, costs, pricing	View Details →
PERCENT	Valor percentual	Completion rates, discounts	View Details →
RATING	Avaliação em estrelas com escala personalizada	Performance ratings, satisfaction	View Details →
FORMULA	Campo calculado com base em outros campos	Totals, computations, aggregations	View Details →

Campos de Contato

Tipo	Descrição	Casos de Uso	Link
EMAIL	Endereço de e-mail com validação	Informações de contato, notificações	View Details →
PHONE	Número de telefone com formatação internacional	Contact details, emergency contacts	View Details →
URL	URL da web com validação	Links, references, resources	View Details →

Campos de Data e Hora

Tipo	Descrição	Casos de Uso	Link
DATE	Seletor de data	Deadlines, milestones, events	View Details →
TIME_DURATION	Campo de rastreamento de tempo	Work hours, duration estimates	View Details →

Localização e Geografia

Tipo	Descrição	Casos de Uso	Link
LOCATION	Localização geográfica (lat/lng)	Addresses, venues, service areas	View Details →
COUNTRY	Seletor de país	Regional assignments, localization	View Details →

Arquivo e Mídia

Tipo	Descrição	Casos de Uso	Link
FILE	Anexo de arquivo	Documents, images, resources	View Details →

Campos do Sistema

Tipo	Descrição	Casos de Uso	Link
UNIQUE_ID	Identificador único gerado automaticamente	Ticket numbers, order IDs	View Details →
REFERENCE	Link para registros em outro projeto	Cross-project relationships	View Details →
LOOKUP	Extrair dados de registros referenciados	Aggregate data from related records	View Details →

Campos Interativos

Tipo	Descrição	Casos de Uso	Link
BUTTON	Campo de botão acionável	Triggers, actions, workflows	View Details →
CURRENCY_CONVERSION	Campo de conversão de moeda	Multi-currency calculations	View Details →

Conceitos Chave

Definição de Campo

• Campos personalizados são definidos no nível do projeto
• Cada campo tem um nome e tipo únicos
• Os campos podem incluir regras de validação e restrições
• As opções de configuração variam de acordo com o tipo de campo

Valores de Campo

• Os valores são armazenados em registros individuais (tarefas)
• Cada registro pode ter valores diferentes para o mesmo campo
• Valores vazios/nulos são permitidos para campos opcionais
• Os valores são validados de acordo com as regras do tipo de campo

Modelo de Permissões

Os campos personalizados respeitam as permissões em nível de projeto:

Função	Criar Campos	Editar Campos*	Definir Valores	Visualizar Valores
OWNER	✅ Sim	✅ Sim	✅ Sim	✅ Sim
ADMIN	✅ Sim	✅ Sim	✅ Sim	✅ Sim
MEMBER	❌ Não	❌ Não	✅ Sim	✅ Sim
CLIENT	❌ Não	❌ Não	✅ Limitado	✅ Limitado

*Editar Campos refere-se à modificação das configurações do campo (nome, tipo, opções, regras de validação) - não à definição de valores de campo em registros

Permissões de Função Personalizada

• Projetos podem ter funções personalizadas com permissões específicas para campos
• Os campos podem ser marcados como editáveis/não editáveis por função
• Funções personalizadas podem restringir o acesso a campos específicos

Padrões Comuns

Criando um Campo Personalizado Básico

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
    }
  }
}

Definindo Valores de Campo em Registros

mutation SetFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionId: "option_789"  # For SELECT_SINGLE
  })
}

Consultando Registros com Campos Personalizados

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
    }
  }
}

Criando Registros com Valores de Campos Personalizados

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
    }
  }
}

Melhores Práticas

Design de Campos

1. Use nomes descritivos - Deixe claro os propósitos dos campos
2. Escolha tipos apropriados - Combine o tipo de campo com os requisitos de dados
3. Defina regras de validação - Use valores mínimos/máximos, campos obrigatórios
4. Organize logicamente - Agrupe campos relacionados

Considerações de Desempenho

1. Limite a contagem de campos - Muitos campos podem impactar o desempenho
2. Use paginação - Ao consultar grandes conjuntos de dados
3. Indexe campos-chave - Para campos usados em filtragem/classificação
4. Evite aninhamento profundo - Mantenha as relações de campo simples

Qualidade de Dados

1. Valide a entrada - Use tipos de campo apropriados com validação
2. Forneça padrões - Defina valores padrão sensatos onde apropriado
3. Use formatos consistentes - Padronize os padrões de entrada de dados
4. Limpeza regular - Remova campos e opções não utilizados

Experiência do Usuário

1. Descrições claras - Forneça descrições úteis dos campos
2. Ordenação lógica - Posicione os campos em uma ordem natural de fluxo de trabalho
3. Hierarquia visual - Use cores e formatação de forma eficaz
4. Divulgação progressiva - Mostre campos quando relevantes

Tratamento de Erros

Erros comuns ao trabalhar com campos personalizados:

Código de Erro	Descrição	Solução
CUSTOM_FIELD_NOT_FOUND	Campo não existe	Verify field ID and project access
VALIDATION_ERROR	Valor não corresponde ao tipo de campo	Check format and validation rules
UNAUTHORIZED	Permissões insuficientes	Ensure proper role level
CUSTOM_FIELD_VALUE_PARSE_ERROR	Formato de valor inválido	Review field type requirements

Recursos Relacionados

• API de Registros - Trabalhando com registros que contêm campos personalizados
• API de Projetos - Gerenciando projetos que contêm campos personalizados
• API de Automação - Automatizando fluxos de trabalho com gatilhos de campos personalizados
• API de Gerenciamento de Usuários - Gerenciando permissões de campos personalizados