Body Options

Body Options memungkinkan pengiriman opsi tambahan bersamaan dengan data utama dalam satu request body. Opsi ini berfungsi sebagai flag atau parameter kontrol yang dapat dibaca oleh component engine handler dan processor untuk menjalankan logic conditional.

Ikhtisar (Overview)

Tanpa Body Options, tidak ada mekanisme standar untuk mengirimkan instruksi tambahan ke handler/processor selain melalui header HTTP atau query parameter. Hal ini menyulitkan skenario seperti:

Mengontrol apakah notifikasi email dikirim setelah create
Menentukan apakah event perlu di-publish ke message broker
Mengirimkan flag khusus untuk conditional logic di processor
Meneruskan metadata bisnis yang bukan bagian dari data tabel

Body Options menyelesaikan masalah ini dengan menyediakan format body terstruktur {data, options} yang secara otomatis dikenali oleh middleware.

Format Request Body

Format Standar (Standard Format)

Format body lama tetap didukung sepenuhnya. Data dikirim langsung di body tanpa wrapper:

{
    "supplier_code": "SUP-001",
    "supplier_name": "PT Maju Jaya",
    "email": "contact@majujaya.com",
    "is_active": true
}

Format dengan Options (Format with Options)

Data dibungkus dalam property data, dan opsi tambahan ditempatkan di property options:

{
    "data": {
        "supplier_code": "SUP-001",
        "supplier_name": "PT Maju Jaya",
        "email": "contact@majujaya.com",
        "is_active": true
    },
    "options": {
        "send_feedback_email": true,
        "send_to_kafka": false,
        "custom_flag": "any_value"
    }
}

Aturan Deteksi (Detection Rules)

Middleware mendeteksi format baru berdasarkan tiga kondisi yang harus terpenuhi seluruhnya:

Kondisi	Persyaratan
Body memiliki tepat 2 key	`data` dan `options`
`data` bertipe object	Bukan null, bukan array, bukan string
`options` bertipe object	Bukan null, bukan array, bukan string

Jika salah satu kondisi tidak terpenuhi, body diproses menggunakan format standar. Tabel berikut menunjukkan perilaku untuk berbagai format body:

Format Body	Dikenali sebagai Options	Keterangan
`{ field: "value" }`	Tidak	Format lama, diproses tanpa perubahan
`{ data: {...}, options: {...} }`	Ya	Data di-extract, options diteruskan
`{ rootKey: {...} }`	Tidak	Format composite lama
`{ data: { rootKey: {...} }, options: {...} }`	Ya	Format composite dengan options
`{ data: "string", options: {...} }`	Tidak	`data` bukan object
`{ data: {...}, options: {...}, extra: "x" }`	Tidak	Lebih dari 2 key
`{ data: {...} }`	Tidak	Hanya 1 key

Aturan "tepat 2 key" menghindari false positive jika tabel kebetulan memiliki kolom bernama data atau options. Fitur ini sepenuhnya backward compatible.

Action yang Didukung (Supported Actions)

Action	Body Options Aktif
`create`	Ya
`update`	Ya
`delete`	Ya
`create-composite`	Ya
`update-composite`	Ya
`adjust`	Ya
Workflow actions	Ya

Contoh Penggunaan (Usage Examples)

CREATE dengan Options

POST /api/mini-inventory/supplier/create

{
    "data": {
        "supplier_code": "SUP-001",
        "supplier_name": "PT Maju Jaya",
        "is_active": true
    },
    "options": {
        "send_feedback_email": true,
        "notify_admin": false
    }
}

UPDATE-COMPOSITE dengan Options

POST /api/mini-inventory/stock-inbound/update-composite

{
    "data": {
        "stock_inbound": {
            "stock_inbound_id": "d4e57872-...",
            "notes": "Diperbarui",
            "stock_inbound_item": {
                "update": [
                    { "stock_inbound_item_id": "a1b2c3d4-...", "qty_received": 30 }
                ],
                "insert": [],
                "delete": []
            }
        }
    },
    "options": {
        "recalculate_totals": true,
        "notify_warehouse": true
    }
}

Mengakses Options (Accessing Options)

Dari Handler (From Handler)

Pada konfigurasi component di payload JSON, tambahkan {options} sebagai parameter template variable:

Konfigurasi component di payload

{
    "params": [
        { "value": "{tableName}" },
        { "value": "{requestData}" },
        { "value": "{options}" }
    ]
}

Handler menerima options sebagai parameter fungsi:

src/components/handlers/custom_handler.js

async function handleBeforeInsert(tableName, requestData, options, services) {
    if (options.send_feedback_email) {
        // Logic pengiriman email
    }
    return { success: true };
}

Template variable mendukung dot notation untuk mengakses property spesifik:

{options} menghasilkan seluruh object options
{options.send_feedback_email} menghasilkan true
{options.custom_flag} menghasilkan "any_value"

Dari Processor (From Processor)

Processor dapat mengakses options melalui req.bodyOptions:

src/modules/{project}/processor/{endpoint}/{name}.js

async function process(input, services, req) {
    const options = req.bodyOptions || {};

    if (options.send_to_kafka !== false) {
        // Default: publish ke Kafka jika tidak di-disable
    }

    return { success: true, statusCode: 201, data: { processed: true } };
}

Alur Pemrosesan (Processing Flow)

HTTP Request
  │
  ▼
bodyParser.json()          ← Parse JSON body
  │
  ▼
Idempotency Middleware     ← Hash body asli (termasuk options)
  │
  ▼
Body Options Middleware    ← Deteksi {data, options}, extract ke req.body dan req.bodyOptions
  │
  ▼
Route Handler              ← req.body = data saja, req.bodyOptions = options
  │
  ▼
Component Engine           ← Resolve {options} template variable dari context
  │
  ▼
Handler / Processor        ← Menerima options sebagai parameter

Idempotency middleware berjalan sebelum body options middleware. Dua request dengan data yang sama tetapi options berbeda menghasilkan hash yang berbeda dan tidak dianggap sebagai duplikat.

Panduan Penggunaan (Usage Guidelines)

Gunakan options untuk:

Kategori	Contoh
Flag kontrol behavior	`send_email`, `notify_admin`, `skip_audit`
Mode operasi	`dry_run`, `force_update`, `soft_delete`
Parameter integrasi	`send_to_kafka`, `sync_to_erp`
Metadata non-data	`reason`, `source_system`, `batch_id`

Jangan gunakan options untuk:

Kategori	Alasan
Data kolom tabel	Kirim langsung di `data`
Kriteria WHERE	Masukkan di `data.where` (untuk delete)
Informasi autentikasi	Gunakan header `x-api-key` atau `Authorization`
Pagination/sorting	Gunakan parameter pada endpoint read

Langkah Selanjutnya (Next Steps)

Format Response untuk memahami struktur response dari setiap action
Pola Action-Based untuk memahami action mana saja yang mendukung body options

Body Options

On this page