Desain direktori integrasi yang dapat diskalakan dari 3 hingga 30 aplikasi

Apa yang perlu dilakukan layar integrasi (dengan kata sederhana)

Orang membuka direktori integrasi untuk satu alasan: menghubungkan alat dan menjaga mereka bekerja tanpa memikirkan tiap hari. Jika layar membuat pengguna menebak apa yang terhubung, apa yang rusak, atau apa yang harus diklik selanjutnya, kepercayaan cepat menurun.

Dengan 3 integrasi, grid logo sederhana bisa bekerja. Dengan 30, itu runtuh: orang berhenti memindai, tiket dukungan meningkat, dan tombol “Connect” menjadi jebakan karena setiap integrasi bisa berada dalam status berbeda.

Setiap kartu integrasi (atau baris) harus menjawab tiga pertanyaan sekilas:

• Apa ini? (Nama plus tujuan singkat)
• Apakah ini bekerja sekarang? (Status jelas plus last check atau last sync)
• Apa yang harus saya lakukan selanjutnya? (Connect, lanjutkan penyiapan, re-auth, manage)

Kebingungan paling banyak datang dari kasus tepi yang terjadi terus-menerus di tim nyata. Seseorang menghubungkan Google dengan akun pribadi alih-alih akun perusahaan. Token Stripe kadaluarsa dan penagihan berhenti sinkron. Workspace Slack terhubung, tetapi scope channel yang diperlukan tidak pernah diberikan, sehingga penyiapan “setengah jadi” walau UI terlihat baik.

Layar yang baik membuat situasi itu jelas. Alih-alih hanya “Connected,” tunjukkan sesuatu seperti “Connected (perlu izin)” atau “Connected to: [email protected],” dan letakkan langkah selanjutnya tepat di kartu. Itu mencegah tebakan dan menjaga daftar tetap terkendali saat bertambah.

Model data sederhana: katalog vs installs vs connections

Cara paling sederhana untuk menskalakan direktori integrasi adalah memisahkan:

• apa yang Anda tawarkan (katalog)
• apa yang diaktifkan setiap workspace (installs)
• akun eksternal atau kredensial yang digunakan (connections)

Ini tetap terbaca pada 3 integrasi dan masih bekerja pada 30.

Tiga objek inti

Integration adalah entri katalog. Bersifat global, tidak terkait ke workspace mana pun.

Install mewakili workspace yang mengaktifkan Integration tersebut (mis. “Slack diaktifkan untuk Workspace A”).

Connection mewakili akun eksternal nyata atau kredensial (mis. “workspace Slack X via OAuth” atau “akun Stripe Y via API key”). Satu Install bisa punya banyak Connections.

Sekumpulan field minimal yang cenderung baik untuk skala:

• Integration: id, key ("slack"), display_name, category, auth_type (oauth/api_key/webhook), docs_hint (teks pendek), created_at
• Install: id, workspace_id, integration_id, status (enabled/disabled), setup_state (not_started/in_progress/complete), created_by, created_at, updated_at
• Connection: id, install_id, label ("Marketing Slack"), connection_status (ok/expired/error), external_account_id (jika diketahui), scopes/permissions_granted, last_success_at, created_at

Konfigurasi vs rahasia (dan apa yang tidak boleh bocor)

Simpan konfigurasi yang terlihat pengguna (channel terpilih, nama webhook, event yang diaktifkan) di Install atau Connection sebagai data biasa. Simpan rahasia (refresh token OAuth, API key, signing secret) hanya di penyimpanan rahasia atau field terenkripsi dengan kontrol akses ketat.

Jangan taruh rahasia, authorization code penuh, atau payload webhook mentah ke dalam log. Jika harus melog, log referensi (connection_id) plus metadata yang aman (HTTP status, error code).

Agar fleksibel di antara OAuth, API key, dan webhook, simpan field spesifik autentikasi di dalam Connection (token metadata vs fingerprint key vs status verifikasi webhook). Simpan state yang ditampilkan UI (enabled dan progres penyiapan) di Install.

Status dan progres penyiapan yang bisa dipahami pengguna

Orang membuka direktori integrasi untuk cepat menjawab tiga hal: apakah berfungsi, seberapa jauh penyiapan, dan apa yang harus saya lakukan selanjutnya. Jika kata status Anda samar, tiket dukungan meningkat dan kepercayaan turun.

Mulailah dengan set status kecil yang bisa Anda pertahankan bertahun-tahun:

• Not set up
• In progress
• Connected
• Needs attention
• Disabled

Lebih baik gunakan status yang diturunkan daripada yang disimpan. Label yang disimpan mengendur: seseorang memperbaiki error, tapi lencana tetap merah. Status turunan dihitung dari fakta yang sudah Anda lacak, seperti apakah token valid, apakah langkah penyiapan yang diperlukan selesai, dan apakah admin menjeda integrasi. Jika Anda menyimpan sesuatu, simpan fakta dasar (last successful sync, last error code), bukan label akhir.

Progres penyiapan bekerja terbaik sebagai checklist pendek, dengan pembagian jelas antara wajib dan opsional. Modelkan sebagai definisi langkah (statis, per integration) plus hasil langkah (per install).

Contoh: Slack mungkin mewajibkan “Authorize workspace” dan “Select channels,” dengan langkah opsional seperti “Enable message previews.” UI bisa menunjukkan “2 dari 3 langkah wajib selesai” sambil menjaga item opsional mudah ditemukan tanpa memblokir.

Beberapa connection di bawah satu integration bisa membuat direktori berantakan jika tidak direncanakan. Tampilkan satu kartu per integration, tunjukkan jumlah connection, dan gabungkan status secara jujur. Jika ada connection yang rusak, tampilkan “Needs attention” dengan petunjuk seperti “1 dari 4 workspace perlu re-auth.” Tampilan ringkasan tetap bersih, namun mencerminkan realita.

Izin dan peran tanpa membuatnya rumit

Izin integrasi menjadi berantakan saat semuanya dianggap sebagai satu sakelar. Lebih jelas memisahkan:

• siapa yang bisa melihat integrasi
• siapa yang bisa mengkonfigurasinya
• siapa yang bisa menggunakannya sehari-hari

Mulailah dengan pemeriksaan peran ringan yang berlaku di mana-mana. Untuk banyak produk, tiga peran cukup: Admin, Manager, dan Member. Admin bisa melakukan apa saja. Manager bisa menyiapkan sebagian besar integrasi untuk tim mereka. Member bisa menggunakan integrasi yang sudah diaktifkan, tetapi tidak bisa mengubah pengaturan.

Kemudian tambahkan flag izin per-integrasi hanya saat diperlukan. Sebagian besar integrasi (calendar, chat) bisa mengikuti aturan peran default. Yang sensitif (payments, payroll, exports) harus meminta pemeriksaan tambahan seperti “Payments admin” atau “Billing manager.” Simpan ini sebagai boolean sederhana pada install, bukan seluruh sistem peran baru.

Pemetaan yang tetap terbaca:

• View: Admin, Manager, Member
• Configure: Admin, Manager (Member dapat melihat tapi tidak bisa connect atau edit)
• Use: Siapa saja di workspace setelah diaktifkan (kecuali dibatasi)
• Sensitive override: Hanya pengguna dengan flag khusus yang bisa mengkonfigurasi atau memicu tindakan

Audit tidak perlu berat, tapi harus ada. Lacak cukup agar bisa menjawab pertanyaan dukungan dan keamanan dengan cepat: siapa yang menghubungkan, kapan kredensial berubah, dan siapa yang menonaktifkan. Panel “Activity” di halaman detail dengan 5–20 event terbaru biasanya sudah cukup.

Contoh: Stripe mungkin terlihat oleh semua orang, tetapi hanya Admin (atau pengguna bertanda “Billing manager”) yang bisa menghubungkannya, merotasi kunci, atau menonaktifkan payout. Slack mungkin mengizinkan Manager untuk connect, sementara Member tetap bisa menerima notifikasi Slack setelah diaktifkan.

Tata letak UI yang masih bekerja pada 30 integrasi

Dengan 3 integrasi, Anda bisa menampilkan semuanya. Dengan 30, direktori harus cepat menjawab satu pertanyaan: “Mana yang berfungsi, dan apa yang harus saya lakukan selanjutnya?” Pendekatan paling bersih adalah memisahkan pemindaian dari tindakan.

Jaga tampilan direktori fokus pada keputusan cepat. Dorong kontrol yang lebih berat ke halaman detail di balik satu tombol “Manage”.

Di daftar, tampilkan hanya yang mendukung klik selanjutnya:

• Ikon, nama, dan deskripsi satu baris (jaga panjang konsisten)
• Pil status yang jelas (Connected, Needs setup, Error, Disabled)
• Satu tombol aksi utama
• Tombol sekunder “Manage” untuk sisanya

Anatomi kartu penting karena membangun memori otot. Aksi utama harus selalu berarti “langkah selanjutnya” berdasarkan status: Connect untuk baru, Continue setup untuk setengah jadi, Reconnect saat auth kadaluarsa, dan Manage saat semuanya sehat. Hindari dua tombol utama yang sama nyaring di setiap kartu. Itu membuat halaman terasa berantakan.

Contoh:

• Jika “Google” Connected, aksi utama bisa Manage.
• Jika “Slack” gagal tadi malam, tunjukkan Error dan jadikan aksi utama Reconnect.
• Jika “Stripe” setengah jadi, tunjukkan Needs setup dan Continue setup.

Empty state harus memberi panduan tanpa menumpahkan manual ke layar:

• Tidak ada integrasi terpasang: sarankan 2–3 pilihan populer dan apa yang mereka buka
• Tidak ada hasil pencarian: beri tip singkat seperti “coba ‘CRM’ atau ‘billing’”
• Penyiapan pertama kali: satu kalimat tentang izin dan data apa yang akan diakses

Ini menjaga halaman tetap tenang pada 30 integrasi karena setiap kartu menjawab: apa ini, apakah oke, dan apa yang harus saya lakukan sekarang?

Halaman detail: alur penyiapan, connections, dan kontrol

Daftar direktori membawa orang ke integrasi yang tepat. Halaman detail adalah tempat mereka memutuskan: menyiapkannya, memperbaikinya, atau mematikannya. Jaga struktur halaman konsisten di setiap integrasi, walau pekerjaan backend berbeda.

Mulailah dengan overview ringkas: nama integrasi, deskripsi satu baris, dan label status jelas (Connected, Needs attention, Disabled). Tambahkan garis “Setup progress” kecil agar pengguna tahu apakah mereka tinggal satu langkah atau masih di awal.

Alur penyiapan yang terasa aman

Wizard sederhana bekerja baik: 3–6 langkah, satu layar per langkah, dengan tombol “Back” selalu tersedia. Namai langkah dengan bahasa yang mudah dimengerti (Connect account, Choose workspace, Pick data to sync, Confirm). Jika langkah punya pilihan opsional, beri label opsional daripada menyembunyikannya.

Jika penyiapan bisa dijeda, katakan dengan jelas: “Anda bisa menyelesaikannya nanti. Kami akan menyimpan pilihan Anda.” Itu mengurangi kekhawatiran saat meninggalkan proses.

Connections dan kontrol yang tidak akan disesali pengguna

Tampilkan Connections sebagai tabel kecil: nama akun, connected by (pengguna), tanggal dibuat, dan last sync.

Untuk “next sync,” hindari janji yang tak bisa dipenuhi (mis. waktu pasti). Gunakan kata yang bisa Anda pertanggungjawabkan, seperti “Next sync: scheduled soon” atau “Next sync: within the next hour,” berdasarkan apa yang sistem Anda benar-benar jamin.

Jauhkan aksi berisiko dari jalur utama. Letakkan aksi utama di atas (Continue setup, Reconnect). Letakkan Disable dan Disconnect di bagian “Danger zone” terpisah di bawah dengan penjelasan singkat dampaknya. Jika Anda mendukung peran, katakan dalam satu kalimat (mis. “Hanya admin yang bisa disconnect”).

Tambahkan log aktivitas kecil: event terbaru (connected, token refreshed, sync failed), timestamp, dan pesan error singkat yang dapat disalin pengguna ke tiket dukungan.

Langkah demi langkah: menambah integrasi baru end-to-end

Menambahkan integrasi lebih mudah saat Anda memperlakukannya seperti produk kecil. Perlu listing, cara menghubungkan, tempat menyimpan connection, dan hasil yang jelas untuk sukses atau gagal.

1) Mulai dengan entri katalog

Tambahkan integrasi ke katalog agar muncul di direktori bahkan sebelum ada yang menghubungkannya. Sertakan nama jelas, deskripsi pendek, ikon, dan satu atau dua kategori (Messaging, Payments). Tulis ekspektasi penyiapan dengan kata sederhana, seperti “Connect an account” dan “Choose a workspace.” Di sini juga Anda mendefinisikan kebutuhan integrasi nanti (OAuth scopes, field wajib, fitur yang didukung).

2) Bangun metode koneksi

Pilih metode koneksi paling sederhana yang cocok dengan penyedia:

1. OAuth saat pengguna harus masuk dan menyetujui akses (umum untuk Google, Slack)
2. API key saat pengguna bisa menempel token dari penyedia
3. Webhooks saat penyedia mendorong event ke aplikasi Anda

3) Simpan kredensial dan buat record Connection

Saat pengguna menyelesaikan flow, buat record Connection yang terkait ke workspace atau akun mereka, bukan hanya pengguna. Simpan kredensial dengan aman (enkripsi saat istirahat dan hindari menampilkan secret penuh lagi). Simpan dasar yang dibutuhkan dukungan: provider account ID, waktu dibuat, siapa yang menghubungkan, dan izin yang diberikan.

4) Jalankan pemeriksaan pertama dan set status + progres

Jalankan tes sederhana segera (untuk Stripe: ambil detail akun). Jika lulus, tampilkan Connected dan tandai progres sebagai siap. Jika lulus sebagian (terhubung tapi izin kurang), beri tanda Needs attention dan tunjukkan perbaikan yang jelas.

5) Tentukan apa yang dilihat pengguna saat gagal

Tampilkan satu pesan jelas, satu tindakan yang direkomendasikan, dan fallback aman. Contoh: “We couldn’t reach Stripe. Check the API key or try again.” Jaga direktori tetap berguna meski satu integrasi rusak.

Jika Anda membangun di Koder.ai (koder.ai), Anda bisa merancang katalog, alur penyiapan, dan aturan status di Planning Mode terlebih dahulu, lalu menghasilkan UI dan backend dari rencana itu.

Error, retry, dan riwayat yang ramah dukungan

Integrasi gagal karena alasan-alasan membosankan. Jika direktori Anda tidak bisa menjelaskan alasan itu dengan jelas, pengguna menyalahkan aplikasi Anda dan dukungan tidak punya sesuatu untuk ditindaklanjuti.

Kelompokkan kegagalan ke dalam bucket yang cocok dengan perbaikan nyata: login kadaluarsa, izin hilang, outage penyedia, atau rate limit. Simpan kode error internal yang rinci, tapi tunjukkan label singkat yang mudah dimengerti pengguna.

Saat sesuatu rusak, pesan harus menjawab tiga hal: apa yang terjadi, apa yang harus dilakukan pengguna, dan apa yang sistem Anda akan lakukan selanjutnya. Contoh: “Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect.” Lebih tenang dan bisa ditindaklanjuti dibandingkan raw API error.

Aturan retry yang tidak mengganggu pengguna

Auto-retry hanya saat pengguna tidak bisa memperbaikinya sendiri. Satu set aturan sederhana cukup:

• Provider down atau network error: auto-retry dengan backoff, simpan last success time
• Rate limited: jeda, retry nanti, dan tampilkan “Paused (rate limit)”
• Auth expired: hentikan retry dan minta pengguna reconnect
• Missing permissions: hentikan dan tunjukkan izin pasti yang diperlukan
• Konfigurasi buruk: hentikan dan tunjukkan setting yang harus diisi

Status menjadi kadaluarsa kecuali Anda menyegarkannya. Tambahkan job health check ringan yang secara berkala memastikan token masih bekerja, last sync berjalan, dan badge direktori sesuai realita.

Riwayat yang berguna untuk dukungan

Simpan riwayat event kecil per install. Anda tidak perlu log penuh, cukup breadcrumb yang membantu: timestamp, event (“token refreshed”, “sync failed”), alasan singkat, dan siapa yang memicunya (pengguna atau sistem). Tambahkan field catatan internal agar dukungan dapat mencatat apa yang mereka ubah dan mengapa.

Pencarian, filter, dan mengorganisasi direktori

Direktori cepat berantakan setelah jumlah aplikasi melampaui beberapa. Tujuannya sederhana: bantu orang menemukan apa yang mereka butuhkan dalam hitungan detik, dan bantu mereka melihat masalah tanpa membuka setiap kartu.

Mulailah dengan pencarian dasar pada nama integrasi dan kategori. Kebanyakan pengguna mengetik apa yang sudah mereka tahu (“Slack”, “Stripe”), jadi pencocokan nama lebih penting daripada perankingan rumit. Pencarian kategori membantu saat mereka hanya tahu tugasnya (payments, messaging).

Filter harus mencerminkan niat nyata. Tiga ini biasanya mencakup sebagian besar kasus:

• Connected (bekerja sekarang)
• Needs attention (error, token kadaluarsa, izin hilang)
• Not set up (tersedia tapi belum ada install)

Untuk mengatur daftar, pilih satu pengelompokan utama dan konsisten. Pengelompokan kategori bekerja baik pada jumlah besar (CRM, Payments, Messaging). Popularitas bisa berguna juga, tapi hanya jika mencerminkan basis pengguna Anda, bukan pemasaran. Default praktis: tampilkan yang paling sering digunakan dulu, lalu kelompokkan sisanya per kategori.

Anda juga perlu rencana jelas untuk “tidak semua orang harus melihat semuanya.” Jika integrasi ada di balik feature flag atau tier rencana, sembunyikan untuk kebanyakan pengguna atau tampilkan dalam kondisi disabled dengan alasan singkat seperti “Business plan.” Hindari menampilkan halaman penuh kartu abu-abu yang membuat layar terasa rusak.

Jaga performa tetap cepat dengan memisahkan load daftar dan detail. Paginate atau virtualize daftar agar tidak merender 30 kartu berat sekaligus, dan lazy-load detail hanya saat pengguna membuka integrasi. Direktori bisa menampilkan field ringkasan (Slack: Connected, Google: Needs attention, Stripe: Not set up) sementara halaman detail mengambil riwayat connection penuh.

Contoh: Slack, Google, dan Stripe di aplikasi nyata

Bayangkan aplikasi workspace tim bernama Pinework. Ia punya dua peran: Admin dan Member. Admin bisa menghubungkan tool dan mengubah pengaturan. Member bisa menggunakan tool terhubung tapi tidak bisa menambah atau menghapus.

Di direktori integrasi Pinework, setiap kartu menampilkan label jelas (Connected, Needs setup, Error), satu baris “apa yang dilakukannya”, dan progres penyiapan seperti “2 dari 3 langkah.” Orang bisa tahu apa yang bekerja dan apa yang tertunda tanpa banyak klik.

Slack digunakan untuk notifikasi. Seorang Admin membuka Slack dan melihat: Status: Connected, Setup: “3 dari 3 langkah.” Member juga melihat Slack, tapi aksi utama dinonaktifkan dan bertuliskan “Ask an Admin to manage.” Jika Slack terputus, Member tetap bisa melihat apa yang rusak, tapi tidak kontrol reconnect.

Google digunakan untuk kalender. Pinework mendukung dua departemen, jadi mengizinkan beberapa connection. Kartu Google menampilkan: Status: Connected (2 accounts). Di bawahnya, baris pendek mencantumkan “Marketing Calendar” dan “Support Calendar.” Penyiapan bisa tetap lengkap, dan halaman detail menunjukkan dua connection terpisah sehingga Admin bisa mencabut salah satunya.

Stripe digunakan untuk penagihan. Penyiapan setengah umum: akun terhubung, tapi webhooks belum selesai. Kartu menampilkan: Status: Needs setup, Progress: “2 dari 3 langkah,” dengan peringatan seperti “Payments may not sync.” Tampilan detail menjelaskan langkah tersisa:

• Connect Stripe account (selesai)
• Choose billing plan mapping (selesai)
• Add webhook endpoint (belum selesai)

Itu menghindari situasi menyakitkan “terlihat terhubung tapi tidak ada yang bekerja.”

Kesalahan umum yang membuat integrasi sulit dikelola

Direktori integrasi biasanya rusak saat aplikasi tumbuh dari beberapa integrasi menjadi puluhan. Masalahnya jarang karena “teknologi besar.” Mereka adalah kesalahan kecil pada pelabelan dan pemodelan yang membingungkan orang setiap hari.

Masalah umum adalah mencampur “installed” vs “connected.” Installed biasanya berarti “tersedia di workspace Anda.” Connected berarti kredensial nyata ada dan data bisa mengalir. Saat itu kabur, pengguna mengklik integrasi yang terlihat siap dan menemui jalan buntu.

Kesalahan lain adalah menciptakan terlalu banyak status. Tim mulai dengan lencana sederhana, lalu menambahkan edge case: pending, verifying, partial, paused, degraded, blocked, expiring, dan lainnya. Seiring waktu label-label itu menyimpang dari realita karena tidak ada yang mempertahankannya konsisten. Jaga set kecil yang terikat pada pengecekan yang benar-benar bisa Anda jalankan, seperti Not connected, Connected, Needs attention.

Izin tersembunyi juga bermasalah. Seseorang menghubungkan akun, kemudian menemukan integrasi punya akses yang lebih luas dari yang diharapkan. Perjelas scope sebelum langkah “Connect” terakhir, dan tampilkan lagi di halaman detail agar admin bisa mengaudit.

Jangan anggap satu connection per integration

Banyak aplikasi butuh banyak connection: dua workspace Slack, beberapa akun Stripe, atau akun Google bersama plus akun pribadi. Jika Anda memaksa “satu integration = satu connection,” Anda akan berakhir dengan solusi buruk nanti.

Rencanakan untuk:

• Banyak connection di bawah satu integration
• “Default” connection yang jelas (jika diperlukan)
• Connection bersama vs pribadi
• Tempat untuk melihat siapa yang menghubungkan

Jaga tampilan daftar tetap ringan. Saat Anda mengisinya dengan log, pemetaan field, dan deskripsi panjang, pemindaian melambat. Gunakan daftar untuk nama, tujuan singkat, dan progres penyiapan. Letakkan riwayat dan pengaturan lanjutan di halaman detail integrasi.

Daftar cepat dan langkah berikutnya

Direktori integrasi yang skalabel bermuara pada model sederhana dan UI yang jujur. Jika pengguna bisa menjawab tiga pertanyaan dengan cepat, sistem terasa dapat diprediksi: apa yang terhubung, apa yang rusak, dan apa yang harus saya lakukan selanjutnya?

Daftar periksa sebelum rilis:

• Pisahkan model: Integration (katalog) vs Install (diaktifkan di workspace) vs Connection (OAuth token, API key, atau webhook). Tambahkan Event hanya jika Anda membutuhkan riwayat audit dan dukungan.
• Turunkan status: hitung label dari pengecekan (token valid, scopes OK, webhook reachable) plus langkah penyiapan yang selesai, agar lencana selalu akurat.
• Jaga tampilan daftar mudah dipindai: setiap baris menunjukkan nama, label status jelas, dan satu “aksi selanjutnya” (Connect, Continue, Reconnect, Fix permissions).
• Buat aksi lifecycle sebagai fitur utama: Connect, Continue setup, Reconnect, Disable, dan Disconnect harus mudah ditemukan, dengan konfirmasi singkat.
• Buat izin terlihat dan dapat diaudit: tunjukkan siapa yang bisa connect atau disconnect, dan catat siapa mengubah apa dan kapan.

Selanjutnya, pilih tiga integrasi yang sudah Anda kenal baik dan modelkan end-to-end: alat chat (OAuth), koneksi akun gaya Google (OAuth dengan scopes), dan alat pembayaran (API key plus webhooks). Jika model Anda bisa mengekspresikan ketiganya tanpa kasus khusus, biasanya akan skala ke 30.