Ustaw wartości pól niestandardowych

Zaktualizuj wartości pól niestandardowych w rekordach, używając specyficznych dla typu parametrów dla każdego typu pola

Ustaw wartości pól niestandardowych

Pola niestandardowe rozszerzają standardową strukturę rekordu Blue o dane specyficzne dla biznesu. Ten punkt końcowy umożliwia ustawienie lub aktualizację wartości dla dowolnego pola niestandardowego w rekordzie. Każdy typ pola wymaga specyficznych parametrów, aby zapewnić integralność danych i prawidłową walidację.

Podstawowy przykład

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

Zaawansowany przykład

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

Parametry wejściowe

SetTodoCustomFieldInput

Parametr	Typ	Wymagane	Opis
`todoId`	String!	✅ Tak	ID rekordu do zaktualizowania
`customFieldId`	String!	✅ Tak	ID pola niestandardowego
`text`	String	Nie	Dla TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
`number`	Float	Nie	Dla NUMBER, PERCENT, RATING
`currency`	String	Nie	Kod waluty dla typu CURRENCY (np. "USD")
`checked`	Boolean	Nie	Dla pól CHECKBOX
`startDate`	DateTime	Nie	Data początkowa dla pól DATE
`endDate`	DateTime	Nie	Data końcowa dla pól zakresu DATE
`timezone`	String	Nie	Strefa czasowa dla pól DATE (np. "America/New_York")
`latitude`	Float	Nie	Szerokość geograficzna dla pól LOCATION
`longitude`	Float	Nie	Długość geograficzna dla pól LOCATION
`regionCode`	String	Nie	Kod regionu dla pól PHONE
`countryCodes`	[String!]	Nie	Kody krajów ISO dla pól COUNTRY
`customFieldOptionId`	String	Nie	ID opcji dla pól SELECT_SINGLE
`customFieldOptionIds`	[String!]	Nie	ID opcji dla pól SELECT_MULTI
`customFieldReferenceTodoIds`	[String!]	Nie	ID rekordów dla pól REFERENCE

Przykłady typów pól

Pola tekstowe

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

Pola liczbowe

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

Pola wyboru

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

Pola daty

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

Pola lokalizacji

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

Pola walutowe

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

Pola plików

Pola plików używają oddzielnych mutacji:

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

Ustawianie wartości podczas tworzenia rekordu

Możesz ustawić wartości pól niestandardowych podczas tworzenia nowego rekordu:

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

Pola odpowiedzi

Mutacja zwraca wartość logiczną wskazującą na sukces:

Pole	Typ	Opis
`setTodoCustomField`	Boolean!	Prawda, jeśli operacja się powiodła

Wymagane uprawnienia

Użytkownicy muszą mieć uprawnienia do edytowania zarówno rekordu, jak i konkretnego pola niestandardowego:

Rola	Może ustawić wartości pól
`OWNER`	✅ Tak
`ADMIN`	✅ Tak
`MEMBER`	✅ Tak (chyba że ograniczone przez rolę niestandardową)
`CLIENT`	✅ Tak (chyba że ograniczone przez rolę niestandardową)

Dla użytkowników z niestandardowymi rolami projektowymi system wykonuje dwustopniową kontrolę:

Najpierw weryfikuje, czy użytkownik ma dostęp na poziomie projektu
Następnie sprawdza, czy konkretne pole jest oznaczone jako editable w ich konfiguracji roli niestandardowej

Oznacza to, że użytkownik może mieć ogólny dostęp do projektu, ale nadal być ograniczony w edytowaniu niektórych pól w zależności od swojej roli niestandardowej.

Odpowiedzi błędów

Pole niestandardowe nie znalezione

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

Nieautoryzowany dostęp

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

Nieprawidłowa wartość pola

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

Ważne uwagi

Zachowanie upsert: Mutacja tworzy nową wartość pola, jeśli żadna nie istnieje, lub aktualizuje istniejącą wartość
Bezpieczeństwo typów: Podawaj tylko parametry, które odpowiadają typowi pola (np. nie wysyłaj text dla pola NUMBER)
Efekty uboczne: Ustawienie wartości wyzwala:
- Przeliczenia pól formuły
- Zasady automatyzacji
- Powiadomienia webhook
- Wpisy w dzienniku aktywności
- Aktualizacje wykresów
Zachowania specjalne:
- Pola CURRENCY automatycznie obsługują obliczenia konwersji
- Pola REFERENCE aktualizują relacje dwukierunkowe
- Pola FORMULA są tylko do odczytu i nie mogą być ustawiane bezpośrednio (są obliczane automatycznie)
- Pola LOOKUP są tylko do odczytu i nie mogą być ustawiane bezpośrednio (pobierają dane z rekordów referencyjnych)
- Pola BUTTON wyzwalają zdarzenia automatyzacji, gdy są "klikane"
Walidacja: API weryfikuje, że:
- Rekord istnieje w projekcie
- Pole niestandardowe istnieje w tym samym projekcie
- Użytkownik ma uprawnienia do edycji
- Wartość odpowiada wymaganiom typu pola

Odniesienie formatu wartości

Typ pola	Parametr	Format	Przykład
`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

Powiązane punkty końcowe

Lista pól niestandardowych - Pobierz dostępne pola niestandardowe
Utwórz pole niestandardowe - Dodaj nowe pola niestandardowe
Pobierz szczegóły rekordu - Pobierz rekordy z wartościami pól niestandardowych
Masowa aktualizacja rekordów - Zaktualizuj wiele rekordów jednocześnie