Elenca tutti i campi personalizzati

Recupera un elenco paginato di campi personalizzati per un progetto o tra più progetti con opzioni di filtraggio e ordinamento

Elenca tutti i campi personalizzati

I campi personalizzati ti consentono di estendere la struttura standard dei record di Blue con campi dati aggiuntivi specifici per le esigenze della tua azienda. Questo endpoint recupera i campi personalizzati disponibili nei tuoi progetti, con filtraggio per tipo di campo e supporto per la paginazione.

Esempio di base

query ListCustomFields {
  customFields(
    filter: { projectId: "project_123" }
    sort: position_ASC
    take: 20
  ) {
    items {
      id
      uid
      name
      type
      position
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Esempio avanzato

query ListCustomFieldsAdvanced {
  customFields(
    filter: {
      projectId: "project_123"
      types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
    }
    sort: name_ASC
    skip: 20
    take: 50
  ) {
    items {
      id
      uid
      name
      type
      position
      description
      
      # Type-specific fields
      min              # For NUMBER, RATING, PERCENT
      max              # For NUMBER, RATING, PERCENT
      currency         # For CURRENCY type
      prefix           # For UNIQUE_ID type
      isDueDate        # For DATE type
      formula          # For FORMULA type
      
      # Validation settings
      editable
      metadata
      
      # For SELECT types
      customFieldOptions {
        id
        title
        color
        position
      }
    }
    pageInfo {
      totalItems
      hasNextPage
      hasPreviousPage
    }
  }
}

Parametri di input

CustomFieldFilterInput

Parametro	Tipo	Richiesto	Descrizione
`projectId`	String	No	Filtra per ID progetto specifico
`types`	[CustomFieldType!]	No	Filtra per tipi di campo personalizzati

Valori di ordinamento CustomField

Valore	Descrizione
`name_ASC`	Ordina per nome crescente (A-Z)
`name_DESC`	Ordina per nome decrescente (Z-A)
`createdAt_ASC`	Ordina per data di creazione (più vecchio per primo)
`createdAt_DESC`	Ordina per data di creazione (più recente per primo)
`position_ASC`	Ordina per posizione (predefinito)
`position_DESC`	Ordina per posizione decrescente

Valori di tipo CustomField

Valore	Descrizione
`TEXT_SINGLE`	Input di testo su una sola riga
`TEXT_MULTI`	Area di testo su più righe
`SELECT_SINGLE`	Dropdown per selezione singola
`SELECT_MULTI`	Dropdown per selezione multipla
`CHECKBOX`	Campo checkbox booleano
`RATING`	Valutazione a stelle (1-5 o intervallo personalizzato)
`PHONE`	Numero di telefono con validazione
`NUMBER`	Input numerico
`CURRENCY`	Importo in valuta
`PERCENT`	Valore percentuale
`EMAIL`	Indirizzo email con validazione
`URL`	URL web con validazione
`UNIQUE_ID`	Identificatore unico generato automaticamente
`LOCATION`	Posizione geografica (lat/lng)
`FILE`	Allegato di file
`DATE`	Selettore di data
`COUNTRY`	Selettore di paese
`FORMULA`	Campo calcolato basato su altri campi
`REFERENCE`	Link a record in un altro progetto
`LOOKUP`	Estrai dati da record referenziati
`TIME_DURATION`	Campo di tracciamento del tempo
`BUTTON`	Campo pulsante azionabile
`CURRENCY_CONVERSION`	Campo di conversione valuta

Parametri di paginazione

Parametro	Tipo	Richiesto	Descrizione
`skip`	Int	No	Numero di elementi da saltare (predefinito: 0)
`take`	Int	No	Numero di elementi da restituire (predefinito: 20, max: 500)

Campi di risposta

CustomField

Campo	Tipo	Descrizione
`id`	String!	Identificatore unico
`uid`	String!	ID amichevole unico
`name`	String!	Nome visualizzato del campo
`type`	CustomFieldType!	Tipo di campo personalizzato
`position`	Float!	Posizione dell'ordine di ordinamento
`description`	String	Descrizione del campo opzionale
`min`	Float	Valore minimo (NUMERO, VALUTAZIONE, PERCENTUALE)
`max`	Float	Valore massimo (NUMERO, VALUTAZIONE, PERCENTUALE)
`currency`	String	Codice valuta (tipo VALUTA)
`prefix`	String	Prefisso per la generazione di UNIQUE_ID
`isDueDate`	Boolean	Se il campo DATA rappresenta una data di scadenza
`formula`	JSON	Configurazione della formula (tipo FORMULA)
`editable`	Boolean	Se l'utente corrente può modificare questo campo
`metadata`	JSON	Configurazione aggiuntiva del campo
`customFieldOptions`	[CustomFieldOption!]	Opzioni disponibili per i tipi SELECT

CustomFieldOption

Campo	Tipo	Descrizione
`id`	String!	Identificatore unico
`title`	String!	Testo visualizzato per l'opzione
`color`	String!	Codice colore esadecimale
`position`	Float!	Posizione dell'ordine di ordinamento

PageInfo

Campo	Tipo	Descrizione
`totalItems`	Int	Numero totale di campi personalizzati
`hasNextPage`	Boolean!	Se esistono altre pagine
`hasPreviousPage`	Boolean!	Se esistono pagine precedenti
`endCursor`	String	Cursore per la paginazione (deprecato - usa la paginazione basata su offset)

Permessi richiesti

I campi personalizzati sono accessibili in base al tuo ruolo nel progetto. Se hai un ruolo personalizzato con accesso ai campi limitato, verranno restituiti solo i campi contrassegnati come modificabili per il tuo ruolo.

Ruolo	Può elencare i campi personalizzati
`OWNER`	✅ Sì (tutti i campi)
`ADMIN`	✅ Sì (tutti i campi)
`MEMBER`	✅ Sì (in base ai permessi di ruolo)
`CLIENT`	✅ Sì (in base ai permessi di ruolo)

Risposte di errore

Progetto non trovato

{
  "errors": [{
    "message": "Project not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Tipo di campo non valido

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

Note importanti

I campi personalizzati sono limitati ai progetti - devi specificare un projectId nel filtro
Il parametro take è limitato a 500 elementi per richiesta per motivi di prestazioni
I campi vengono restituiti in base ai permessi dell'utente - i ruoli personalizzati possono avere accesso limitato
L'ordine di ordinamento predefinito è per position crescente, che riflette l'ordine mostrato nell'interfaccia utente
Questa query supporta il filtraggio di un singolo progetto - per query multi-progetto, utilizza l'interfaccia CustomFieldQueries annidata
Alcuni tipi di campo (come FORMULA e REFERENCE) possono includere strutture dati annidate aggiuntive
Il campo editable indica se l'utente corrente può modificare i valori per questo campo personalizzato

Endpoint correlati

Crea un campo personalizzato - Aggiungi nuovi campi personalizzati a un progetto
Aggiorna un campo personalizzato - Modifica le proprietà di un campo personalizzato esistente
Elimina un campo personalizzato - Rimuovi un campo personalizzato da un progetto
Imposta valore del campo personalizzato - Imposta valori sui record