Créer un enregistrement

Créez un nouvel enregistrement (todo) dans Blue avec des champs personnalisés, des étiquettes et des attributions optionnels.

Créer un enregistrement

La mutation createTodo vous permet de créer de nouveaux enregistrements dans Blue avec des options de configuration complètes, y compris des champs personnalisés, des étiquettes, des attributions, et plus encore. Les enregistrements peuvent être créés dans des listes spécifiques ou automatiquement placés dans la liste par défaut.

Exemple de base

Créez un enregistrement simple avec juste un titre :

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

Exemple avancé

Créez un enregistrement avec toutes les options disponibles :

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

Paramètres d'entrée

CreateTodoInput

Paramètre	Type	Requis	Description
`todoListId`	String	Non	ID de la liste todo à laquelle ajouter l'enregistrement. Si non fourni, utilise la première liste todo du projet
`title`	String!	✅ Oui	Titre de l'enregistrement (requis)
`position`	Float	Non	Position personnalisée dans la liste. Si non fournie, utilise le paramètre de placement
`placement`	CreateTodoInputPlacement	Non	Où placer l'enregistrement si la position n'est pas spécifiée (HAUT ou BAS)
`startedAt`	DateTime	Non	Date/heure de début pour l'enregistrement
`duedAt`	DateTime	Non	Date/heure d'échéance pour l'enregistrement
`notify`	Boolean	Non	Indique si des notifications doivent être envoyées pour cette création d'enregistrement
`description`	String	Non	Contenu de la description HTML (sera assaini)
`assigneeIds`	[String!]	Non	Tableau d'IDs d'utilisateurs à attribuer à cet enregistrement
`checklists`	[CreateChecklistWithoutTodoInput!]	Non	Tableau de listes de contrôle à créer avec l'enregistrement
`customFields`	[CreateTodoInputCustomField]	Non	Tableau de valeurs de champs personnalisés
`tags`	[CreateTodoTagInput!]	Non	Tableau d'étiquettes à attacher à l'enregistrement

Valeurs de CreateTodoInputPlacement

Valeur	Description
`TOP`	Placer en haut de la liste (position la plus élevée)
`BOTTOM`	Placer en bas de la liste (position la plus basse)

CreateTodoTagInput

Paramètre	Type	Requis	Description
`id`	String	Non*	ID de l'étiquette existante à connecter
`title`	String	Non*	Titre de l'étiquette (crée une nouvelle étiquette si elle n'existe pas)
`color`	String	Non	Couleur hexadécimale pour la nouvelle étiquette (par défaut #4a9fff)

*Remarque : Vous devez fournir soit id (pour une étiquette existante) OU title (pour créer/trouver par titre)

CreateTodoInputCustomField

Paramètre	Type	Requis	Description
`customFieldId`	String	Non	ID du champ personnalisé
`value`	String	Non	Valeur pour le champ personnalisé (voir le guide de format ci-dessous)

CreateChecklistWithoutTodoInput

Paramètre	Type	Requis	Description
`title`	String!	✅ Oui	Titre de la liste de contrôle
`position`	Float	Non	Position de la liste de contrôle dans l'enregistrement

Formats des valeurs de champ personnalisé

Lors de la définition des valeurs des champs personnalisés, utilisez ces formats en fonction du type de champ :

Type de champ	Format	Exemple
`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"`

Champs de réponse

La mutation renvoie un objet Todo avec des détails complets sur l'enregistrement :

Champ	Type	Description
`id`	String!	Identifiant unique pour l'enregistrement
`uid`	String!	Identifiant unique alternatif
`title`	String!	Titre de l'enregistrement
`position`	Float!	Position dans la liste
`done`	Boolean!	Statut d'achèvement
`startedAt`	DateTime	Date/heure de début
`duedAt`	DateTime	Date/heure d'échéance
`todoList`	TodoList	Détails de la liste todo associée
`users`	[User!]	Utilisateurs assignés
`tags`	[Tag!]	Étiquettes associées
`checklists`	[Checklist!]	Listes de contrôle associées
`customFields`	[CustomFieldValue!]	Valeurs des champs personnalisés

Permissions requises

Les utilisateurs doivent avoir un accès approprié au projet pour créer des enregistrements :

Niveau d'accès	Peut créer des enregistrements
`OWNER`	✅ Oui
`ADMIN`	✅ Oui
`MEMBER`	✅ Oui
`CLIENT`	✅ Oui
`COMMENT_ONLY`	❌ Non
`VIEW_ONLY`	❌ Non

La mutation nécessite que le niveau d'accès du projet de l'utilisateur soit OWNER, ADMIN, MEMBER, ou CLIENT. Les utilisateurs avec les rôles VIEW_ONLY ou COMMENT_ONLY ne peuvent pas créer d'enregistrements.

Réponses d'erreur

ProjectNotFoundError

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

Quand : Aucun contexte de projet n'est disponible pour l'utilisateur.

TodoListCreateTodoLimitError

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

Quand : La liste todo contient déjà 100 000 enregistrements (limite maximale).

TodoListNotFoundError

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

Quand : La todoListId spécifiée n'existe pas ou l'utilisateur n'a pas accès.

CustomFieldValueParseError

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

Quand : La valeur du champ personnalisé échoue à la validation (par exemple, téléphone invalide, évaluation hors limites).

Notes importantes

Performance

Chaque liste todo peut contenir jusqu'à 100 000 enregistrements
La création d'enregistrements déclenche plusieurs processus en arrière-plan (webhooks, automatisations, indexation de recherche)
Les opérations par lots sont plus efficaces que la création d'enregistrements un par un

Logique commerciale

Gestion de la position : La position par défaut est 65535.0 lorsque ni position ni placement ne sont spécifiés
Logique de date :
- Si seule duedAt est fournie, startedAt est défini au début de ce jour
- Si seule startedAt est fournie, duedAt est défini à la même valeur
Création d'étiquettes : De nouvelles étiquettes sont automatiquement créées si elles n'existent pas avec le titre/couleur spécifié
Sélection de liste : Si aucune todoListId n'est fournie, la première liste todo du projet est utilisée

Effets secondaires

La création d'un enregistrement déclenche :

Création d'entrée dans le journal d'activité
Notifications webhook
Mises à jour de l'index de recherche
Exécution de règles d'automatisation (si configuré)
Notifications par e-mail/push (si notify: true)
Calculs de champs personnalisés de formule et de durée
Mises à jour d'analytique et de graphiques

Points de terminaison associés

Lister les enregistrements : Interroger les todos pour récupérer les enregistrements existants
Mettre à jour l'enregistrement : Utiliser la mutation updateTodo pour modifier les enregistrements
Lister les champs personnalisés : Interroger pour obtenir les IDs de champs personnalisés disponibles
Lister les étiquettes : Interroger pour obtenir les IDs d'étiquettes existants
Lister les listes de todo : Interroger pour obtenir les IDs de listes de todo disponibles