Berkas Form BPMN untuk Integrasi Pihak Ketiga

Gambaran Umum

Field File Upload pada form BPMN menghasilkan sebuah berkas lampiran yang disimpan di object storage. Ketika Service Task (API Call atau addon) mengirim berkas itu ke sistem luar, yang dikirim berubah mulai rilis 2026.9.4:

Isi Placeholder Variabel Berkas di Body Integrasi

Di konfigurasi API Call maupun payload addon, berkas dirujuk lewat placeholder ${namaVariabelBerkas} — namaVariabelBerkas adalah Key dari field File Upload di form. Contoh body:

{
  "nomor_aplikasi": "${nomorAplikasi}",
  "dokumen_ktp": "${ktp}"
}

Saat Service Task berjalan, platform mengganti ${ktp} di posisi yang sama dengan nilai berikut:

Sebelum 2026.9.4 — isi berkas base64:

{
  "nomor_aplikasi": "APP-2026-0001",
  "dokumen_ktp": "JVBERi0xLjQKJcfsj6IK..."
}

Sesudah 2026.9.4 — URL unduh bertanda tangan:

{
  "nomor_aplikasi": "APP-2026-0001",
  "dokumen_ktp": "https://app.contoh.com/api/v1/probis/public/form-attachments/6f1c2a4e-8b7d-4c39-9a51-0e2d3f4a5b6c/download?token=eyJ...abc.def..."
}

Format URL-nya:

GET /api/v1/probis/public/form-attachments/{attachment_id}/download?token=<token>

Host pada URL mengikuti alamat publik gateway instance, sehingga bisa dijangkau dari luar jaringan aplikasi.

Aturan URL unduh

Konsekuensi untuk penerima: unduh berkas segera saat pesan diterima, di dalam alur pemrosesan yang sama. URL tidak boleh disimpan untuk diunduh nanti (antrean, batch malam hari), dan tidak boleh diakses dua kali — termasuk oleh pemindai tautan atau health check yang ikut membuka URL.

Response unduh yang berhasil adalah isi berkas dengan Content-Type sesuai mime_type berkas dan header Content-Disposition: attachment yang membawa nama file asli.

Membedakan URL dan base64

Berkas yang di-upload sebelum rilis 2026.9.4 tetap tersimpan sebagai berkas biner dan tetap dikirim sebagai base64. Berkas baru dikirim sebagai URL. Selama proses lama masih berjalan, field yang sama bisa berisi base64 atau URL, tergantung kapan berkasnya di-upload.

Base64 tidak pernah mengandung karakter :, sehingga awalan http:// atau https:// membedakannya dengan pasti:

import re
import base64
import requests

def ambil_berkas(nilai: str) -> bytes:
    # URL bertanda tangan (sesudah 2026.9.4)
    if re.match(r"^https?://", nilai):
        resp = requests.get(nilai, timeout=30)
        resp.raise_for_status()
        return resp.content
    # base64 (berkas lama)
    return base64.b64decode(nilai)

Alternatifnya, cek path /api/v1/probis/public/form-attachments/ pada nilai tersebut. Jangan mengandalkan panjang string atau awalan base64 tertentu.

Kalau URL gagal diterbitkan

Penerbitan URL adalah bagian dari Service Task. Kalau gagal — layanan lampiran tidak terjangkau, menolak permintaan, atau tenant/instance proses tidak bisa ditentukan — Service Task gagal dan membuat incident. Request ke sistem luar tidak pernah dikirim, jadi penerima tidak akan pernah menerima metadata JSON mentah sebagai pengganti berkas. Setelah penyebabnya dibereskan, jalankan ulang Service Task dari incident.

Hanya berlaku di body

Penggantian placeholder berkas menjadi URL (atau base64) hanya dilakukan pada:

• body konfigurasi API Call dengan metode POST, PUT, atau PATCH; dan
• payload (parameters) addon.

Placeholder berkas di URL, query parameter, atau header tidak diganti menjadi URL unduh — yang tergantikan di sana adalah nilai variabelnya apa adanya, yaitu string JSON metadata. Jangan menaruh ${namaVariabelBerkas} di tempat-tempat itu.

Objek variables yang ikut dikirim ke addon juga berisi string JSON metadata, bukan URL. Addon yang butuh berkasnya harus mengambilnya dari nilai di parameters.

Isi Variabel Proses: Metadata JSON

Sesudah 2026.9.4, variabel proses untuk field File Upload bertipe String dan berisi JSON berikut:

{
  "attachment_id": "6f1c2a4e-8b7d-4c39-9a51-0e2d3f4a5b6c",
  "file_name": "ktp-budi.pdf",
  "mime_type": "application/pdf",
  "size": 248310
}

Respons upload dan halaman embed juga membawa type ("file_attachment") dan uploaded_at; kedua field itu tidak dipakai untuk mengenali metadata.

def id_lampiran(meta: dict) -> str:
    return meta.get("attachment_id") or meta["id"]

Berkas biner tidak lagi masuk ke database engine; hanya string metadata ini yang tersimpan di variabel.

API Lampiran Form

Lampiran form mengikuti daur draft → commit:

1. Saat pengguna memilih berkas di form, berkas langsung di-upload dan tersimpan sebagai draft. Respons upload berisi metadata di atas.
2. Saat form disubmit, proses berjalan dan variabel berisi metadata tersebut. Engine mengikat (commit) lampiran ke process instance dan task-nya secara otomatis begitu variabel tertulis. Sejak itu lampiran berstatus committed.
3. Draft yang tidak pernah di-commit (mis. berkas diganti sebelum submit, atau proses gagal start) dibersihkan otomatis oleh server; batas usia draft bawaannya 24 jam.

Aplikasi resmi (App, Studio, embed) sudah menjalankan daur ini sendiri. Endpoint di bawah relevan bagi Anda kalau membangun klien sendiri.

Versi login (JWT)

Header: Authorization: Bearer <token> dan x-active-tenant: <slug-workspace> (slug, bukan id numerik).

Ekstensi yang diterima: jpg, jpeg, png, pdf, docx, xlsx (tipe isi diperiksa, bukan hanya ekstensi). Ukuran maksimum per berkas bawaan 10 MB, diatur administrator lewat UPLOAD_MAX_SIZE.

Versi public (embed start-process)

Untuk form start-process yang di-embed — pengunjung tanpa login. Identitas pengunjung adalah token sesi form pada header X-Probis-Form-Token yang dibawa halaman embed; tenant dan proses diambil dari token itu, bukan dari request.

Jalur public tidak punya endpoint finalize: pengikatan lampiran dilakukan engine sendiri setelah proses berhasil berjalan.

Nilai Variabel Berkas di Tasklist dan Report

Bentuk nilai (value) variabel berkas yang dibaca dari tasklist/report ikut berubah:

Aturannya satu untuk semua konsumen: value yang diawali /api/v1/ adalah path absolut dari root gateway dan dipakai apa adanya; nilai lain relatif terhadap base tasklist. Untuk berkas lama, awalan /{processKey}/ pada laporan berisi process definition key.

Bukan Jalur Ini

Tidak semua "upload file" di AlurKerja memakai mekanisme di halaman ini. Kalau kebutuhan Anda salah satu di bawah, jalur yang berlaku berbeda: