Reusable Form
Panduan membuat Reusable Form di Drive, mengelola versinya (publish, riwayat, rollback), serta memahami bagaimana versi, pin, dan override berlaku pada proses yang memakainya.
Reusable Form adalah form yang disimpan sebagai item tersendiri di Drive, lalu dipakai ulang oleh banyak proses BPMN. Form disusun dan diterbitkan sekali, sedangkan setiap perubahan tercatat sebagai versi baru.
Berbeda dengan Custom Form
Reusable Form dibuat lewat New → Reusable Form, terpisah dari Custom Form yang sudah ada (lihat Create New File). Form yang disusun langsung di dalam BPMN (form inline) tetap berjalan seperti biasa dan tidak terpengaruh.
Siapa yang Boleh Mengelola
Semua anggota workspace dapat melihat daftar Reusable Form, detail, riwayat versi, dan tab Used in. Tindakan yang mengubah form — menyimpan draft, Publish, Roll back, Duplicate, dan mengubah pengaturan form — hanya untuk peran Admin SOP atau Owner. Anggota dengan peran lain yang mencoba mengubah form akan ditolak dengan pesan Insufficient permissions.
Reusable Form juga terisolasi per workspace: form milik workspace lain tidak terlihat dan tidak dapat diakses.
Membuat Reusable Form
- Buka Studio lalu pilih menu Drive.
- Klik tombol + New, lalu pilih Reusable Form.
- Isi nama form. Form memiliki Key unik (contoh:
qa-master-pemohon) yang tampil di bawah nama form dan dipakai proses BPMN untuk merujuknya. - Susun field pada Form Editor. Mode Editing, Split, dan Preview tersedia di bagian atas editor.
- Klik Publish untuk menerbitkan versi pertama.
Badge di samping nama form menunjukkan status terkini, misalnya v1 published · up to date. Selama ada perubahan yang belum diterbitkan, badge berubah menjadi unpublished changes.
Draft, Publish, dan Riwayat Versi
- Draft — perubahan yang Anda simpan lewat Save draft. Draft belum dipakai oleh proses.
- Publish — menerbitkan isi draft sebagai versi baru (v1, v2, v3, dan seterusnya). Versi yang sudah terbit tidak pernah ditimpa.
- Version history — daftar semua versi beserta waktu dan catatannya. Versi terbaru ditandai Latest.
Rollback ke Versi Lama
Di tab Version history, klik Roll back to this version pada versi yang diinginkan. Rollback tidak menghapus versi apa pun: sistem membuat versi baru yang isinya sama dengan versi yang dipilih, dengan catatan otomatis (misalnya rollback to v1).
Periksa draft setelah rollback
Setelah rollback, isi draft di editor belum otomatis kembali ke versi yang dipilih, dan badge dapat menampilkan unpublished changes. Jangan menekan Publish sebelum Anda memeriksa isi draft — menerbitkannya akan membuat versi baru dari isi draft tersebut dan membatalkan rollback.
Aturan Versi pada Proses
Data lama tetap memakai versi saat disubmit
Setiap task yang disubmit mencatat versi Reusable Form yang dipakai saat itu. Mempublish versi baru tidak mengubah tampilan data yang sudah terkirim: pada tab History proses, label field tiap tahap mengikuti versi yang berlaku ketika tahap tersebut disubmit.
Task yang masih terbuka akan menampilkan versi terbaru setelah halamannya dimuat ulang. Contoh: Anda mempublish v2 (menambahkan field Email wajib) saat Task 2 masih terbuka; setelah dimuat ulang, Task 2 menampilkan Nama, NIK, dan Email*, lalu mencatat v2 saat disubmit.
Pin versi
Sebuah node (user task atau start event) dapat di-pin ke versi tertentu. Node yang di-pin selalu menampilkan versi tersebut, sedangkan node lain yang tidak di-pin mengikuti versi terbaru.
Contoh: setelah v3 terbit (Nama, NIK, Email, Alamat), Task 3 yang di-pin ke v1 hanya menampilkan Nama dan NIK.
Sebagai pembanding, task yang tidak di-pin menampilkan versi terbaru:
Override hidden, readonly, dan required
Pada setiap node yang memakai Reusable Form, field tertentu dapat di-override tanpa mengubah form aslinya:
| Override | Efek pada tampilan di App |
|---|---|
| hidden | Field tidak ditampilkan. |
| readonly | Field tampil abu-abu dan tidak dapat diubah. |
| required | Field bertanda * dan wajib diisi sebelum Complete Task. |
Jika field required dikosongkan, tombol Complete Task menampilkan Form incomplete beserta pesan Email is required.
Penegakan di server
Override required hanya ditegakkan oleh server apabila pengaturan form.constraint.enabled
aktif (default: mati). Saat mati, pemblokiran hanya terjadi di tampilan App. Override
hidden dan readonly hanya berlaku di tampilan; server tidak menolak kiriman data untuk keduanya.
Saat pengaturan aktif, task yang di-pin ke versi tertentu juga menolak variabel di luar field versi itu
(pesan: Variable tidak dikenal pada form: …).
Tab Used in
Tab Used in menampilkan jumlah dan daftar tempat form ini dipakai — proses dan elemen (start event atau user task) yang merujuk form ini. Gunakan tab ini untuk menilai dampak sebelum mempublish atau melakukan rollback.
Pesan Error Bentrok Key
Key field di dalam Reusable Form tidak boleh sama dengan key field lain pada proses yang memakainya. Pemeriksaan dilakukan di tiga titik:
| Tindakan | Kondisi | Hasil |
|---|---|---|
| Menyimpan draft | Ada key ganda di dalam form yang sama | Ditolak (duplicate_keys, HTTP 422). |
| Publish / rollback | Salah satu key bentrok dengan field lokal pada proses yang memakai form (dilaporkan beserta proses dan elemennya) | Ditolak (collisions, HTTP 422). Draft bentrok masih boleh disimpan; pemeriksaan ada di Publish. |
| Deploy BPMN | Field lokal di proses bentrok dengan key form yang dirujuk | Ditolak (HTTP 400), pesan: key field lokal bentrok dengan key form referensi: …. |
Perbaiki dengan mengganti key salah satu field, lalu ulangi tindakannya.
Memakai Form yang Sama Lebih dari Sekali (Rename Key)
Kapan Perlu Rename
Satu Reusable Form boleh dipakai dua kali atau lebih di satu form, misalnya form Data Pemohon untuk pemohon dan sekali lagi untuk penjamin. Karena key field harus unik, pemakaian kedua akan bentrok dengan yang pertama (nik, nama, alamat muncul dua kali). Solusinya: ubah key field pada pemakaian kedua lewat Field & override.
Cara Mengganti Key
- Di editor form BPMN, klik elemen Reusable Form (pemakaian kedua) agar panel Edit Element terbuka.
- Pada bagian Field & override, isi kolom New key untuk setiap field yang ingin diganti. Kolom Key menampilkan key aslinya dan tidak berubah.
- Untuk mengganti semua field sekaligus, isi kotak prefix (contoh:
penjamin_) lalu klik Add prefix. Seluruh key terisi otomatis, misalnyanikmenjadipenjamin_nik. - Klik Save Changes.
Hasilnya, kedua pemakaian tampil berdampingan tanpa bentrok:
Field di dalam repeater
Field anak di dalam repeater tidak dapat di-rename: kolom New key-nya nonaktif dan diberi keterangan row-scoped. Key repeater itu sendiri dan field di luar repeater tetap dapat diganti.
Aturan
- Key harus unik di seluruh form. Jika key baru sudah dipakai field lain, kolom New key menampilkan Key is already used in this form.
- Semua pemakaian form yang sama harus memakai versi yang sama — di-pin ke versi yang sama, atau semuanya mengikuti latest. Campuran versi (misalnya satu v1 dan satu latest/v2) ditolak dengan pesan used more than once with different versions.
Pesan Conflict dan Save Version Diblokir
Selama masih ada key ganda atau versi campuran, banner merah tampil di atas editor, menyebut key yang bentrok beserta pemakaiannya, dan tombol Save Version nonaktif. Deploy proses juga ditolak (HTTP 400). Ganti key lewat New key, atau samakan versinya, sampai banner hilang.
Akibat ke Data
Nilai yang diisi pada pemakaian ter-rename tersimpan di key baru: contohnya penjamin_nik, terpisah dari nik milik pemohon. Di tab History, kedua blok tampil lengkap dengan labelnya masing-masing.
Laporan dan Question lama tidak ikut berubah
Laporan atau Question yang sudah membaca variabel nik tetap membaca nik saja dan tidak otomatis
mencakup penjamin_nik. Tambahkan variabel baru tersebut secara manual ke laporan/Question yang
membutuhkannya.
Kolom Tampil di App (Show in App)
Field dari Reusable Form ikut tersedia sebagai variabel proses dan dapat dipilih untuk ditampilkan pada daftar My Tasks dan My Instances. Batasnya maksimal 2 variabel per proses; mengaktifkan variabel ketiga ditolak dengan pesan at most 2 variables can be shown in app per process.