Buat Field Kustom

Tambahkan field kustom baru untuk memperluas struktur data proyek Anda dengan konfigurasi spesifik tipe

Buat Field Kustom

Field kustom memungkinkan Anda menyesuaikan Blue dengan kebutuhan bisnis spesifik Anda dengan menambahkan field data terstruktur ke catatan Anda. Endpoint ini membuat field kustom baru dengan konfigurasi yang spesifik untuk setiap tipe field.

Contoh Dasar

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

Contoh Lanjutan

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

Parameter Input

CreateCustomFieldInput

Parameter	Tipe	Diperlukan	Deskripsi
`name`	String!	✅ Ya	Nama tampilan dari field kustom
`type`	CustomFieldType!	✅ Ya	Tipe field (lihat tipe di bawah)
`description`	String	Tidak	Deskripsi opsional yang menjelaskan tujuan field
`min`	Float	Tidak	Nilai minimum untuk field NUMBER, RATING, PERCENT
`max`	Float	Tidak	Nilai maksimum untuk field NUMBER, RATING, PERCENT
`currency`	String	Tidak	Kode mata uang ISO untuk field CURRENCY
`prefix`	String	Tidak	Prefiks teks untuk field UNIQUE_ID
`isDueDate`	Boolean	Tidak	Apakah field DATE mewakili tanggal jatuh tempo
`formula`	JSON	Tidak	Konfigurasi formula untuk field FORMULA
`referenceProjectId`	String	Tidak	ID proyek target untuk field REFERENCE
`referenceMultiple`	Boolean	Tidak	Izinkan pemilihan ganda dalam field REFERENCE
`referenceFilter`	TodoFilterInput	Tidak	Opsi filter untuk field REFERENCE
`lookupOption`	CustomFieldLookupOptionInput	Tidak	Konfigurasi untuk field LOOKUP
`timeDurationDisplay`	CustomFieldTimeDurationDisplayType	Tidak	Format tampilan untuk TIME_DURATION
`timeDurationTargetTime`	Float	Tidak	Waktu target dalam detik untuk TIME_DURATION
`timeDurationStartInput`	CustomFieldTimeDurationInput	Tidak	Pemicu awal untuk TIME_DURATION
`timeDurationEndInput`	CustomFieldTimeDurationInput	Tidak	Pemicu akhir untuk TIME_DURATION
`buttonType`	String	Tidak	Tipe aksi tombol untuk field BUTTON
`buttonConfirmText`	String	Tidak	Prompt konfirmasi untuk field BUTTON
`useSequenceUniqueId`	Boolean	Tidak	Gunakan penomoran berurutan untuk UNIQUE_ID
`sequenceDigits`	Int	Tidak	Jumlah digit dalam urutan (misalnya, 5 → 00001)
`sequenceStartingNumber`	Int	Tidak	Nomor awal untuk urutan
`currencyFieldId`	String	Tidak	Field mata uang referensi untuk CURRENCY_CONVERSION
`conversionDate`	String	Tidak	Tanggal konversi untuk CURRENCY_CONVERSION
`conversionDateType`	String	Tidak	Tipe tanggal konversi untuk CURRENCY_CONVERSION
`metadata`	JSON	Tidak	Metadata tambahan untuk field kustom

Nilai CustomFieldType

Nilai	Deskripsi	Parameter Diperlukan
`TEXT_SINGLE`	Input teks satu baris	Tidak ada
`TEXT_MULTI`	Area teks multi-baris	Tidak ada
`SELECT_SINGLE`	Dropdown pemilihan tunggal	Create options separately
`SELECT_MULTI`	Dropdown pemilihan ganda	Create options separately
`CHECKBOX`	Checkbox boolean	Tidak ada
`RATING`	Field penilaian bintang	Optional: `max` (default: 5)
`PHONE`	Nomor telepon dengan validasi	Tidak ada
`NUMBER`	Input numerik	Optional: `min`, `max`
`CURRENCY`	Jumlah mata uang	Optional: `currency`, `min`, `max`
`PERCENT`	Persentase (0-100)	Optional: `min`, `max`
`EMAIL`	Email dengan validasi	Tidak ada
`URL`	URL web dengan validasi	Tidak ada
`UNIQUE_ID`	Identifikasi yang dihasilkan secara otomatis	Optional: `prefix`, `useSequenceUniqueId`
`LOCATION`	Koordinat geografis	Tidak ada
`FILE`	Lampiran file	Tidak ada
`DATE`	Pemilih tanggal	Optional: `isDueDate`
`COUNTRY`	Pemilih negara	Tidak ada
`FORMULA`	Field yang dihitung	Required: `formula`
`REFERENCE`	Tautan ke catatan lain	Required: `referenceProjectId`
`LOOKUP`	Ambil data dari referensi	Required: `lookupOption`
`TIME_DURATION`	Pelacakan waktu	Required: duration inputs (see below)
`BUTTON`	Tombol aksi	Optional: `buttonType`, `buttonConfirmText`
`CURRENCY_CONVERSION`	Konverter mata uang	Special configuration

Contoh Konfigurasi Tipe Field

Field Angka dengan Pembatasan

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

Field Mata Uang

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

Field Tanggal dengan Flag Tanggal Jatuh Tempo

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

Field Referensi

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

Field Lookup

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 Unik dengan Urutan

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

Field Durasi Waktu

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

Tipe Durasi Waktu yang Valid

TODO_CREATED_AT - Ketika catatan dibuat
TODO_CUSTOM_FIELD - Ketika field kustom berubah
TODO_DUE_DATE - Ketika tanggal jatuh tempo diatur/diubah
TODO_MARKED_AS_COMPLETE - Ketika catatan ditandai lengkap
TODO_MOVED - Ketika catatan dipindahkan ke daftar yang berbeda
TODO_TAG_ADDED - Ketika tag ditambahkan
TODO_ASSIGNEE_ADDED - Ketika penugasan ditambahkan

Membuat Opsi Pilihan

Setelah membuat field SELECT_SINGLE atau SELECT_MULTI, tambahkan opsi:

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

Field Respons

CustomField

Field	Tipe	Deskripsi
`id`	String!	Pengidentifikasi unik
`uid`	String!	ID unik yang ramah pengguna
`name`	String!	Nama tampilan
`type`	CustomFieldType!	Tipe field
`description`	String	Deskripsi field
`position`	Float!	Posisi urutan tampilan
`createdAt`	DateTime!	Timestamp pembuatan
`updatedAt`	DateTime!	Timestamp pembaruan terakhir
`min`	Float	Nilai minimum (jika berlaku)
`max`	Float	Nilai maksimum (jika berlaku)
`currency`	String	Kode mata uang (tipe CURRENCY)
`prefix`	String	Prefiks ID (tipe UNIQUE_ID)
`isDueDate`	Boolean	Flag tanggal jatuh tempo (tipe DATE)
`formula`	JSON	Konfigurasi formula (tipe FORMULA)
`referenceProjectId`	String	Proyek yang dirujuk (tipe REFERENCE)
`customFieldLookupOption`	CustomFieldLookupOption	Konfigurasi lookup (tipe LOOKUP)

Izin yang Diperlukan

Membuat field kustom memerlukan akses proyek:

Peran	Dapat Membuat Field Kustom
`OWNER`	✅ Ya
`ADMIN`	✅ Ya
`MEMBER`	✅ Ya
`CLIENT`	❌ Tidak

Catatan: Peran kustom mungkin memiliki batasan tambahan pada manajemen field.

Respons Kesalahan

Tipe Field Tidak Valid

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

Proyek Referensi Tidak Ditemukan

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

Konfigurasi Diperlukan Hilang

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

Catatan Penting

Posisi Field: Secara otomatis dihitung untuk muncul di akhir field yang ada
Batas Field: Proyek mungkin memiliki batasan pada jumlah field kustom
Ketersediaan Segera: Field yang dibuat segera tersedia untuk digunakan
Efek Samping: Membuat field memicu:
- Entri log aktivitas
- Pembaruan waktu nyata kepada pengguna yang terhubung
- Notifikasi webhook
- Pekerjaan latar belakang untuk field FORMULA, LOOKUP, dan UNIQUE_ID
Pertimbangan Khusus:
- Field REFERENCE memerlukan akses ke proyek target
- Field LOOKUP bergantung pada field REFERENCE yang ada
- Field FORMULA tidak dapat merujuk pada dirinya sendiri
- Urutan UNIQUE_ID diproses secara asinkron
- Field SELECT memerlukan opsi yang dibuat secara terpisah
Penamaan: Nama field harus jelas dan deskriptif seperti yang muncul di UI

Endpoint Terkait

Daftar Field Kustom - Lihat field kustom yang ada
Perbarui Field Kustom - Modifikasi properti field
Hapus Field Kustom - Hapus field kustom
Buat Opsi Field - Tambahkan opsi ke field pilihan
Atur Nilai Field Kustom - Atur nilai pada catatan