Addon Enable / Opt-in per Tenant
Menyalakan addon per workspace dari menu Addons, mematikannya beserta perilaku soft-block, serta memahami apa yang berubah di menu Integration dan editor BPMN.
Addon tidak lagi otomatis tersedia begitu terpasang di sebuah instance. Sekarang setiap workspace menyalakan sendiri addon yang ingin dipakainya (opt-in), dan addon yang belum dinyalakan tidak bisa dikonfigurasi maupun dipanggil dari proses. Katalognya tetap terbuka — semua addon yang boleh dilihat tetap tampil — yang berubah hanya izin memakainya.
Pengaturannya ada di menu Addons, pada grup ADMINISTRATION di sidebar Studio.
Menu Addons adalah kendali admin workspace, bukan setting end-user. Anda membutuhkan role Owner atau Admin SOP pada workspace tersebut untuk menyalakan atau mematikan addon.
Prasyarat
- Role Owner atau Admin SOP pada workspace yang bersangkutan.
- Addon yang dituju sudah terpasang di instance dan terlihat di katalog workspace Anda.
Yang dibaca adalah role keanggotaan workspace, bukan role realm Keycloak. Akun dengan platform_owner atau license_admin di Keycloak tetap ditolak 403 bila di workspace tersebut ia hanya berstatus member. Ini penyebab 403 yang paling sering salah didiagnosis sebagai bug — lihat Troubleshooting.
Dua Hal yang Sering Tertukar
Fitur ini punya dua sumbu berbeda. Hampir semua kebingungan datang dari menganggapnya satu hal.
| Visibility — boleh melihat | Activation — sudah menyalakan | |
|---|---|---|
| Melekat pada | addon | pasangan (addon, workspace) |
| Diatur oleh | privat/publik, properti addon | tombol Enable for this workspace |
| Siapa yang boleh mengubah | Owner di workspace pemilik addon | Owner atau Admin SOP di workspace itu sendiri |
| Efek kalau dimatikan | addon hilang dari katalog workspace lain | addon tidak bisa dipakai di workspace ini saja |
Activation adalah yang Anda pakai sehari-hari. Sumbu visibility baru relevan bila workspace Anda menerbitkan addon sendiri — dan pada rilis ini kendalinya belum terbuka, lihat Batasan Fase 1.
Membuka Menu Addons
Dari sidebar Studio, buka grup ADMINISTRATION, lalu pilih Addons.
Halaman ini menampilkan seluruh addon yang boleh dilihat workspace Anda, bukan hanya yang aktif. Addon yang belum dinyalakan tetap tampil dengan status Disabled — itu keadaan normal, bukan tanda ada yang salah.
Anatomi Kartu Addon
| Bagian | Keterangan |
|---|---|
| Nama | Nama tampilan addon. |
slug · versi | Kunci teknis dan versi addon, dibaca dari paket addon. Nilai inilah yang muncul di pesan error runtime. |
| Badge status | Enabled (hijau) atau Disabled — status untuk workspace ini saja. |
| Badge asal | Platform addon untuk addon yang dipasang admin instance. Addon yang diterbitkan sebuah workspace ditandai berbeda. |
| Deskripsi | Diambil dari index.json di dalam paket addon, bukan diketik lewat form. |
| Used by N integration configurations | Jumlah konfigurasi integrasi di workspace ini yang menunjuk addon tersebut. Perlakukan sebagai indikasi, bukan angka pasti — lihat Batasan Fase 1. |
| Enable for this workspace | Switch aktivasi. Hanya tampil aktif bagi Owner / Admin SOP. |
Menyalakan Addon
Alurnya searah: nyalakan di menu Addons, lalu konfigurasikan di menu Integration. Menu Addons memang bukan tempat mengisi kredensial.
- Buka Addons, cari kartu addon yang dituju.
- Nyalakan switch Enable for this workspace.
- Badge kartu berubah menjadi Enabled. Tidak ada dialog konfirmasi — menyalakan addon tidak merusak apa pun yang sedang berjalan.
Setelah aktif, addon langsung muncul sebagai entri baru di menu Integration — di sanalah kredensial dan endpoint-nya diisi.
Addon yang sudah Enabled tetapi belum punya satu pun konfigurasi adalah keadaan yang sah, bukan setengah jadi. Enable memberi izin memakai; konfigurasi adalah langkah terpisah.
Menyalakan addon yang sudah menyala aman diulang — tidak membuat aktivasi ganda.
Yang Berubah di Menu Integration
Halaman All Integrations (/{workspace}/integration) memisahkan integrasi bawaan dari addon.
| Seksi | Isi |
|---|---|
| BUILT-IN | Integrasi bawaan platform (API Call, Auth Token, Database, Email, Odoo, Telegram, Template, WhatsApp). Tidak terpengaruh opt-in. |
| ADDONS | Hanya addon yang sudah dinyalakan di workspace ini. |
| TURNED OFF, STILL CONFIGURED | Addon yang dimatikan tetapi konfigurasinya masih tersimpan. |
Tombol Manage Addons di kanan atas membawa Anda langsung ke menu Addons.
Workspace yang belum menyalakan addon apa pun mendapat empty state yang menyebutkan jalan keluarnya, bukan halaman kosong yang tidak bisa dibedakan dari gagal muat:
Mematikan Addon
- Menu Addons, matikan switch Enable for this workspace.
- Muncul dialog konfirmasi "Disable
<nama addon>?". - Pilih Disable addon untuk melanjutkan, atau Cancel untuk membatalkan.
Berbeda dengan menyalakan, mematikan selalu meminta konfirmasi. Isi dialognya menjelaskan bahwa penjagaannya bersifat lunak (soft-block):
- Proses yang sedang berjalan tetap diselesaikan, tidak dihentikan di tengah jalan.
- Yang ditolak adalah eksekusi baru yang memakai addon tersebut, sampai addon dinyalakan kembali.
- Konfigurasi lama tidak dihapus.
Konfigurasi yang tertinggal itu tetap terlihat di halaman Integration, pada seksi Turned off, still configured:
Tiap kartu di seksi ini berbadge Addon turned off disertai keterangan bahwa konfigurasinya dipertahankan tetapi tidak lagi dijalankan. Menyalakan addonnya kembali memulihkan keadaan semula tanpa perlu konfigurasi ulang.
Pada instance bersama, jangan menekan Disable untuk addon yang sedang dipakai workspace lain sebelum memastikannya. Aktivasi memang terpisah per workspace, tetapi konfigurasi dan proses berjalan tidak selalu jelas pemiliknya dari halaman ini.
Yang Berubah di Editor BPMN
Addon masuk ke proses lewat panel Integrations pada sebuah elemen BPMN — bukan lewat palette di sisi kiri, yang tetap berisi elemen BPMN standar.
Pilih sebuah service task, lalu buka panel Integrations-nya:
Tombol Add Integration membuka daftar addon yang bisa dipilih. Daftar ini hanya memuat addon yang sudah dinyalakan di workspace tersebut — addon lain di katalog tidak muncul sama sekali:
Dua hal yang perlu diketahui saat membaca daftar ini:
- Kelompoknya diberi judul memakai deskripsi addon, bukan namanya. Cocokkan lewat deskripsi dan versinya.
- Addon yang sudah enabled belum tentu menyumbang action. Sebagian addon hanya menyediakan komponen tampilan dan akan tampil sebagai kelompok tanpa satu pun action yang bisa dipilih.
Integrasi yang terlanjur terpasang pada sebuah elemen tetap terlihat dan masih berstatus Active di editor walaupun addonnya sudah dimatikan workspace-wide. Ini disengaja: penolakannya terjadi saat eksekusi, dan kalau panelnya ikut hilang, satu-satunya petunjuk kenapa proses gagal saat runtime hilang bersamanya.
Aktivasi Terkunci per Workspace
Menyalakan addon adalah keputusan satu workspace, bukan keputusan akun dan bukan keputusan instance. Akun yang sama, di workspace lain, akan melihat addon yang sama dalam keadaan Disabled:
Konsekuensi praktisnya: bila organisasi Anda memisahkan lingkungan uji dan produksi ke dua workspace berbeda, addon harus dinyalakan di masing-masing. Menyalakannya di satu workspace tidak berpengaruh pada yang lain. Untuk TEST dan LIVE di dalam satu workspace yang sama, satu kali enable berlaku untuk keduanya.
Menerbitkan Addon dari Workspace
Tombol Publish addon di kanan atas menu Addons memungkinkan sebuah workspace menerbitkan addonnya sendiri.
| Kolom | Keterangan |
|---|---|
| Addon key | Dipakai di URL dan path instalasi. Hanya huruf, angka, tanda hubung, dan garis bawah. |
| Addon package | Berkas .zip paket addon. Arsipnya wajib memuat index.json — nama, versi, dan deskripsi dibaca dari sana, bukan diketik di form. |
Dialog ini menyatakan sendiri batasannya: addon yang diterbitkan sebuah workspace tetap privat pada rilis ini dan hanya terlihat di workspace penerbitnya. Tidak ada pilihan mempublikkannya ke workspace lain dari layar ini.
Troubleshooting
| Gejala | Penyebab paling mungkin | Tindakan |
|---|---|---|
| Addon tidak muncul di menu Integration | Belum di-enable di workspace ini. | Buka Addons, nyalakan switch-nya. |
| Addon tidak muncul di picker Add Integration editor BPMN | Belum di-enable, atau addonnya memang tidak menyediakan action. | Cek statusnya di menu Addons lebih dulu; kalau sudah Enabled tapi tetap tanpa action, addon tersebut bukan addon service task. |
| Addon tidak muncul di menu Addons sama sekali | Addon privat milik workspace lain, atau memang belum terpasang di instance ini. | Hubungi pemilik addon atau admin instance. |
| Menekan Enable dijawab 403 padahal akun terlihat "admin" | Yang dibaca adalah role keanggotaan workspace (Owner / Admin SOP). Role realm Keycloak seperti platform_owner tidak dihitung sama sekali. | Cek keanggotaan Anda di workspace tersebut, bukan role di Keycloak. Minta Owner workspace menaikkan role Anda. |
| Menekan Enable dijawab 404 | Addon tidak terlihat oleh workspace ini (privat milik workspace lain), atau backend di instance itu belum memuat endpointnya. | Pastikan versi service, lalu cek ulang katalog. |
| Addon sudah di-enable di satu workspace tapi terbaca mati di workspace lain | Aktivasi dikunci per workspace, bukan per akun atau per instance. | Nyalakan addon di masing-masing workspace yang membutuhkannya. |
| Service task gagal saat runtime dengan pesan addon tidak aktif | Addon dimatikan setelah proses dirancang (soft-block). | Nyalakan kembali addonnya, lalu ulangi activity yang gagal. |
| Menyimpan konfigurasi integrasi ditolak | Addon belum di-enable di workspace ini. | Nyalakan dulu di menu Addons, lalu simpan ulang. |
| Switch Enable for this workspace tidak bisa ditekan | Role Anda member. | Minta Owner atau Admin SOP workspace yang melakukannya. |
| Konfigurasi lama hilang dari submenu Integration setelah addon dimatikan | Perilaku normal. Konfigurasinya tidak dihapus. | Buka All Integrations, lihat seksi Turned off, still configured. |
Batasan Fase 1
Hal-hal berikut belum tersedia pada rilis ini. Disebutkan supaya tidak dicari-cari di layar.
- Tidak ada kendali privat/publik di UI. Kartu addon tidak menyediakan aksi mengubah visibility, dan dialog Publish menyatakan addon terbitan workspace tetap privat pada rilis ini. Sumbu visibility ada di rancangan dan di API, tetapi layarnya belum ada.
- Version bump belum ada. Menerbitkan ulang key yang sama tidak menimpa addon yang sudah terbit.
- Menu Addons bukan tempat konfigurasi. Kredensial dan endpoint tetap diisi lewat menu Integration.
- Governance admin instance belum masuk. Kendali "addon mana yang boleh beredar di instance" belum bagian dari fase ini.
Angka pemakaian belum bisa dipercaya. Pada environment yang diperiksa saat dokumen ini ditulis, seluruh kartu menampilkan Used by 0 integration configurations dan dialog Disable menyebut used by 0 processes — termasuk untuk addon yang jelas-jelas punya konfigurasi, karena addon yang sama terdaftar di seksi Turned off, still configured. Jangan memakai angka ini sebagai dasar keputusan mematikan addon. Periksa seksi Turned off, still configured dan proses yang berjalan secara langsung.
Lampiran — Kontrak API
Untuk integrator dan siapa pun yang menelusuri lewat network tab. Base path: /api/v1/integration.
Tabel ini merangkum kontrak Fase 1. Yang dijalankan langsung lewat UI saat dokumen ini ditulis adalah jalur enable dan disable; sisanya mengikuti rancangan dan perlu dikonfirmasi ulang bila perilakunya terasa berbeda.
| Endpoint | Wewenang | Keterangan |
|---|---|---|
GET /addons | Anggota workspace | Katalog; tiap item membawa status aktivasi, kepemilikan, dan jumlah pemakaian. |
POST /addons/{key}/enable | Owner / Admin SOP | Idempoten. 404 bila addon tidak terlihat oleh workspace pemanggil. |
POST /addons/{key}/disable | Owner / Admin SOP | Idempoten. |
POST /addons/{key}/visibility | Owner saja | Mengubah privat/publik. Body memerlukan is_private secara eksplisit. Perhatikan: endpointnya POST .../visibility, bukan PATCH terhadap field is_private. |
POST /addons | Owner / Admin SOP | Publish addon; multipart berisi addon key dan berkas .zip. |
| Kode | Arti di rangkaian endpoint ini |
|---|---|
400 | Body tidak sah, misalnya is_private tidak disertakan. |
403 | Role keanggotaan workspace tidak mencukupi. |
404 | Addon tidak ada atau tidak terlihat oleh workspace pemanggil — sengaja tidak dibedakan, agar keberadaan addon privat milik workspace lain tidak bocor. |
409 | Memprivatkan addon yang masih diaktifkan workspace lain, atau publish key yang sudah terpakai. |
422 | Addon terlihat tetapi belum di-enable di workspace pemanggil. |
Workspace pemanggil selalu diambil dari konteks autentikasi, tidak pernah dari URL atau body.
Custom Domain
Panduan mendaftarkan domain sendiri untuk workspace, mulai dari konfigurasi CNAME, verifikasi DNS, hingga pengaturan sertifikat SSL (otomatis maupun upload sertifikat sendiri)
Activity Log
Jejak audit setiap request yang ditangani API gateway untuk workspace Anda — ditandai sebagai resource.action, dengan filter sumber, method, outcome, rentang waktu, event tag, dan path.
