Crea un Campo Personalizzato

Aggiungi nuovi campi personalizzati per estendere la struttura dei dati del tuo progetto con configurazioni specifiche per tipo

Crea un Campo Personalizzato

I campi personalizzati ti consentono di adattare Blue alle tue specifiche esigenze aziendali aggiungendo campi di dati strutturati ai tuoi record. Questo endpoint crea un nuovo campo personalizzato con configurazioni specifiche per ciascun tipo di campo.

Esempio Base

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

Esempio Avanzato

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

Parametri di Input

CreateCustomFieldInput

Parametro	Tipo	Richiesto	Descrizione
`name`	String!	✅ Sì	Il nome visualizzato del campo personalizzato
`type`	CustomFieldType!	✅ Sì	Il tipo di campo (vedi tipi di seguito)
`description`	String	No	Descrizione facoltativa che spiega lo scopo del campo
`min`	Float	No	Valore minimo per i campi NUMBER, RATING, PERCENT
`max`	Float	No	Valore massimo per i campi NUMBER, RATING, PERCENT
`currency`	String	No	Codice valuta ISO per i campi CURRENCY
`prefix`	String	No	Prefisso di testo per i campi UNIQUE_ID
`isDueDate`	Boolean	No	Se il campo DATE rappresenta una data di scadenza
`formula`	JSON	No	Configurazione della formula per i campi FORMULA
`referenceProjectId`	String	No	ID del progetto di destinazione per i campi REFERENCE
`referenceMultiple`	Boolean	No	Consenti selezioni multiple nei campi REFERENCE
`referenceFilter`	TodoFilterInput	No	Opzioni di filtro per i campi REFERENCE
`lookupOption`	CustomFieldLookupOptionInput	No	Configurazione per i campi LOOKUP
`timeDurationDisplay`	CustomFieldTimeDurationDisplayType	No	Formato di visualizzazione per TIME_DURATION
`timeDurationTargetTime`	Float	No	Tempo di destinazione in secondi per TIME_DURATION
`timeDurationStartInput`	CustomFieldTimeDurationInput	No	Trigger di inizio per TIME_DURATION
`timeDurationEndInput`	CustomFieldTimeDurationInput	No	Trigger di fine per TIME_DURATION
`buttonType`	String	No	Tipo di azione del pulsante per i campi BUTTON
`buttonConfirmText`	String	No	Messaggio di conferma per i campi BUTTON
`useSequenceUniqueId`	Boolean	No	Utilizza numerazione sequenziale per UNIQUE_ID
`sequenceDigits`	Int	No	Numero di cifre nella sequenza (es. 5 → 00001)
`sequenceStartingNumber`	Int	No	Numero iniziale per la sequenza
`currencyFieldId`	String	No	Campo di valuta di riferimento per CURRENCY_CONVERSION
`conversionDate`	String	No	Data di conversione per CURRENCY_CONVERSION
`conversionDateType`	String	No	Tipo di data di conversione per CURRENCY_CONVERSION
`metadata`	JSON	No	Metadati aggiuntivi per il campo personalizzato

Valori di CustomFieldType

Valore	Descrizione	Parametri Richiesti
`TEXT_SINGLE`	Input di testo a riga singola	Nessuno
`TEXT_MULTI`	Area di testo a più righe	Nessuno
`SELECT_SINGLE`	Dropdown a selezione singola	Create options separately
`SELECT_MULTI`	Dropdown a selezione multipla	Create options separately
`CHECKBOX`	Checkbox booleano	Nessuno
`RATING`	Campo di valutazione a stelle	Optional: `max` (default: 5)
`PHONE`	Numero di telefono con validazione	Nessuno
`NUMBER`	Input numerico	Optional: `min`, `max`
`CURRENCY`	Importo in valuta	Optional: `currency`, `min`, `max`
`PERCENT`	Percentuale (0-100)	Optional: `min`, `max`
`EMAIL`	Email con validazione	Nessuno
`URL`	URL web con validazione	Nessuno
`UNIQUE_ID`	Identificatore generato automaticamente	Optional: `prefix`, `useSequenceUniqueId`
`LOCATION`	Coordinate geografiche	Nessuno
`FILE`	Allegato di file	Nessuno
`DATE`	Selettore di data	Optional: `isDueDate`
`COUNTRY`	Selettore di paese	Nessuno
`FORMULA`	Campo calcolato	Required: `formula`
`REFERENCE`	Link ad altri record	Required: `referenceProjectId`
`LOOKUP`	Estrai dati da riferimenti	Required: `lookupOption`
`TIME_DURATION`	Tracciamento del tempo	Required: duration inputs (see below)
`BUTTON`	Pulsante di azione	Optional: `buttonType`, `buttonConfirmText`
`CURRENCY_CONVERSION`	Convertitore di valuta	Special configuration

Esempi di Configurazione del Tipo di Campo

Campo Numero con Vincoli

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

Campo Valuta

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

Campo Data con Flag di Scadenza

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

Campo Riferimento

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

Campo 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 Unico con Sequenza

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

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

Tipi di Durata Tempo Validi

TODO_CREATED_AT - Quando il record è stato creato
TODO_CUSTOM_FIELD - Quando un campo personalizzato cambia
TODO_DUE_DATE - Quando la data di scadenza è impostata/cambiata
TODO_MARKED_AS_COMPLETE - Quando il record è contrassegnato come completo
TODO_MOVED - Quando il record viene spostato in un'altra lista
TODO_TAG_ADDED - Quando viene aggiunta un'etichetta
TODO_ASSIGNEE_ADDED - Quando viene aggiunto un assegnatario

Creazione di Opzioni di Selezione

Dopo aver creato un campo SELECT_SINGLE o SELECT_MULTI, aggiungi opzioni:

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

Campi di Risposta

CustomField

Campo	Tipo	Descrizione
`id`	String!	Identificatore unico
`uid`	String!	ID unico a misura d'utente
`name`	String!	Nome visualizzato
`type`	CustomFieldType!	Tipo di campo
`description`	String	Descrizione del campo
`position`	Float!	Posizione dell'ordine di visualizzazione
`createdAt`	DateTime!	Timestamp di creazione
`updatedAt`	DateTime!	Timestamp dell'ultimo aggiornamento
`min`	Float	Valore minimo (se applicabile)
`max`	Float	Valore massimo (se applicabile)
`currency`	String	Codice valuta (tipo CURRENCY)
`prefix`	String	Prefisso ID (tipo UNIQUE_ID)
`isDueDate`	Boolean	Flag di data di scadenza (tipo DATE)
`formula`	JSON	Configurazione della formula (tipo FORMULA)
`referenceProjectId`	String	Progetto di riferimento (tipo REFERENCE)
`customFieldLookupOption`	CustomFieldLookupOption	Configurazione di lookup (tipo LOOKUP)

Permessi Richiesti

La creazione di campi personalizzati richiede accesso al progetto:

Ruolo	Può Creare Campi Personalizzati
`OWNER`	✅ Sì
`ADMIN`	✅ Sì
`MEMBER`	✅ Sì
`CLIENT`	❌ No

Nota: I ruoli personalizzati possono avere restrizioni aggiuntive sulla gestione dei campi.

Risposte di Errore

Tipo di Campo Non Valido

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

Progetto di Riferimento Non Trovato

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

Configurazione Richiesta Mancante

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

Note Importanti

Posizione del Campo: Calcolata automaticamente per apparire alla fine dei campi esistenti
Limiti dei Campi: I progetti possono avere limiti sul numero di campi personalizzati
Disponibilità Immediata: I campi creati sono immediatamente disponibili per l'uso
Effetti Collaterali: La creazione di un campo attiva:
- Voce nel registro delle attività
- Aggiornamenti in tempo reale agli utenti connessi
- Notifiche webhook
- Lavori in background per i campi FORMULA, LOOKUP e UNIQUE_ID
Considerazioni Speciali:
- I campi REFERENCE richiedono accesso al progetto di destinazione
- I campi LOOKUP dipendono dai campi REFERENCE esistenti
- I campi FORMULA non possono fare riferimento a se stessi
- Le sequenze UNIQUE_ID vengono elaborate in modo asincrono
- I campi SELECT necessitano di opzioni create separatamente
Nomenclatura: I nomi dei campi devono essere chiari e descrittivi come appaiono nell'interfaccia utente

Endpoint Correlati

Elenca Campi Personalizzati - Visualizza i campi personalizzati esistenti
Aggiorna Campo Personalizzato - Modifica le proprietà del campo
Elimina Campo Personalizzato - Rimuovi un campo personalizzato
Crea Opzioni di Campo - Aggiungi opzioni ai campi di selezione
Imposta Valori di Campo Personalizzato - Imposta valori sui record