Définir des valeurs de champ personnalisées

Mettre à jour les valeurs des champs personnalisés sur les enregistrements en utilisant des paramètres spécifiques au type pour chaque type de champ

Définir des valeurs de champ personnalisées

Les champs personnalisés étendent la structure d'enregistrement standard de Blue avec des données spécifiques à l'entreprise. Ce point de terminaison vous permet de définir ou de mettre à jour des valeurs pour tout champ personnalisé sur un enregistrement. Chaque type de champ nécessite des paramètres spécifiques pour garantir l'intégrité des données et une validation appropriée.

Exemple de base

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

Exemple avancé

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

Paramètres d'entrée

SetTodoCustomFieldInput

Paramètre	Type	Requis	Description
`todoId`	String!	✅ Oui	L'ID de l'enregistrement à mettre à jour
`customFieldId`	String!	✅ Oui	L'ID du champ personnalisé
`text`	String	Non	Pour TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
`number`	Float	Non	Pour NUMBER, PERCENT, RATING
`currency`	String	Non	Code de devise pour le type CURRENCY (par exemple, "USD")
`checked`	Boolean	Non	Pour les champs CHECKBOX
`startDate`	DateTime	Non	Date de début pour les champs DATE
`endDate`	DateTime	Non	Date de fin pour les champs de plage DATE
`timezone`	String	Non	Fuseau horaire pour les champs DATE (par exemple, "America/New_York")
`latitude`	Float	Non	Latitude pour les champs LOCATION
`longitude`	Float	Non	Longitude pour les champs LOCATION
`regionCode`	String	Non	Code de région pour les champs PHONE
`countryCodes`	[String!]	Non	Codes de pays ISO pour les champs COUNTRY
`customFieldOptionId`	String	Non	ID d'option pour les champs SELECT_SINGLE
`customFieldOptionIds`	[String!]	Non	IDs d'option pour les champs SELECT_MULTI
`customFieldReferenceTodoIds`	[String!]	Non	IDs d'enregistrement pour les champs REFERENCE

Exemples de types de champ

Champs de texte

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

Champs numériques

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

Champs de sélection

# 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"]
  })
}

Champs de date

# 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"
  })
}

Champs de localisation

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

Champs de devise

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

Champs de fichier

Les champs de fichier utilisent des mutations séparées :

# 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"
  })
}

Définir des valeurs lors de la création d'enregistrements

Vous pouvez définir des valeurs de champ personnalisé lors de la création d'un nouvel enregistrement :

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

Champs de réponse

La mutation renvoie un booléen indiquant le succès :

Champ	Type	Description
`setTodoCustomField`	Boolean!	Vrai si l'opération a réussi

Permissions requises

Les utilisateurs doivent avoir la permission de modifier à la fois l'enregistrement et le champ personnalisé spécifique :

Rôle	Peut définir des valeurs de champ
`OWNER`	✅ Oui
`ADMIN`	✅ Oui
`MEMBER`	✅ Oui (sauf si restreint par un rôle personnalisé)
`CLIENT`	✅ Oui (sauf si restreint par un rôle personnalisé)

Pour les utilisateurs avec des rôles de projet personnalisés, le système effectue une vérification à deux niveaux :

Tout d'abord, il vérifie que l'utilisateur a un accès au niveau du projet
Ensuite, il vérifie si le champ spécifique est marqué comme editable dans leur configuration de rôle personnalisé

Cela signifie qu'un utilisateur peut avoir un accès général au projet mais être restreint dans l'édition de certains champs en fonction de son rôle personnalisé.

Réponses d'erreur

Champ personnalisé non trouvé

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

Accès non autorisé

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

Valeur de champ invalide

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

Notes importantes

Comportement d'Upsert : La mutation crée une nouvelle valeur de champ si aucune n'existe, ou met à jour la valeur existante
Sécurité des types : Ne fournissez que des paramètres qui correspondent au type de champ (par exemple, n'envoyez pas text pour un champ NUMBER)
Effets secondaires : La définition de valeurs déclenche :
- Recalculs des champs de formule
- Règles d'automatisation
- Notifications de webhook
- Entrées de journal d'activité
- Mises à jour de graphiques
Comportements spéciaux :
- Les champs CURRENCY gèrent automatiquement les calculs de conversion
- Les champs REFERENCE mettent à jour les relations bidirectionnelles
- Les champs FORMULA sont en lecture seule et ne peuvent pas être définis directement (ils sont calculés automatiquement)
- Les champs LOOKUP sont en lecture seule et ne peuvent pas être définis directement (ils tirent des données des enregistrements référencés)
- Les champs BUTTON déclenchent des événements d'automatisation lorsqu'ils sont "cliqués"
Validation : L'API valide que :
- L'enregistrement existe dans le projet
- Le champ personnalisé existe dans le même projet
- L'utilisateur a des permissions d'édition
- La valeur correspond aux exigences de type de champ

Référence de format de valeur

Type de champ	Paramètre	Format	Exemple
`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

Points de terminaison associés

Lister les champs personnalisés - Obtenir les champs personnalisés disponibles
Créer un champ personnalisé - Ajouter de nouveaux champs personnalisés
Obtenir les détails de l'enregistrement - Récupérer les enregistrements avec des valeurs de champ personnalisées
Mise à jour en masse des enregistrements - Mettre à jour plusieurs enregistrements à la fois