Imposta Valori dei Campi Personalizzati

Aggiorna i valori dei campi personalizzati nei record utilizzando parametri specifici per ciascun tipo di campo

Imposta Valori dei Campi Personalizzati

I campi personalizzati estendono la struttura standard dei record di Blue con dati specifici per l'azienda. Questo endpoint consente di impostare o aggiornare i valori per qualsiasi campo personalizzato in un record. Ogni tipo di campo richiede parametri specifici per garantire l'integrità dei dati e una corretta convalida.

Esempio di Base

mutation SetTextFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_xyz789"
    text: "Project specification document"
  })
}

Esempio Avanzato

mutation SetMultipleFieldTypes {
  # Set a date range field
  dateField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_date_001"
    startDate: "2024-01-15T09:00:00Z"
    endDate: "2024-01-31T17:00:00Z"
    timezone: "America/New_York"
  })
  
  # Set a multi-select field
  selectField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_select_002"
    customFieldOptionIds: ["option_high", "option_urgent", "option_client"]
  })
  
  # Set a location field
  locationField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_location_003"
    latitude: 40.7128
    longitude: -74.0060
  })
}

Parametri di Input

SetTodoCustomFieldInput

Parametro	Tipo	Richiesto	Descrizione
`todoId`	String!	✅ Sì	L'ID del record da aggiornare
`customFieldId`	String!	✅ Sì	L'ID del campo personalizzato
`text`	String	No	Per TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
`number`	Float	No	Per NUMBER, PERCENT, RATING
`currency`	String	No	Codice valuta per il tipo CURRENCY (es. "USD")
`checked`	Boolean	No	Per i campi CHECKBOX
`startDate`	DateTime	No	Data di inizio per i campi DATE
`endDate`	DateTime	No	Data di fine per i campi DATE range
`timezone`	String	No	Fuso orario per i campi DATE (es. "America/New_York")
`latitude`	Float	No	Latitudine per i campi LOCATION
`longitude`	Float	No	Longitudine per i campi LOCATION
`regionCode`	String	No	Codice regione per i campi PHONE
`countryCodes`	[String!]	No	Codici paese ISO per i campi COUNTRY
`customFieldOptionId`	String	No	ID opzione per i campi SELECT_SINGLE
`customFieldOptionIds`	[String!]	No	ID opzioni per i campi SELECT_MULTI
`customFieldReferenceTodoIds`	[String!]	No	ID record per i campi REFERENCE

Esempi di Tipo di Campo

Campi di Testo

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_description"
    text: "Detailed project requirements and specifications"
  })
}

Campi Numerici

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_budget"
    number: 15000.50
  })
}

Campi di Selezione

# Single Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_priority"
    customFieldOptionId: "option_high"
  })
}

# Multi Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_tags"
    customFieldOptionIds: ["option_frontend", "option_urgent", "option_v2"]
  })
}

Campi di Data

# Single Date
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_deadline"
    startDate: "2024-12-31T23:59:59Z"
  })
}

# Date Range
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_project_timeline"
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-03-31T23:59:59Z"
    timezone: "UTC"
  })
}

Campi di Posizione

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_office_location"
    latitude: 37.7749
    longitude: -122.4194
  })
}

Campi di Valuta

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_invoice_amount"
    number: 5000
    currency: "USD"
  })
}

Campi di File

I campi file utilizzano mutazioni separate:

# Add a file
mutation {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

# Remove a file
mutation {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

Impostazione dei Valori Durante la Creazione del Record

Puoi impostare i valori dei campi personalizzati quando crei un nuovo record:

mutation {
  createTodo(input: {
    todoListId: "list_project_123"
    title: "New Feature Development"
    customFields: [
      {
        customFieldId: "field_priority"
        value: "high"
      },
      {
        customFieldId: "field_estimate"
        value: "8"
      }
    ]
  }) {
    id
    customFields {
      customField {
        name
      }
      value
    }
  }
}

Campi di Risposta

La mutazione restituisce un booleano che indica il successo:

Campo	Tipo	Descrizione
`setTodoCustomField`	Boolean!	Vero se l'operazione ha avuto successo

Permessi Richiesti

Gli utenti devono avere il permesso di modificare sia il record che il campo personalizzato specifico:

Ruolo	Può Impostare Valori dei Campi
`OWNER`	✅ Sì
`ADMIN`	✅ Sì
`MEMBER`	✅ Sì (a meno che non sia limitato da un ruolo personalizzato)
`CLIENT`	✅ Sì (a meno che non sia limitato da un ruolo personalizzato)

Per gli utenti con ruoli di progetto personalizzati, il sistema esegue un controllo a due livelli:

Prima verifica che l'utente abbia accesso a livello di progetto
Poi controlla se il campo specifico è contrassegnato come editable nella loro configurazione del ruolo personalizzato

Ciò significa che un utente potrebbe avere accesso generale al progetto ma essere comunque limitato nella modifica di determinati campi in base al proprio ruolo personalizzato.

Risposte di Errore

Campo Personalizzato Non Trovato

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Accesso Non Autorizzato

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Valore del Campo Non Valido

{
  "errors": [{
    "message": "Invalid value for field type NUMBER",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Note Importanti

Comportamento Upsert: La mutazione crea un nuovo valore di campo se non esiste, o aggiorna il valore esistente
Sicurezza del Tipo: Fornisci solo parametri che corrispondono al tipo di campo (es. non inviare text per un campo NUMBER)
Effetti Collaterali: Impostare valori attiva:
- Ricalcoli dei campi formula
- Regole di automazione
- Notifiche webhook
- Voci nel registro delle attività
- Aggiornamenti dei grafici
Comportamenti Speciali:
- I campi CURRENCY gestiscono automaticamente i calcoli di conversione
- I campi REFERENCE aggiornano le relazioni bidirezionali
- I campi FORMULA sono di sola lettura e non possono essere impostati direttamente (vengono calcolati automaticamente)
- I campi LOOKUP sono di sola lettura e non possono essere impostati direttamente (estraggono dati dai record referenziati)
- I campi BUTTON attivano eventi di automazione quando vengono "cliccati"
Convalida: L'API convalida che:
- Il record esista nel progetto
- Il campo personalizzato esista nello stesso progetto
- L'utente abbia permessi di modifica
- Il valore soddisfi i requisiti del tipo di campo

Riferimento al Formato del Valore

Tipo di Campo	Parametro	Formato	Esempio
`TEXT_SINGLE`	`text`	String	`"Project Alpha"`
`TEXT_MULTI`	`text`	String with newlines	`"Line 1\nLine 2"`
`NUMBER`	`number`	Float	`42.5`
`CURRENCY`	`number` + `currency`	Float + ISO code	`1000.00` + `"USD"`
`PERCENT`	`number`	Float (0-100)	`75`
`RATING`	`number`	Float (within min/max)	`4.5`
`CHECKBOX`	`checked`	Boolean	`true`
`DATE`	`startDate`	ISO 8601 DateTime	`"2024-01-15T00:00:00Z"`
`DATE` (range)	`startDate` + `endDate`	ISO 8601 DateTimes	See example above
`SELECT_SINGLE`	`customFieldOptionId`	Option ID	`"option_123"`
`SELECT_MULTI`	`customFieldOptionIds`	Array of Option IDs	`["opt_1", "opt_2"]`
`PHONE`	`text`	String	`"+1-555-123-4567"`
`EMAIL`	`text`	String	`"user@example.com"`
`URL`	`text`	String	`"https://example.com"`
`LOCATION`	`latitude` + `longitude`	Floats	`40.7128, -74.0060`
`COUNTRY`	`countryCodes`	ISO 3166 codes	`["US", "CA"]`
`REFERENCE`	`customFieldReferenceTodoIds`	Array of record IDs	`["todo_1", "todo_2"]`
`FORMULA`	N/A	Read-only - calculated automatically	N/A
`LOOKUP`	N/A	Read-only - pulls from references	N/A

Endpoint Correlati

Elenca Campi Personalizzati - Ottieni i campi personalizzati disponibili
Crea Campo Personalizzato - Aggiungi nuovi campi personalizzati
Ottieni Dettagli del Record - Recupera record con valori di campi personalizzati
Aggiorna Record in Blocco - Aggiorna più record contemporaneamente