Elenco Registrazioni

Interroga e filtra registrazioni (todo) in Blue con potenti opzioni di ricerca e paginazione.

Elenco Registrazioni

La query dei todo consente di recuperare registrazioni da Blue con opzioni complete di filtraggio, ordinamento e paginazione. Puoi interrogare registrazioni attraverso aziende, progetti o filtrare per criteri specifici come assegnatari, tag e date.

Esempio Base

Elenca tutte le registrazioni in un'azienda con parametri minimi:

query ListRecords {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
      }
    ) {
      items {
        id
        title
        done
        duedAt
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Esempio Avanzato

Interroga registrazioni con filtraggio, ordinamento e selezione dei campi completi:

query ListRecordsAdvanced {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_456", "project_789"]
        assigneeIds: ["user_123"]
        tagIds: ["tag_priority", "tag_urgent"]
        showCompleted: false
        dueStart: "2025-01-01T00:00:00Z"
        dueEnd: "2025-12-31T23:59:59Z"
        search: "product launch"
        excludeArchivedProjects: true
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "cf_status_123"
            customFieldType: "SELECT_SINGLE"
            values: ["In Progress", "Review"]
            op: "IN"
          }
        ]
        op: "AND"
      }
      sort: [duedAt_ASC, position_ASC]
      limit: 50
      skip: 0
    ) {
      items {
        id
        uid
        position
        title
        text
        html
        startedAt
        duedAt
        timezone
        color
        cover
        done
        archived
        createdAt
        updatedAt
        commentCount
        checklistCount
        checklistCompletedCount
        isRepeating
        todoList {
          id
          title
        }
        users {
          id
          name
          email
        }
        tags {
          id
          title
          color
        }
        customFields {
          id
          title
          type
          value
        }
        createdBy {
          id
          name
        }
      }
      pageInfo {
        totalPages
        totalItems
        page
        perPage
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Parametri di Input

TodosFilter

Parametro	Tipo	Richiesto	Descrizione
`companyIds`	[String!]!	✅ Sì	ID aziendali o slug da interrogare
`projectIds`	[String!]	No	Filtra per ID di progetto specifici o slug
`todoIds`	[String!]	No	Recupera specifici todo per i loro ID
`assigneeIds`	[String!]	No	Filtra per ID utente assegnati
`tagIds`	[String!]	No	Filtra per ID di tag
`tagColors`	[String!]	No	Filtra per colori dei tag (formato esadecimale)
`tagTitles`	[String!]	No	Filtra per titoli dei tag
`todoListIds`	[String!]	No	Filtra per ID di liste todo
`todoListTitles`	[String!]	No	Filtra per titoli di liste todo
`done`	Boolean	No	Filtra per stato di completamento (deprecato, usa showCompleted)
`showCompleted`	Boolean	No	Mostra/nascondi todo completati (predefinito: true)
`startedAt`	DateTime	No	Filtra per data di inizio
`duedAt`	DateTime	No	Filtra per data di scadenza esatta
`dueStart`	DateTime	No	Inizio intervallo data di scadenza (inclusivo)
`dueEnd`	DateTime	No	Fine intervallo data di scadenza (inclusivo)
`search`	String	No	Cerca nel titolo e nel contenuto testuale
`q`	String	No	Parametro di ricerca alternativo (stesso di search)
`excludeArchivedProjects`	Boolean	No	Escludi todo da progetti archiviati
`coordinates`	JSON	No	Filtro geo-spaziale per vista mappa (coordinate poligonali)
`fields`	JSON	No	Filtri per campi personalizzati (vedi filtraggio avanzato)
`op`	FilterLogicalOperator	No	Operatore logico per filtri di campo (AND/OR)

Parametri di Query

Parametro	Tipo	Richiesto	Descrizione
`filter`	TodosFilter!	✅ Sì	Criteri di filtraggio per la query
`sort`	[TodosSort!]	No	Ordine di ordinamento (predefinito: array vuoto)
`limit`	Int	No	Numero di elementi per pagina (predefinito: 20, max: 500)
`skip`	Int	No	Numero di elementi da saltare per la paginazione (predefinito: 0)

Valori di TodosSort

Valore	Descrizione
`assignees_ASC`	Ordina per nomi degli assegnatari in ordine crescente
`assignees_DESC`	Ordina per nomi degli assegnatari in ordine decrescente
`createdAt_ASC`	Ordina per data di creazione in ordine crescente (più vecchi per primi)
`createdAt_DESC`	Ordina per data di creazione in ordine decrescente (più recenti per primi)
`createdBy_ASC`	Ordina per nome del creatore in ordine crescente
`createdBy_DESC`	Ordina per nome del creatore in ordine decrescente
`duedAt_ASC`	Ordina per data di scadenza in ordine crescente (più vicina per prima)
`duedAt_DESC`	Ordina per data di scadenza in ordine decrescente (più lontana per prima)
`position_ASC`	Ordina per posizione in ordine crescente (ordine predefinito della lista)
`position_DESC`	Ordina per posizione in ordine decrescente
`startedAt_ASC`	Ordina per data di inizio in ordine crescente
`startedAt_DESC`	Ordina per data di inizio in ordine decrescente
`title_ASC`	Ordina per titolo in ordine alfabetico crescente
`title_DESC`	Ordina per titolo in ordine alfabetico decrescente
`todoListPosition_ASC`	Ordina per posizione della lista todo in ordine crescente
`todoListPosition_DESC`	Ordina per posizione della lista todo in ordine decrescente
`todoListTitle_ASC`	Ordina per titolo della lista todo in ordine crescente
`todoListTitle_DESC`	Ordina per titolo della lista todo in ordine decrescente
`todoTags_ASC`	Ordina per tag in ordine crescente
`todoTags_DESC`	Ordina per tag in ordine decrescente

Valori di FilterLogicalOperator

Valore	Descrizione
`AND`	Tutte le condizioni devono corrispondere
`OR`	Qualsiasi condizione deve corrispondere

Filtraggio dei Campi Personalizzati

Il parametro fields supporta il filtraggio avanzato per campi personalizzati:

{
  "fields": [
    {
      "type": "CUSTOM_FIELD",
      "customFieldId": "cf_123",
      "customFieldType": "SELECT_SINGLE",
      "values": ["Option1", "Option2"],
      "op": "IN"
    }
  ]
}

Struttura del Filtro per Campi Personalizzati

Campo	Tipo	Descrizione
`type`	String	Deve essere "CUSTOM_FIELD"
`customFieldId`	String	ID del campo personalizzato
`customFieldType`	String	Tipo del campo personalizzato
`values`	[String!]	Valori da filtrare
`op`	String	Operatore di confronto (IN, NOT_IN, EQ, ecc.)

Tipi di Campo Personalizzati Supportati

Campi di testo: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
Campi numerici: CURRENCY, NUMBER, FORMULA
Campi di selezione: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
Campi di riferimento: REFERENCE, LOOKUP
Campi di data: DATE

Campi di Risposta

TodosResult

Campo	Tipo	Descrizione
`items`	[Todo!]!	Array di registrazioni todo
`pageInfo`	PageInfo!	Metadati di paginazione

PageInfo

Campo	Tipo	Descrizione
`totalPages`	Int	Numero totale di pagine disponibili
`totalItems`	Int	Numero totale di elementi in tutte le pagine
`page`	Int	Numero della pagina corrente (calcolato da skip/limit)
`perPage`	Int	Numero di elementi per pagina
`hasNextPage`	Boolean!	Se c'è una pagina successiva
`hasPreviousPage`	Boolean!	Se c'è una pagina precedente

Campi Todo

Campo	Tipo	Descrizione
`id`	ID!	Identificatore unico
`uid`	String!	Identificatore unico a misura d'utente
`position`	Float!	Posizione nella lista
`title`	String!	Titolo del todo
`text`	String!	Contenuto in testo semplice
`html`	String!	Contenuto formattato in HTML
`startedAt`	DateTime	Data/ora di inizio
`duedAt`	DateTime	Data/ora di scadenza
`timezone`	String	Fuso orario per le date
`color`	String	Indicatore di colore visivo
`cover`	String	URL dell'immagine di copertura
`done`	Boolean!	Stato di completamento
`archived`	Boolean!	Stato di archiviazione
`createdAt`	DateTime!	Timestamp di creazione
`updatedAt`	DateTime!	Timestamp dell'ultima modifica
`commentCount`	Int!	Numero di commenti
`checklistCount`	Int!	Totale degli elementi della checklist
`checklistCompletedCount`	Int!	Elementi della checklist completati
`isRepeating`	Boolean!	Se il todo è ricorrente
`isRead`	Boolean	Stato di lettura per l'utente corrente
`isSeen`	Boolean	Stato di visione per l'utente corrente
`todoList`	TodoList!	Lista todo genitore
`users`	[User!]!	Utenti assegnati
`tags`	[Tag!]!	Tag associati
`checklists`	[Checklist!]!	Checklist associate
`createdBy`	User	Utente che ha creato il todo
`customFields`	[CustomField!]!	Valori dei campi personalizzati
`dependOn`	[Todo!]	Todo bloccanti (dipendenze)
`dependBy`	[Todo!]	Todo dipendenti (bloccati da questo)
`timeTracking`	TimeTracking	Dati di tracciamento del tempo

Permessi Richiesti

Gli utenti devono avere accesso appropriato per interrogare le registrazioni:

Tipo di Accesso	Requisiti
Company Access	User must be a member of the company
Project Access	User must have access to specific projects (if filtering by project)
Todo Visibility	Depends on user's role and permissions:
- `VIEW_ONLY`	Can view all accessible todos
- `COMMENT_ONLY`	Can view all accessible todos
- `CLIENT`	May be restricted to assigned todos only
- `MEMBER`	Can view all project todos
- `ADMIN`	Can view all project todos
- `OWNER`	Can view all company todos

Restrizioni Speciali:

Gli utenti con permesso showOnlyAssignedTodos possono vedere solo i todo a loro assegnati
Le liste todo nascoste (basate sulla configurazione del ruolo) sono automaticamente escluse
I permessi basati su tag possono ulteriormente filtrare i risultati

Risposte di Errore

Errori Comuni

La query gestisce gli errori in modo elegante e restituisce risultati vuoti per:

ID aziendali non validi
Progetti inaccessibili
Scenari di permesso negato

Per errori gravi, potrebbero essere restituiti errori GraphQL:

{
  "errors": [{
    "message": "Query timeout exceeded",
    "extensions": {
      "code": "QUERY_TIMEOUT"
    }
  }]
}

Note Importanti

Prestazioni

Limite predefinito: 20 elementi per pagina (applicato automaticamente se non specificato)
Limite massimo: 500 elementi per richiesta (automaticamente limitato)
Ottimizzazione: Le query utilizzano join ottimizzati con STRAIGHT_JOIN per le migliori prestazioni
Indicizzazione: I campi di filtro comuni sono indicizzati per query rapide
Campi personalizzati: Supporto esteso per il filtraggio dei campi personalizzati con impatto minimo sulle prestazioni
Query geografiche: Supporta il filtraggio delle coordinate basato su poligoni per le viste mappa

Filtraggio delle Date

Gli intervalli di date sono inclusivi
Supporta intervalli di date sovrapposti (todo che iniziano o finiscono nell'intervallo)
Le date nulle sono gestite in modo elegante (i todo senza date di scadenza non corrisponderanno ai filtri di data)
Tutte le date devono essere nel formato ISO 8601

Comportamento di Ricerca

La ricerca è insensibile al maiuscolo/minuscolo
Cerca sia nel titolo che nel contenuto testuale
Il matching parziale delle parole è supportato
I caratteri speciali sono gestiti in modo appropriato

Strategia di Paginazione

Usa skip e limit per la paginazione basata su offset
Calcola la pagina corrente: page = Math.floor(skip / limit) + 1
Per dataset di grandi dimensioni, considera di utilizzare filtri per ridurre la dimensione dei risultati
Controlla sempre hasNextPage prima di incrementare lo skip

Endpoint Correlati

Crea Registrazione: Usa la mutazione createTodo per creare nuove registrazioni
Aggiorna Registrazione: Usa la mutazione updateTodo per modificare registrazioni
Elimina Registrazione: Usa la mutazione deleteTodo per rimuovere registrazioni
Elenca Campi Personalizzati: Interroga i campi personalizzati disponibili per il filtraggio
Elenca Progetti: Interroga i progetti disponibili per il filtraggio