Créer un champ personnalisé

Ajoutez de nouveaux champs personnalisés pour étendre la structure de données de votre projet avec des configurations spécifiques au type

Créer un champ personnalisé

Les champs personnalisés vous permettent d'adapter Blue à vos besoins commerciaux spécifiques en ajoutant des champs de données structurées à vos enregistrements. Ce point de terminaison crée un nouveau champ personnalisé avec des configurations spécifiques à chaque type de champ.

Exemple de base

mutation CreateTextField {
  createCustomField(input: {
    name: "Customer Name"
    type: TEXT_SINGLE
    description: "Primary customer contact name"
  }) {
    id
    uid
    name
    type
    position
  }
}

Exemple avancé

mutation CreateAdvancedField {
  createCustomField(input: {
    name: "Project Budget"
    type: CURRENCY
    description: "Total allocated budget for this project"
    currency: "USD"
    min: 0
    max: 1000000
  }) {
    id
    uid
    name
    type
    currency
    min
    max
    position
    createdAt
  }
}

Paramètres d'entrée

CreateCustomFieldInput

Paramètre	Type	Requis	Description
`name`	String!	✅ Oui	Le nom d'affichage du champ personnalisé
`type`	CustomFieldType!	✅ Oui	Le type de champ (voir types ci-dessous)
`description`	String	Non	Description optionnelle expliquant l'objectif du champ
`min`	Float	Non	Valeur minimale pour les champs NUMBER, RATING, PERCENT
`max`	Float	Non	Valeur maximale pour les champs NUMBER, RATING, PERCENT
`currency`	String	Non	Code de devise ISO pour les champs CURRENCY
`prefix`	String	Non	Préfixe de texte pour les champs UNIQUE_ID
`isDueDate`	Boolean	Non	Indique si le champ DATE représente une date d'échéance
`formula`	JSON	Non	Configuration de formule pour les champs FORMULA
`referenceProjectId`	String	Non	ID du projet cible pour les champs REFERENCE
`referenceMultiple`	Boolean	Non	Autoriser plusieurs sélections dans les champs REFERENCE
`referenceFilter`	TodoFilterInput	Non	Options de filtre pour les champs REFERENCE
`lookupOption`	CustomFieldLookupOptionInput	Non	Configuration pour les champs LOOKUP
`timeDurationDisplay`	CustomFieldTimeDurationDisplayType	Non	Format d'affichage pour TIME_DURATION
`timeDurationTargetTime`	Float	Non	Temps cible en secondes pour TIME_DURATION
`timeDurationStartInput`	CustomFieldTimeDurationInput	Non	Déclencheur de début pour TIME_DURATION
`timeDurationEndInput`	CustomFieldTimeDurationInput	Non	Déclencheur de fin pour TIME_DURATION
`buttonType`	String	Non	Type d'action de bouton pour les champs BUTTON
`buttonConfirmText`	String	Non	Invite de confirmation pour les champs BUTTON
`useSequenceUniqueId`	Boolean	Non	Utiliser une numérotation séquentielle pour UNIQUE_ID
`sequenceDigits`	Int	Non	Nombre de chiffres dans la séquence (par exemple, 5 → 00001)
`sequenceStartingNumber`	Int	Non	Numéro de départ pour la séquence
`currencyFieldId`	String	Non	Champ de devise de référence pour CURRENCY_CONVERSION
`conversionDate`	String	Non	Date de conversion pour CURRENCY_CONVERSION
`conversionDateType`	String	Non	Type de date de conversion pour CURRENCY_CONVERSION
`metadata`	JSON	Non	Métadonnées supplémentaires pour le champ personnalisé

Valeurs de CustomFieldType

Valeur	Description	Paramètres requis
`TEXT_SINGLE`	Champ de texte à une ligne	Aucun
`TEXT_MULTI`	Zone de texte multi-lignes	Aucun
`SELECT_SINGLE`	Menu déroulant à sélection unique	Create options separately
`SELECT_MULTI`	Menu déroulant à sélection multiple	Create options separately
`CHECKBOX`	Case à cocher booléenne	Aucun
`RATING`	Champ d'évaluation par étoiles	Optional: `max` (default: 5)
`PHONE`	Numéro de téléphone avec validation	Aucun
`NUMBER`	Saisie numérique	Optional: `min`, `max`
`CURRENCY`	Montant en devise	Optional: `currency`, `min`, `max`
`PERCENT`	Pourcentage (0-100)	Optional: `min`, `max`
`EMAIL`	Email avec validation	Aucun
`URL`	URL Web avec validation	Aucun
`UNIQUE_ID`	Identifiant généré automatiquement	Optional: `prefix`, `useSequenceUniqueId`
`LOCATION`	Coordonnées géographiques	Aucun
`FILE`	Pièce jointe	Aucun
`DATE`	Sélecteur de date	Optional: `isDueDate`
`COUNTRY`	Sélecteur de pays	Aucun
`FORMULA`	Champ calculé	Required: `formula`
`REFERENCE`	Lien vers d'autres enregistrements	Required: `referenceProjectId`
`LOOKUP`	Extraire des données des références	Required: `lookupOption`
`TIME_DURATION`	Suivi du temps	Required: duration inputs (see below)
`BUTTON`	Bouton d'action	Optional: `buttonType`, `buttonConfirmText`
`CURRENCY_CONVERSION`	Convertisseur de devises	Special configuration

Exemples de configuration de type de champ

Champ numérique avec contraintes

mutation CreateQuantityField {
  createCustomField(input: {
    name: "Quantity"
    type: NUMBER
    description: "Number of items"
    min: 1
    max: 999
  }) {
    id
    name
    min
    max
  }
}

Champ de devise

mutation CreateBudgetField {
  createCustomField(input: {
    name: "Budget"
    type: CURRENCY
    currency: "EUR"
    min: 0
  }) {
    id
    name
    currency
    min
  }
}

Champ de date avec indicateur de date d'échéance

mutation CreateDeadlineField {
  createCustomField(input: {
    name: "Project Deadline"
    type: DATE
    isDueDate: true
    description: "When this project must be completed"
  }) {
    id
    name
    isDueDate
  }
}

Champ de référence

mutation CreateRelatedTasksField {
  createCustomField(input: {
    name: "Dependencies"
    type: REFERENCE
    referenceProjectId: "proj_abc123"
    referenceMultiple: true
    referenceFilter: {
      statusIds: ["status_open", "status_inprogress"]
    }
  }) {
    id
    name
    referenceProjectId
    referenceMultiple
  }
}

Champ de recherche

mutation CreateLookupField {
  createCustomField(input: {
    name: "Customer Email"
    type: LOOKUP
    lookupOption: {
      referenceId: "field_customer_ref"
      lookupId: "field_email"
      lookupType: TODO_CUSTOM_FIELD
    }
  }) {
    id
    name
    customFieldLookupOption {
      referenceId
      lookupId
      lookupType
    }
  }
}

ID unique avec séquence

mutation CreateOrderNumberField {
  createCustomField(input: {
    name: "Order Number"
    type: UNIQUE_ID
    prefix: "ORD-"
    useSequenceUniqueId: true
    sequenceDigits: 6
    sequenceStartingNumber: 1000
  }) {
    id
    name
    prefix
  }
}

Champ de durée

mutation CreateTimeTrackingField {
  createCustomField(input: {
    name: "Time to Resolution"
    type: TIME_DURATION
    timeDurationDisplay: FULL_DATE_STRING
    timeDurationStartInput: {
      type: TODO_CREATED_AT
      condition: FIRST
    }
    timeDurationEndInput: {
      type: TODO_MARKED_AS_COMPLETE
      condition: FIRST
    }
  }) {
    id
    name
  }
}

Types de durée valides

TODO_CREATED_AT - Lorsque l'enregistrement a été créé
TODO_CUSTOM_FIELD - Lorsque le champ personnalisé change
TODO_DUE_DATE - Lorsque la date d'échéance est définie/modifiée
TODO_MARKED_AS_COMPLETE - Lorsque l'enregistrement est marqué comme complet
TODO_MOVED - Lorsque l'enregistrement est déplacé vers une autre liste
TODO_TAG_ADDED - Lorsque une étiquette est ajoutée
TODO_ASSIGNEE_ADDED - Lorsque un assigné est ajouté

Création d'options de sélection

Après avoir créé un champ SELECT_SINGLE ou SELECT_MULTI, ajoutez des options :

mutation CreateSelectOptions {
  createCustomFieldOptions(input: {
    customFieldId: "field_xyz789"
    customFieldOptions: [
      { title: "High", color: "#FF0000", position: 1 }
      { title: "Medium", color: "#FFA500", position: 2 }
      { title: "Low", color: "#00FF00", position: 3 }
    ]
  }) {
    id
    title
    color
    position
  }
}

Champs de réponse

CustomField

Champ	Type	Description
`id`	String!	Identifiant unique
`uid`	String!	ID unique convivial
`name`	String!	Nom d'affichage
`type`	CustomFieldType!	Type de champ
`description`	String	Description du champ
`position`	Float!	Position d'ordre d'affichage
`createdAt`	DateTime!	Horodatage de création
`updatedAt`	DateTime!	Horodatage de dernière mise à jour
`min`	Float	Valeur minimale (le cas échéant)
`max`	Float	Valeur maximale (le cas échéant)
`currency`	String	Code de devise (type CURRENCY)
`prefix`	String	Préfixe d'ID (type UNIQUE_ID)
`isDueDate`	Boolean	Indicateur de date d'échéance (type DATE)
`formula`	JSON	Configuration de formule (type FORMULA)
`referenceProjectId`	String	Projet référencé (type REFERENCE)
`customFieldLookupOption`	CustomFieldLookupOption	Configuration de recherche (type LOOKUP)

Permissions requises

La création de champs personnalisés nécessite un accès au projet :

Rôle	Peut créer des champs personnalisés
`OWNER`	✅ Oui
`ADMIN`	✅ Oui
`MEMBER`	✅ Oui
`CLIENT`	❌ Non

Remarque : Les rôles personnalisés peuvent avoir des restrictions supplémentaires sur la gestion des champs.

Réponses d'erreur

Type de champ invalide

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

Projet de référence introuvable

{
  "errors": [{
    "message": "Reference project not found or access denied",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Configuration requise manquante

{
  "errors": [{
    "message": "REFERENCE fields require referenceProjectId",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Notes importantes

Position du champ : Calculée automatiquement pour apparaître à la fin des champs existants
Limites des champs : Les projets peuvent avoir des limites sur le nombre de champs personnalisés
Disponibilité immédiate : Les champs créés sont immédiatement disponibles à l'utilisation
Effets secondaires : La création d'un champ déclenche :
- Une entrée dans le journal d'activité
- Des mises à jour en temps réel pour les utilisateurs connectés
- Des notifications webhook
- Des travaux en arrière-plan pour les champs FORMULA, LOOKUP et UNIQUE_ID
Considérations spéciales :
- Les champs REFERENCE nécessitent un accès au projet cible
- Les champs LOOKUP dépendent des champs REFERENCE existants
- Les champs FORMULA ne peuvent pas se référencer eux-mêmes
- Les séquences UNIQUE_ID sont traitées de manière asynchrone
- Les champs SELECT nécessitent que des options soient créées séparément
Nommage : Les noms des champs doivent être clairs et descriptifs tels qu'ils apparaissent dans l'interface utilisateur

Points de terminaison associés

Lister les champs personnalisés - Voir les champs personnalisés existants
Mettre à jour un champ personnalisé - Modifier les propriétés du champ
Supprimer un champ personnalisé - Supprimer un champ personnalisé
Créer des options de champ - Ajouter des options aux champs de sélection
Définir des valeurs de champ personnalisé - Définir des valeurs sur les enregistrements