Crear un Campo Personalizado

Agrega nuevos campos personalizados para extender la estructura de datos de tu proyecto con configuraciones específicas de tipo

Crear un Campo Personalizado

Los campos personalizados te permiten adaptar Blue a las necesidades específicas de tu negocio al agregar campos de datos estructurados a tus registros. Este endpoint crea un nuevo campo personalizado con configuraciones específicas para cada tipo de campo.

Ejemplo Básico

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

Ejemplo Avanzado

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	Requerido	Descripción
`name`	String!	✅ Sí	El nombre para mostrar del campo personalizado
`type`	CustomFieldType!	✅ Sí	El tipo de campo (ver tipos a continuación)
`description`	String	No	Descripción opcional que explica el propósito del campo
`min`	Float	No	Valor mínimo para campos de NÚMERO, CALIFICACIÓN, PORCENTAJE
`max`	Float	No	Valor máximo para campos de NÚMERO, CALIFICACIÓN, PORCENTAJE
`currency`	String	No	Código de moneda ISO para campos de MONEDA
`prefix`	String	No	Prefijo de texto para campos de ID_UNICO
`isDueDate`	Boolean	No	Si el campo de FECHA representa una fecha de vencimiento
`formula`	JSON	No	Configuración de fórmula para campos de FÓRMULA
`referenceProjectId`	String	No	ID del proyecto objetivo para campos de REFERENCIA
`referenceMultiple`	Boolean	No	Permitir múltiples selecciones en campos de REFERENCIA
`referenceFilter`	TodoFilterInput	No	Opciones de filtro para campos de REFERENCIA
`lookupOption`	CustomFieldLookupOptionInput	No	Configuración para campos de BÚSQUEDA
`timeDurationDisplay`	CustomFieldTimeDurationDisplayType	No	Formato de visualización para DURACIÓN_DE_TIEMPO
`timeDurationTargetTime`	Float	No	Tiempo objetivo en segundos para DURACIÓN_DE_TIEMPO
`timeDurationStartInput`	CustomFieldTimeDurationInput	No	Disparador de inicio para DURACIÓN_DE_TIEMPO
`timeDurationEndInput`	CustomFieldTimeDurationInput	No	Disparador de fin para DURACIÓN_DE_TIEMPO
`buttonType`	String	No	Tipo de acción del botón para campos de BOTÓN
`buttonConfirmText`	String	No	Mensaje de confirmación para campos de BOTÓN
`useSequenceUniqueId`	Boolean	No	Usar numeración secuencial para ID_UNICO
`sequenceDigits`	Int	No	Número de dígitos en la secuencia (por ejemplo, 5 → 00001)
`sequenceStartingNumber`	Int	No	Número inicial para la secuencia
`currencyFieldId`	String	No	Campo de referencia de moneda para CONVERSIÓN_DE_MONEDA
`conversionDate`	String	No	Fecha de conversión para CONVERSIÓN_DE_MONEDA
`conversionDateType`	String	No	Tipo de fecha de conversión para CONVERSIÓN_DE_MONEDA
`metadata`	JSON	No	Metadatos adicionales para el campo personalizado

Valores de CustomFieldType

Valor	Descripción	Parámetros Requeridos
`TEXT_SINGLE`	Entrada de texto de una sola línea	Ninguno
`TEXT_MULTI`	Área de texto de varias líneas	Ninguno
`SELECT_SINGLE`	Desplegable de selección única	Create options separately
`SELECT_MULTI`	Desplegable de selección múltiple	Create options separately
`CHECKBOX`	Casilla de verificación booleana	Ninguno
`RATING`	Campo de calificación por estrellas	Optional: `max` (default: 5)
`PHONE`	Número de teléfono con validación	Ninguno
`NUMBER`	Entrada numérica	Optional: `min`, `max`
`CURRENCY`	Monto en moneda	Optional: `currency`, `min`, `max`
`PERCENT`	Porcentaje (0-100)	Optional: `min`, `max`
`EMAIL`	Correo electrónico con validación	Ninguno
`URL`	URL web con validación	Ninguno
`UNIQUE_ID`	Identificador autogenerado	Optional: `prefix`, `useSequenceUniqueId`
`LOCATION`	Coordenadas geográficas	Ninguno
`FILE`	Archivo adjunto	Ninguno
`DATE`	Selector de fecha	Optional: `isDueDate`
`COUNTRY`	Selector de país	Ninguno
`FORMULA`	Campo calculado	Required: `formula`
`REFERENCE`	Enlace a otros registros	Required: `referenceProjectId`
`LOOKUP`	Extraer datos de referencias	Required: `lookupOption`
`TIME_DURATION`	Seguimiento de tiempo	Required: duration inputs (see below)
`BUTTON`	Botón de acción	Optional: `buttonType`, `buttonConfirmText`
`CURRENCY_CONVERSION`	Conversor de moneda	Special configuration

Ejemplos de Configuración de Tipo de Campo

Campo Numérico con Restricciones

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

Campo de Moneda

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

Campo de Fecha con Indicador de Fecha de Vencimiento

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

Campo de Referencia

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 Búsqueda

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 con Secuencia

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

Campo de Duración de Tiempo

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 de Duración de Tiempo Válidos

TODO_CREATED_AT - Cuando se creó el registro
TODO_CUSTOM_FIELD - Cuando cambia un campo personalizado
TODO_DUE_DATE - Cuando se establece/cambia la fecha de vencimiento
TODO_MARKED_AS_COMPLETE - Cuando el registro se marca como completo
TODO_MOVED - Cuando el registro se mueve a una lista diferente
TODO_TAG_ADDED - Cuando se agrega una etiqueta
TODO_ASSIGNEE_ADDED - Cuando se agrega un asignado

Creando Opciones de Selección

Después de crear un campo SELECT_SINGLE o SELECT_MULTI, agrega opciones:

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 Respuesta

CustomField

Campo	Tipo	Descripción
`id`	String!	Identificador único
`uid`	String!	ID único amigable
`name`	String!	Nombre para mostrar
`type`	CustomFieldType!	Tipo de campo
`description`	String	Descripción del campo
`position`	Float!	Posición del orden de visualización
`createdAt`	DateTime!	Marca de tiempo de creación
`updatedAt`	DateTime!	Marca de tiempo de última actualización
`min`	Float	Valor mínimo (si aplica)
`max`	Float	Valor máximo (si aplica)
`currency`	String	Código de moneda (tipo MONEDA)
`prefix`	String	Prefijo de ID (tipo ID_UNICO)
`isDueDate`	Boolean	Indicador de fecha de vencimiento (tipo FECHA)
`formula`	JSON	Configuración de fórmula (tipo FÓRMULA)
`referenceProjectId`	String	Proyecto referenciado (tipo REFERENCIA)
`customFieldLookupOption`	CustomFieldLookupOption	Configuración de búsqueda (tipo BÚSQUEDA)

Permisos Requeridos

Crear campos personalizados requiere acceso al proyecto:

Rol	Puede Crear Campos Personalizados
`OWNER`	✅ Sí
`ADMIN`	✅ Sí
`MEMBER`	✅ Sí
`CLIENT`	❌ No

Nota: Los roles personalizados pueden tener restricciones adicionales sobre la gestión de campos.

Respuestas de Error

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

Proyecto de Referencia No Encontrado

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

Configuración Requerida Faltante

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

Notas Importantes

Posición del Campo: Calculada automáticamente para aparecer al final de los campos existentes
Límites de Campo: Los proyectos pueden tener límites en el número de campos personalizados
Disponibilidad Inmediata: Los campos creados están disponibles inmediatamente para su uso
Efectos Secundarios: Crear un campo desencadena:
- Entrada en el registro de actividad
- Actualizaciones en tiempo real para usuarios conectados
- Notificaciones de webhook
- Trabajos en segundo plano para campos de FÓRMULA, BÚSQUEDA y ID_UNICO
Consideraciones Especiales:
- Los campos de REFERENCIA requieren acceso al proyecto objetivo
- Los campos de BÚSQUEDA dependen de campos de REFERENCIA existentes
- Los campos de FÓRMULA no pueden hacer referencia a sí mismos
- Las secuencias de ID_UNICO se procesan de forma asíncrona
- Los campos de SELECCIÓN necesitan opciones creadas por separado
Nomenclatura: Los nombres de los campos deben ser claros y descriptivos, tal como aparecen en la interfaz de usuario

Endpoints Relacionados

Listar Campos Personalizados - Ver campos personalizados existentes
Actualizar Campo Personalizado - Modificar propiedades del campo
Eliminar Campo Personalizado - Eliminar un campo personalizado
Crear Opciones de Campo - Agregar opciones a campos de selección
Establecer Valores de Campo Personalizado - Establecer valores en registros