---

Crea un Record

La mutazione createTodo consente di creare nuovi record in Blue con opzioni di configurazione complete, inclusi campi personalizzati, tag, assegnazioni e altro. I record possono essere creati in elenchi specifici o automaticamente collocati nell'elenco predefinito.

Esempio di Base

Crea un record semplice con solo un titolo:

mutation CreateRecord {
  createTodo(
    input: {
      title: "New Task"
    }
  ) {
    id
    title
    position
  }
}

Esempio Avanzato

Crea un record con tutte le opzioni disponibili:

mutation CreateRecordAdvanced {
  createTodo(
    input: {
      todoListId: "clm4n8qwx000008l0g4oxdqn7"
      title: "Product Launch Planning"
      placement: TOP
      description: "<p>Complete product launch preparation including marketing materials and documentation.</p>"
      startedAt: "2025-01-15T09:00:00Z"
      duedAt: "2025-02-01T17:00:00Z"
      notify: true
      assigneeIds: ["user_123", "user_456"]
      tags: [
        { id: "tag_existing_123" }
        { title: "Priority", color: "#ff4b4b" }
        { title: "Marketing" }
      ]
      customFields: [
        {
          customFieldId: "cf_budget_123"
          value: "50000 USD"
        }
        {
          customFieldId: "cf_status_456"
          value: "In Progress"
        }
      ]
      checklists: [
        {
          title: "Pre-launch Checklist"
          position: 1
        }
      ]
    }
  ) {
    id
    uid
    title
    position
    startedAt
    duedAt
    todoList {
      id
      title
    }
    users {
      id
      fullName
    }
    tags {
      id
      title
      color
    }
  }
}

Parametri di Input

CreateTodoInput

Parametro	Tipo	Richiesto	Descrizione
todoListId	String	No	ID dell'elenco todo a cui aggiungere il record. Se non fornito, utilizza il primo elenco todo nel progetto
title	String!	✅ Sì	Titolo del record (richiesto)
position	Float	No	Posizione personalizzata nell'elenco. Se non fornito, utilizza il parametro di posizionamento
placement	CreateTodoInputPlacement	No	Dove posizionare il record se la posizione non è specificata (IN ALTO o IN BASSO)
startedAt	DateTime	No	Data/ora di inizio per il record
duedAt	DateTime	No	Data/ora di scadenza per il record
notify	Boolean	No	Se inviare notifiche per la creazione di questo record
description	String	No	Contenuto della descrizione HTML (verrà sanificato)
assigneeIds	[String!]	No	Array di ID utente da assegnare a questo record
checklists	[CreateChecklistWithoutTodoInput!]	No	Array di checklist da creare con il record
customFields	[CreateTodoInputCustomField]	No	Array di valori dei campi personalizzati
tags	[CreateTodoTagInput!]	No	Array di tag da allegare al record

Valori di CreateTodoInputPlacement

Valore	Descrizione
TOP	Posizionare in cima all'elenco (posizione più alta)
BOTTOM	Posizionare in fondo all'elenco (posizione più bassa)

CreateTodoTagInput

Parametro	Tipo	Richiesto	Descrizione
id	String	No*	ID del tag esistente da collegare
title	String	No*	Titolo del tag (crea nuovo se non esiste)
color	String	No	Colore esadecimale per il nuovo tag (predefinito è #4a9fff)

*Nota: Devi fornire id (per tag esistente) O title (per creare/trovare per titolo)

CreateTodoInputCustomField

Parametro	Tipo	Richiesto	Descrizione
customFieldId	String	No	ID del campo personalizzato
value	String	No	Valore per il campo personalizzato (vedi guida al formato qui sotto)

CreateChecklistWithoutTodoInput

Parametro	Tipo	Richiesto	Descrizione
title	String!	✅ Sì	Titolo della checklist
position	Float	No	Posizione della checklist all'interno del record

Formati dei Valori dei Campi Personalizzati

Quando si impostano valori dei campi personalizzati, utilizzare questi formati in base al tipo di campo:

Tipo di Campo	Formato	Esempio
CHECKBOX	"true", "1", or "checked" for checked	"true"
COUNTRY	Country name or ISO code	"United States" or "US"
CURRENCY	Amount with optional currency	"50000 USD"
DATE	YYYY-MM-DD or date range	"2025-01-15" or "2025-01-15,2025-01-20"
NUMBER	Numeric value	"42"
PERCENT	Numeric value (% optional)	"75" or "75%"
RATING	Numeric value within range	"4" (if max is 5)
PHONE	International phone format	"+1234567890"
SELECT_SINGLE	Custom field option ID	"option_123"
SELECT_MULTI	Comma-separated option IDs	"option_1,option_2"
LOCATION	Latitude,longitude	"40.7128,-74.0060"
EMAIL	Valid email address	"user@example.com"
URL	Valid URL	"https://example.com"
TEXT	Plain text value	"Any text content"

Campi di Risposta

La mutazione restituisce un oggetto Todo con dettagli completi del record:

Campo	Tipo	Descrizione
id	String!	Identificatore unico per il record
uid	String!	Identificatore unico alternativo
title	String!	Titolo del record
position	Float!	Posizione nell'elenco
done	Boolean!	Stato di completamento
startedAt	DateTime	Data/ora di inizio
duedAt	DateTime	Data/ora di scadenza
todoList	TodoList	Dettagli dell'elenco todo associato
users	[User!]	Utenti assegnati
tags	[Tag!]	Tag associati
checklists	[Checklist!]	Checklist associate
customFields	[CustomFieldValue!]	Valori dei campi personalizzati

Permessi Richiesti

Gli utenti devono avere accesso appropriato al progetto per creare record:

Livello di Accesso	Può Creare Record
OWNER	✅ Sì
ADMIN	✅ Sì
MEMBER	✅ Sì
CLIENT	✅ Sì
COMMENT_ONLY	❌ No
VIEW_ONLY	❌ No

La mutazione richiede che il livello di accesso del progetto dell'utente sia OWNER, ADMIN, MEMBER, o CLIENT. Gli utenti con i ruoli VIEW_ONLY o COMMENT_ONLY non possono creare record.

Risposte di Errore

ProjectNotFoundError

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

Quando: Non è disponibile alcun contesto di progetto per l'utente.

TodoListCreateTodoLimitError

{
  "errors": [{
    "message": "Todo list has reached the maximum number of todos.",
    "extensions": {
      "code": "TODO_LIST_CREATE_TODO_LIMIT_ERROR"
    }
  }]
}

Quando: L'elenco todo contiene già 100.000 record (limite massimo).

TodoListNotFoundError

{
  "errors": [{
    "message": "Todo list was not found.",
    "extensions": {
      "code": "TODO_LIST_NOT_FOUND"
    }
  }]
}

Quando: L'todoListId specificato non esiste o l'utente non ha accesso.

CustomFieldValueParseError

{
  "errors": [{
    "message": "Invalid phone number format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Quando: Il valore del campo personalizzato non supera la validazione (ad esempio, telefono non valido, valutazione fuori intervallo).

Note Importanti

Prestazioni

• Ogni elenco todo può contenere fino a 100.000 record
• La creazione di record attiva più processi in background (webhook, automazioni, indicizzazione della ricerca)
• Le operazioni in batch sono più efficienti rispetto alla creazione di record uno alla volta

Logica Aziendale

• Gestione della Posizione: La posizione predefinita è 65535.0 quando né position né placement sono specificati
• Logica delle Date:
  • Se viene fornito solo duedAt, startedAt è impostato all'inizio di quel giorno
  • Se viene fornito solo startedAt, duedAt è impostato sullo stesso valore
• Creazione di Tag: I nuovi tag vengono creati automaticamente se non esistono con il titolo/colore specificato
• Selezione dell'Elenco: Se non viene fornito todoListId, viene utilizzato il primo elenco todo nel progetto

Effetti Collaterali

La creazione di un record attiva:

• Creazione di un'entrata nel registro delle attività
• Notifiche webhook
• Aggiornamenti dell'indice di ricerca
• Esecuzione di regole di automazione (se configurate)
• Notifiche email/push (se notify: true)
• Calcoli dei campi personalizzati di formula e durata
• Aggiornamenti di analisi e grafici

Endpoint Correlati

• Elenca Record: Interroga i todo per recuperare record esistenti
• Aggiorna Record: Usa la mutazione updateTodo per modificare i record
• Elenca Campi Personalizzati: Interroga per ottenere gli ID dei campi personalizzati disponibili
• Elenca Tag: Interroga per ottenere gli ID dei tag esistenti
• Elenca Elenchi Todo: Interroga per ottenere gli ID degli elenchi todo disponibili