Criar um Campo Personalizado

Adicione novos campos personalizados para estender a estrutura de dados do seu projeto com configurações específicas de tipo

Criar um Campo Personalizado

Campos personalizados permitem que você adapte o Blue às suas necessidades específicas de negócios, adicionando campos de dados estruturados aos seus registros. Este endpoint cria um novo campo personalizado com configurações específicas para cada tipo de campo.

Exemplo Básico

mutation CreateTextField {
  createCustomField(input: {
    name: "Customer Name"
    type: TEXT_SINGLE
    description: "Primary customer contact name"
  }) {
    id
    uid
    name
    type
    position
  }
}

Exemplo Avançado

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

Parâmetros de Entrada

CreateCustomFieldInput

Parâmetro	Tipo	Necessário	Descrição
`name`	String!	✅ Sim	O nome exibido do campo personalizado
`type`	CustomFieldType!	✅ Sim	O tipo de campo (veja os tipos abaixo)
`description`	String	Não	Descrição opcional explicando o propósito do campo
`min`	Float	Não	Valor mínimo para campos NUMBER, RATING, PERCENT
`max`	Float	Não	Valor máximo para campos NUMBER, RATING, PERCENT
`currency`	String	Não	Código da moeda ISO para campos CURRENCY
`prefix`	String	Não	Prefixo de texto para campos UNIQUE_ID
`isDueDate`	Boolean	Não	Se o campo DATE representa uma data de vencimento
`formula`	JSON	Não	Configuração de fórmula para campos FORMULA
`referenceProjectId`	String	Não	ID do projeto de destino para campos REFERENCE
`referenceMultiple`	Boolean	Não	Permitir múltiplas seleções em campos REFERENCE
`referenceFilter`	TodoFilterInput	Não	Opções de filtro para campos REFERENCE
`lookupOption`	CustomFieldLookupOptionInput	Não	Configuração para campos LOOKUP
`timeDurationDisplay`	CustomFieldTimeDurationDisplayType	Não	Formato de exibição para TIME_DURATION
`timeDurationTargetTime`	Float	Não	Tempo alvo em segundos para TIME_DURATION
`timeDurationStartInput`	CustomFieldTimeDurationInput	Não	Gatilho de início para TIME_DURATION
`timeDurationEndInput`	CustomFieldTimeDurationInput	Não	Gatilho de fim para TIME_DURATION
`buttonType`	String	Não	Tipo de ação do botão para campos BUTTON
`buttonConfirmText`	String	Não	Prompt de confirmação para campos BUTTON
`useSequenceUniqueId`	Boolean	Não	Usar numeração sequencial para UNIQUE_ID
`sequenceDigits`	Int	Não	Número de dígitos na sequência (ex: 5 → 00001)
`sequenceStartingNumber`	Int	Não	Número inicial para a sequência
`currencyFieldId`	String	Não	Campo de moeda de referência para CURRENCY_CONVERSION
`conversionDate`	String	Não	Data de conversão para CURRENCY_CONVERSION
`conversionDateType`	String	Não	Tipo de data de conversão para CURRENCY_CONVERSION
`metadata`	JSON	Não	Metadados adicionais para o campo personalizado

Valores de CustomFieldType

Valor	Descrição	Parâmetros Necessários
`TEXT_SINGLE`	Entrada de texto de linha única	Nenhum
`TEXT_MULTI`	Área de texto de várias linhas	Nenhum
`SELECT_SINGLE`	Dropdown de seleção única	Create options separately
`SELECT_MULTI`	Dropdown de múltipla seleção	Create options separately
`CHECKBOX`	Caixa de seleção booleana	Nenhum
`RATING`	Campo de classificação por estrelas	Optional: `max` (default: 5)
`PHONE`	Número de telefone com validação	Nenhum
`NUMBER`	Entrada numérica	Optional: `min`, `max`
`CURRENCY`	Montante em moeda	Optional: `currency`, `min`, `max`
`PERCENT`	Porcentagem (0-100)	Optional: `min`, `max`
`EMAIL`	Email com validação	Nenhum
`URL`	URL da web com validação	Nenhum
`UNIQUE_ID`	Identificador gerado automaticamente	Optional: `prefix`, `useSequenceUniqueId`
`LOCATION`	Coordenadas geográficas	Nenhum
`FILE`	Anexo de arquivo	Nenhum
`DATE`	Seletor de data	Optional: `isDueDate`
`COUNTRY`	Seletor de país	Nenhum
`FORMULA`	Campo calculado	Required: `formula`
`REFERENCE`	Link para outros registros	Required: `referenceProjectId`
`LOOKUP`	Puxar dados de referências	Required: `lookupOption`
`TIME_DURATION`	Rastreamento de tempo	Required: duration inputs (see below)
`BUTTON`	Botão de ação	Optional: `buttonType`, `buttonConfirmText`
`CURRENCY_CONVERSION`	Conversor de moeda	Special configuration

Exemplos de Configuração de Tipo de Campo

Campo Numérico com Restrições

mutation CreateQuantityField {
  createCustomField(input: {
    name: "Quantity"
    type: NUMBER
    description: "Number of items"
    min: 1
    max: 999
  }) {
    id
    name
    min
    max
  }
}

Campo de Moeda

mutation CreateBudgetField {
  createCustomField(input: {
    name: "Budget"
    type: CURRENCY
    currency: "EUR"
    min: 0
  }) {
    id
    name
    currency
    min
  }
}

Campo de Data com Sinal de Data de Vencimento

mutation CreateDeadlineField {
  createCustomField(input: {
    name: "Project Deadline"
    type: DATE
    isDueDate: true
    description: "When this project must be completed"
  }) {
    id
    name
    isDueDate
  }
}

Campo de Referência

mutation CreateRelatedTasksField {
  createCustomField(input: {
    name: "Dependencies"
    type: REFERENCE
    referenceProjectId: "proj_abc123"
    referenceMultiple: true
    referenceFilter: {
      statusIds: ["status_open", "status_inprogress"]
    }
  }) {
    id
    name
    referenceProjectId
    referenceMultiple
  }
}

Campo de Lookup

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 Único com Sequência

mutation CreateOrderNumberField {
  createCustomField(input: {
    name: "Order Number"
    type: UNIQUE_ID
    prefix: "ORD-"
    useSequenceUniqueId: true
    sequenceDigits: 6
    sequenceStartingNumber: 1000
  }) {
    id
    name
    prefix
  }
}

Campo de Duração de Tempo

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

Tipos Válidos de Duração de Tempo

TODO_CREATED_AT - Quando o registro foi criado
TODO_CUSTOM_FIELD - Quando um campo personalizado muda
TODO_DUE_DATE - Quando a data de vencimento é definida/mudada
TODO_MARKED_AS_COMPLETE - Quando o registro é marcado como completo
TODO_MOVED - Quando o registro é movido para uma lista diferente
TODO_TAG_ADDED - Quando uma tag é adicionada
TODO_ASSIGNEE_ADDED - Quando um responsável é adicionado

Criando Opções de Seleção

Após criar um campo SELECT_SINGLE ou SELECT_MULTI, adicione opções:

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

Campos de Resposta

CustomField

Campo	Tipo	Descrição
`id`	String!	Identificador único
`uid`	String!	ID único amigável ao usuário
`name`	String!	Nome exibido
`type`	CustomFieldType!	Tipo de campo
`description`	String	Descrição do campo
`position`	Float!	Posição da ordem de exibição
`createdAt`	DateTime!	Timestamp de criação
`updatedAt`	DateTime!	Timestamp da última atualização
`min`	Float	Valor mínimo (se aplicável)
`max`	Float	Valor máximo (se aplicável)
`currency`	String	Código da moeda (tipo CURRENCY)
`prefix`	String	Prefixo de ID (tipo UNIQUE_ID)
`isDueDate`	Boolean	Sinal de data de vencimento (tipo DATE)
`formula`	JSON	Configuração de fórmula (tipo FORMULA)
`referenceProjectId`	String	Projeto referenciado (tipo REFERENCE)
`customFieldLookupOption`	CustomFieldLookupOption	Configuração de lookup (tipo LOOKUP)

Permissões Necessárias

Criar campos personalizados requer acesso ao projeto:

Função	Pode Criar Campos Personalizados
`OWNER`	✅ Sim
`ADMIN`	✅ Sim
`MEMBER`	✅ Sim
`CLIENT`	❌ Não

Nota: Funções personalizadas podem ter restrições adicionais na gestão de campos.

Respostas de Erro

Tipo de Campo Inválido

{
  "errors": [{
    "message": "Variable \"$input\" got invalid value \"INVALID\" at \"input.type\"; Value \"INVALID\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

Projeto de Referência Não Encontrado

{
  "errors": [{
    "message": "Reference project not found or access denied",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Configuração Necessária Ausente

{
  "errors": [{
    "message": "REFERENCE fields require referenceProjectId",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Notas Importantes

Posição do Campo: Calculada automaticamente para aparecer no final dos campos existentes
Limites de Campo: Projetos podem ter limites no número de campos personalizados
Disponibilidade Imediata: Campos criados estão imediatamente disponíveis para uso
Efeitos Colaterais: Criar um campo aciona:
- Entrada no log de atividades
- Atualizações em tempo real para usuários conectados
- Notificações de webhook
- Tarefas em segundo plano para campos FORMULA, LOOKUP e UNIQUE_ID
Considerações Especiais:
- Campos REFERENCE requerem acesso ao projeto de destino
- Campos LOOKUP dependem de campos REFERENCE existentes
- Campos FORMULA não podem referenciar a si mesmos
- Sequências UNIQUE_ID processam de forma assíncrona
- Campos SELECT precisam de opções criadas separadamente
Nomeação: Nomes de campos devem ser claros e descritivos como aparecem na interface do usuário

Endpoints Relacionados

Listar Campos Personalizados - Visualizar campos personalizados existentes
Atualizar Campo Personalizado - Modificar propriedades do campo
Excluir Campo Personalizado - Remover um campo personalizado
Criar Opções de Campo - Adicionar opções a campos de seleção
Definir Valores de Campo Personalizado - Definir valores em registros