Registrieren
Kontakt Anmelden Registrieren
Systemstatus

Aktualisieren Sie benutzerdefinierte Feldwerte in Datensätzen mithilfe von typenspezifischen Parametern für jeden Feldtyp

Benutzerdefinierte Feldwerte festlegen

Benutzerdefinierte Felder erweitern die Standarddatensatzstruktur von Blue um geschäftsspezifische Daten. Dieser Endpunkt ermöglicht es Ihnen, Werte für jedes benutzerdefinierte Feld in einem Datensatz festzulegen oder zu aktualisieren. Jeder Feldtyp erfordert spezifische Parameter, um die Datenintegrität und die ordnungsgemäße Validierung sicherzustellen.

Einfaches Beispiel

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

Fortgeschrittenes Beispiel

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

Eingabeparameter

SetTodoCustomFieldInput

Parameter Typ Erforderlich Beschreibung
todoId String! ✅ Ja Die ID des zu aktualisierenden Datensatzes
customFieldId String! ✅ Ja Die ID des benutzerdefinierten Feldes
text String Nein Für TEXT_SINGLE, TEXT_MULTI, TELEFON, E-MAIL, URL
number Float Nein Für ZAHL, PROZENT, BEWERTUNG
currency String Nein Währungscode für den WÄHRUNG-Typ (z.B. "USD")
checked Boolean Nein Für CHECKBOX-Felder
startDate DateTime Nein Startdatum für DATUM-Felder
endDate DateTime Nein Enddatum für DATUM-Bereichsfelder
timezone String Nein Zeitzone für DATUM-Felder (z.B. "America/New_York")
latitude Float Nein Breitengrad für ORT-Felder
longitude Float Nein Längengrad für ORT-Felder
regionCode String Nein Regionscode für TELEFON-Felder
countryCodes [String!] Nein ISO-Ländercodes für LAND-Felder
customFieldOptionId String Nein Options-ID für SELECT_SINGLE-Felder
customFieldOptionIds [String!] Nein Options-IDs für SELECT_MULTI-Felder
customFieldReferenceTodoIds [String!] Nein Datensatz-IDs für REFERENZ-Felder

Beispiele für Feldtypen

Textfelder

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

Zahlenfelder

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

Auswahlfelder

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

Datumsfelder

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

Standortfelder

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

Währungsfelder

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

Dateifelder

Dateifelder verwenden separate Mutationen:

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

Werte während der Datensatz-Erstellung festlegen

Sie können benutzerdefinierte Feldwerte beim Erstellen eines neuen Datensatzes festlegen:

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

Antwortfelder

Die Mutation gibt einen booleschen Wert zurück, der den Erfolg anzeigt:

Feld Typ Beschreibung
setTodoCustomField Boolean! Wahr, wenn die Operation erfolgreich war

Erforderliche Berechtigungen

Benutzer müssen die Berechtigung haben, sowohl den Datensatz als auch das spezifische benutzerdefinierte Feld zu bearbeiten:

Rolle Kann Feldwerte festlegen
OWNER ✅ Ja
ADMIN ✅ Ja
MEMBER ✅ Ja (es sei denn, durch eine benutzerdefinierte Rolle eingeschränkt)
CLIENT ✅ Ja (es sei denn, durch eine benutzerdefinierte Rolle eingeschränkt)

Für Benutzer mit benutzerdefinierten Projektrollen führt das System eine zweistufige Überprüfung durch:

  1. Zuerst wird überprüft, ob der Benutzer Zugriff auf Projektebene hat
  2. Dann wird überprüft, ob das spezifische Feld in ihrer Konfiguration der benutzerdefinierten Rolle als editable markiert ist

Das bedeutet, dass ein Benutzer möglicherweise allgemeinen Projektzugriff hat, aber dennoch von der Bearbeitung bestimmter Felder aufgrund seiner benutzerdefinierten Rolle ausgeschlossen sein kann.

Fehlermeldungen

Benutzerdefiniertes Feld nicht gefunden

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

Unbefugter Zugriff

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

Ungültiger Feldwert

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

Wichtige Hinweise

  • Upsert-Verhalten: Die Mutation erstellt einen neuen Feldwert, wenn keiner vorhanden ist, oder aktualisiert den vorhandenen Wert
  • Typensicherheit: Stellen Sie nur Parameter zur Verfügung, die dem Feldtyp entsprechen (z.B. senden Sie nicht text für ein ZAHL-Feld)
  • Nebenwirkungen: Das Festlegen von Werten löst aus:
    • Neuberechnungen von Formel-Feldern
    • Automatisierungsregeln
    • Webhook-Benachrichtigungen
    • Einträge im Aktivitätsprotokoll
    • Aktualisierungen von Diagrammen
  • Besondere Verhaltensweisen:
    • WÄHRUNG-Felder behandeln automatisch Umrechnungsberechnungen
    • REFERENZ-Felder aktualisieren bidirektionale Beziehungen
    • FORMEL-Felder sind schreibgeschützt und können nicht direkt festgelegt werden (sie werden automatisch berechnet)
    • LOOKUP-Felder sind schreibgeschützt und können nicht direkt festgelegt werden (sie ziehen Daten aus referenzierten Datensätzen)
    • BUTTON-Felder lösen Automatisierungsereignisse aus, wenn sie "geklickt" werden
  • Validierung: Die API validiert, dass:
    • Der Datensatz im Projekt existiert
    • Das benutzerdefinierte Feld im selben Projekt existiert
    • Der Benutzer Bearbeitungsberechtigungen hat
    • Der Wert den Anforderungen des Feldtyps entspricht

Wertformatreferenz

Feldtyp Parameter Format Beispiel
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

Verwandte Endpunkte

© Blue | Entworfen mit ❤ über die

KI-Assistent

Antworten werden mit KI generiert und können Fehler enthalten.

Wie kann ich Ihnen helfen?

Fragen Sie mich alles über Blue oder diese Dokumentation.

Eingabe zum Senden • Shift+Eingabe für neue Zeile • ⌘I zum Öffnen