API ini dipakai sistem lain untuk memulai banyak instance dari satu proses sekaligus, tanpa memanggil /start atau /direct-start berulang kali. Maksimal 100 instance per panggilan.

Tiap item diperlakukan seperti satu panggilan /direct-start: pemula (initiator), activity history, dan webhook process.started sama persis.

Siapa yang boleh

Pemanggil harus berhak memulai proses itu, sama seperti saat memulainya dari aplikasi. Bila tidak, jawabannya 403.

Menyalakan fitur

Fitur ini mati secara bawaan. Admin instalasi menyalakannya lewat environment variable server:

BULK_START_ENABLED=true

Lalu jalankan ulang servis tasklist. Selama flag mati, endpoint menjawab 404. /start dan /direct-start tidak terpengaruh.

Memanggil

POST /api/v1/tasklist/{processName}/bulk-start

Kirim header:

Body berisi array items. Tiap item adalah JSON flat seperti body /direct-start: satu key per variabel, dan key-nya harus nama field pada start form proses itu.

curl -s -X POST 'https://<host>/api/v1/tasklist/pengajuan_cuti/bulk-start' \
  -H 'Authorization: Bearer <access token>' \
  -H 'x-active-tenant: contoh-workspace' \
  -H 'x-act-env: TEST' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      { "nama": "Budi", "jumlah_hari": 3 },
      { "nama": "Sari", "jumlah_hari": 5 },
      { "nama": "Dewi", "jumlah_hari": 2 }
    ]
  }'

Validasi dulu, baru dimulai

Sebelum satu instance pun dibuat, semua item diperiksa: hak akses, key yang bukan field start form, dan constraint form. Bila ada satu item yang tidak sah, seluruh permintaan ditolak dengan 400 yang menyebut nomor item (mulai dari 0) dan alasannya, dan tidak ada instance yang dibuat.

Pesannya berbentuk Item 2: <alasan>, misalnya Item 2: stry untuk key stry yang bukan field start form.

Jawaban

Bila validasi lolos, jawabannya 200:

{
  "total": 3,
  "successCount": 2,
  "failedCount": 1,
  "results": [
    { "index": 0, "processInstanceId": "1234567", "error": null },
    { "index": 1, "processInstanceId": null, "error": "Gagal menjalankan service task" },
    { "index": 2, "processInstanceId": "1234569", "error": null }
  ]
}

Tiap item di-start satu per satu di transaksi engine-nya sendiri, bukan dalam satu transaksi besar. Bila satu item gagal di engine, item lain tetap jalan dan item itu dicatat gagal. Instance yang sudah dibuat tidak ditarik kembali, karena ia mungkin sudah memicu webhook atau email. Periksa results untuk tahu item mana yang perlu dikirim ulang.

Jawaban galat:

Batasan waktu

Tiap item berjalan sampai wait state pertama, sama seperti start tunggal. Proses yang punya service task sinkron lambat sebelum wait state pertama membuat waktu total batch bertambah mengikuti jumlah item, sehingga batch besar bisa melewati timeout. Untuk proses seperti itu, kirim batch yang lebih kecil. Bila permintaan terputus oleh timeout, instance yang sudah dibuat tetap ada, jadi periksa dulu instance yang ada sebelum mengirim ulang.