NAM-APJATEL-BACKEND/DEVICE_BULK_OPERATIONS.md

Device Bulk Operations - Quick Reference

🚀 New Endpoints

Bulk Create Devices

POST /devices/bulk/create

{
  "devices": [
    {
      "device_code": "ODP-001",
      "device_type": "ODP",
      "longitude": 107.6191,
      "latitude": -6.9175,
      "port_amount": 8,
      "status": "active",
      "province": "West Java",
      "city": "Bandung",
      "district": "Cicadas",
      "tower_id": "uuid-optional",
      "olt_id": "uuid-optional-for-odp"
    }
  ]
}

Bulk Update Devices

PUT /devices/bulk/update

{
  "device_ids": ["uuid1", "uuid2"],
  "updates": {
    "status": "maintenance",
    "province": "Central Java"
  }
}

Bulk Delete Devices

DELETE /devices/bulk/delete

{
  "device_ids": ["uuid1", "uuid2", "uuid3"]
}

✅ Validation Rules

Device Types

• ODP - Optical Distribution Point (can be assigned to OLT)
• OTB - Optical Terminal Box
• closure - Cable Closure

Status Values

• active
• inactive
• maintenance

Important Notes

1. Port Amount: Required for OTB and ODP devices (must be > 0)
2. OLT Assignment: Only ODP devices can be assigned to an OLT
3. Tower Assignment: Optional for all device types
4. Limits: Maximum 100 devices per bulk operation

📊 Response Format

{
  "total_requested": 10,
  "successful": 8,
  "failed": 2,
  "errors": [
    {
      "index": 3,
      "error": "Invalid port amount",
      "details": "port amount must be greater than 0 for OTB or ODP devices"
    }
  ],
  "results": [/* array of created/updated devices */],
  "execution_time": "320ms"
}

🔐 Authorization

Requires role: Teknisi | Admin | Super Admin

⚡ Performance

• 5-10x faster than individual operations
• Optimal batch size: 20-50 devices
• Transaction-safe operations
• Batch processing: 50 items per database transaction

📝 Example Usage

PowerShell (Windows)

$body = @{
    devices = @(
        @{
            device_code = "ODP-001"
            device_type = "ODP"
            longitude = 107.6191
            latitude = -6.9175
            port_amount = 8
            status = "active"
            province = "West Java"
            city = "Bandung"
        }
    )
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:8080/devices/bulk/create" `
    -Method POST `
    -Headers @{
        "Authorization" = "Bearer $token"
        "Content-Type" = "application/json"
    } `
    -Body $body

cURL (Linux/Mac)

curl -X POST http://localhost:8080/devices/bulk/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [
      {
        "device_code": "ODP-001",
        "device_type": "ODP",
        "longitude": 107.6191,
        "latitude": -6.9175,
        "port_amount": 8,
        "status": "active"
      }
    ]
  }'

🔧 Common Use Cases

1. Initial Deployment: Bulk create multiple devices from installation plan
2. Status Updates: Bulk update device status during maintenance
3. Network Cleanup: Bulk delete obsolete or replaced devices
4. Configuration Changes: Bulk update device properties
5. Migration: Import devices from external systems

⚠️ Common Errors

Error	Cause	Solution
"Invalid port amount"	Port amount ≤ 0 for OTB/ODP	Set port_amount > 0
"Tower not found"	Tower ID doesn't exist	Verify tower exists
"OLT not found"	OLT ID doesn't exist	Verify OLT exists
"Invalid OLT assignment"	Non-ODP assigned to OLT	Only assign OLT to ODP devices
"Device not found"	ID doesn't exist (update/delete)	Verify device ID

📚 Related Documentation

• Cable Connections Bulk: BULK_OPERATIONS_GUIDE.md
• API Routes: API_ROUTES_CABLE_CONNECTIONS.md
• Quick Reference: BULK_OPERATIONS_QUICK_REF.md

---

Added: October 10, 2025
Version: 1.0 (Device Bulk Operations)