Daftar
Kontak Masuk Daftar
Status Sistem

Perbarui nilai field kustom pada catatan menggunakan parameter spesifik tipe untuk setiap tipe field

Atur Nilai Field Kustom

Field kustom memperluas struktur catatan standar Blue dengan data spesifik bisnis. Endpoint ini memungkinkan Anda untuk mengatur atau memperbarui nilai untuk setiap field kustom pada sebuah catatan. Setiap tipe field memerlukan parameter spesifik untuk memastikan integritas data dan validasi yang tepat.

Contoh Dasar

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

Contoh Lanjutan

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

Parameter Input

SetTodoCustomFieldInput

Parameter Tipe Diperlukan Deskripsi
todoId String! ✅ Ya ID catatan yang akan diperbarui
customFieldId String! ✅ Ya ID field kustom
text String Tidak Untuk TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
number Float Tidak Untuk NUMBER, PERCENT, RATING
currency String Tidak Kode mata uang untuk tipe CURRENCY (misalnya, "USD")
checked Boolean Tidak Untuk field CHECKBOX
startDate DateTime Tidak Tanggal mulai untuk field DATE
endDate DateTime Tidak Tanggal akhir untuk field rentang DATE
timezone String Tidak Zona waktu untuk field DATE (misalnya, "America/New_York")
latitude Float Tidak Garis lintang untuk field LOCATION
longitude Float Tidak Garis bujur untuk field LOCATION
regionCode String Tidak Kode wilayah untuk field PHONE
countryCodes [String!] Tidak Kode negara ISO untuk field COUNTRY
customFieldOptionId String Tidak ID opsi untuk field SELECT_SINGLE
customFieldOptionIds [String!] Tidak ID opsi untuk field SELECT_MULTI
customFieldReferenceTodoIds [String!] Tidak ID catatan untuk field REFERENCE

Contoh Tipe Field

Field Teks

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

Field Angka

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

Field Pilihan

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

Field Tanggal

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

Field Lokasi

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

Field Mata Uang

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

Field File

Field file menggunakan mutasi terpisah:

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

Mengatur Nilai Selama Pembuatan Catatan

Anda dapat mengatur nilai field kustom saat membuat catatan baru:

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

Field Respons

Mutasi mengembalikan boolean yang menunjukkan keberhasilan:

Field Tipe Deskripsi
setTodoCustomField Boolean! Benar jika operasi berhasil

Izin yang Diperlukan

Pengguna harus memiliki izin untuk mengedit baik catatan maupun field kustom tertentu:

Peran Dapat Mengatur Nilai Field
OWNER ✅ Ya
ADMIN ✅ Ya
MEMBER ✅ Ya (kecuali dibatasi oleh peran kustom)
CLIENT ✅ Ya (kecuali dibatasi oleh peran kustom)

Untuk pengguna dengan peran proyek kustom, sistem melakukan pemeriksaan dua tingkat:

  1. Pertama, memverifikasi bahwa pengguna memiliki akses tingkat proyek
  2. Kemudian, memeriksa apakah field tertentu ditandai sebagai editable dalam konfigurasi peran kustom mereka

Ini berarti seorang pengguna mungkin memiliki akses proyek umum tetapi tetap dibatasi dari mengedit field tertentu berdasarkan peran kustom mereka.

Respons Kesalahan

Field Kustom Tidak Ditemukan

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

Akses Tidak Sah

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

Nilai Field Tidak Valid

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

Catatan Penting

  • Perilaku Upsert: Mutasi membuat nilai field baru jika tidak ada yang ada, atau memperbarui nilai yang ada
  • Keamanan Tipe: Hanya berikan parameter yang sesuai dengan tipe field (misalnya, jangan kirim text untuk field NUMBER)
  • Efek Samping: Mengatur nilai memicu:
    • Perhitungan ulang field formula
    • Aturan otomatisasi
    • Notifikasi webhook
    • Entri log aktivitas
    • Pembaruan grafik
  • Perilaku Khusus:
    • Field CURRENCY secara otomatis menangani perhitungan konversi
    • Field REFERENCE memperbarui hubungan dua arah
    • Field FORMULA bersifat read-only dan tidak dapat diatur langsung (mereka dihitung secara otomatis)
    • Field LOOKUP bersifat read-only dan tidak dapat diatur langsung (mereka menarik data dari catatan yang dirujuk)
    • Field BUTTON memicu peristiwa otomatisasi saat "diklik"
  • Validasi: API memvalidasi bahwa:
    • Catatan ada dalam proyek
    • Field kustom ada dalam proyek yang sama
    • Pengguna memiliki izin edit
    • Nilai sesuai dengan persyaratan tipe field

Referensi Format Nilai

Tipe Field Parameter Format Contoh
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

Endpoint Terkait

© Blue | Dirancang dengan ❤ di seluruh

Asisten AI

Respon dihasilkan menggunakan AI dan mungkin mengandung kesalahan.

Bagaimana saya bisa membantu Anda?

Tanyakan apa saja tentang Blue atau dokumentasi ini.

Masukkan untuk mengirim • Shift+Masukkan untuk baris baru • ⌘I untuk membuka