📚 Data Import Guide

Panduan lengkap import data ke Supabase - Multi Client

📋 Quick Navigation

⭐ Required Fields 📝 Format Validasi 🔒 Unique Fields 🔧 Resolusi Konflik ✨ Best Practices 💡 Contoh CSV

⭐ Required Fields (11 Field Wajib)

Penting! SEMUA 11 field ini WAJIB diisi. Jika ada yang kosong, record akan di-skip/gagal.

#	Field Name	Deskripsi	Contoh	Validasi
1	name	Nama lengkap karyawan	`AHMAD RESKI`	REQUIRED Tidak boleh kosong
2	email	Alamat email	`[email protected]`	REQUIRED UNIQUE Format email valid
3	phone	Nomor HP	`081234567890`	REQUIRED Format 08xxx, 9-13 digit
4	password	Password untuk login	`ESBCGT`	REQUIRED Minimal 6 karakter
5	nik	NIK KTP	`1401202505060002`	REQUIRED UNIQUE Harus 16 digit angka
6	opsId	ID Operasional	`SPX-12345` atau `SCP001`	REQUIRED UNIQUE per PREFIX Format: PREFIX-NUMBER atau PREFIXNUMBER Contoh: SPX-12345, SCP001, BMT-999 Prefix otomatis di-extract dari opsId
7	startDate	Tanggal mulai shift	`01/01/2025`	REQUIRED Format: DD/MM/YYYY atau YYYY-MM-DD
8	endDate	Tanggal selesai shift	`31/12/2025`	REQUIRED Format: DD/MM/YYYY atau YYYY-MM-DD, harus >= startDate
9	start	Jam masuk kerja	`08:00`	REQUIRED Format: HH:mm
10	end	Jam keluar kerja	`17:00`	REQUIRED Format: HH:mm
11	position	Nama Jabatan/Posisi	`Rider`	REQUIRED Harus exact match dengan opsPositions Lihat daftar di bawah

📋 Daftar Position yang Valid

Nilai position HARUS sama persis (case-insensitive) dengan salah satu nama berikut:

Rider Driver Rider Last Mile Plus Rider Last Mile Regular Driver Last Mile Regular Driver Mobile Hub Firemen Production Warehouse Logistic

Jika position tidak ada dalam daftar, record akan di-skip/gagal.

OPTIONAL FIELDS

Field berikut OPSIONAL - boleh diisi atau dikosongkan.

#	Field Name (CSV)	Database Table	Deskripsi	Contoh
12	hubId	`ops`	ID Hub (lookup by name atau ID)	`Hub Jakarta` atau `1`
13	vendorName	`ops`	Nama Vendor	`Vendor ABC`
14	isDedicated	`ops`	Status dedicated	`true` / `false`
15	birthDate	`users`	Tanggal lahir	`15/05/1995`
16	birthPlace	`users`	Tempat lahir	`Jakarta`
17	gender	`users`	Jenis kelamin	`Laki-laki` / `Perempuan`
18	address	`users`	Alamat lengkap	`Jl. Contoh No. 1`

Info: Field yang TIDAK di-import ke tabel ops

Field berikut dikelola terpisah (bukan via CSV import):

bankName, bankAccountNumber, bankAccountName, npwp, religion, maritalStatus, lastEducation, joinedAt, trainingStatus, gender, birthPlace, birthDate, address

📝 Format Validasi Field

🆔 NIK (Nomor Induk Kependudukan)

Format:

Harus 16 digit angka
Tidak boleh ada spasi atau karakter lain
Harus UNIQUE (tidak boleh duplikat)

✅ Valid:

1401202505060002

❌ Invalid:

140120250506002 ← Hanya 15 digit

14012025050600022 ← 17 digit

1401-2025-0506-0002 ← Ada tanda strip

1401 2025 0506 0002 ← Ada spasi

📧 Email

Format:

Format email valid: [email protected]
Field OPTIONAL (boleh kosong)
Jika diisi, harus format email yang benar
UNIQUE - jika duplikat akan di-resolve (set ke null)

✅ Valid:

[email protected]
[email protected]
[email protected]

❌ Invalid:

ahmad@gmail ← Tidak ada .com

@gmail.com ← Tidak ada username

ahmad.gmail.com ← Tidak ada @

ahmad @gmail.com ← Ada spasi

📱 Nomor Telepon (telepon)

PENTING! Format Indonesia:

Dimulai dengan 08
Panjang: 9-13 digit
Hanya angka, tidak ada spasi/dash
Field OPTIONAL (boleh kosong)

✅ Valid:

081234567890 ← 12 digit ✓

085269326656 ← 12 digit ✓

08990833248 ← 11 digit ✓

089123456 ← 9 digit ✓ (minimum)

+628123456789 ← Dengan +62 ✓

❌ Invalid:

08951234567890 ← 14 digit (terlalu panjang!) ❌

08123456 ← 8 digit (terlalu pendek) ❌

0812-3456-7890 ← Ada dash ❌

0812 3456 7890 ← Ada spasi ❌

628123456789 ← Tidak ada 0 atau + di depan ❌

📅 Tanggal (shiftStartDate, shiftEndDate, birthDate, joinedAt)

Format yang Didukung (3 format):

DD/MM/YYYY - Recommended (contoh: 01/01/2025)
YYYY-MM-DD - ISO format (contoh: 2025-01-01)
YYYY/MM/DD - Alternative (contoh: 2025/01/01)

Aturan Penting:

Gunakan leading zero untuk tanggal < 10
shiftEndDate harus >= shiftStartDate

✅ Valid:

10/11/2025 ← DD/MM/YYYY ✓

03/11/2025 ← Dengan leading zero ✓

2025-01-01 ← YYYY-MM-DD (ISO) ✓

2025/01/01 ← YYYY/MM/DD ✓

❌ Invalid:

3/11/2025 ← Tanpa leading zero (tidak recommended)

10-11-2025 ← Pakai dash tapi bukan ISO format ❌

32/13/2025 ← Tanggal tidak valid ❌

Date Range Error! Contoh kesalahan umum:

shiftStartDate: 07/11/2025

shiftEndDate: 06/01/2025 ← ERROR! End date lebih kecil dari start date ❌

👤 Username

Field OPTIONAL (boleh kosong)
UNIQUE - jika duplikat akan di-resolve (generate random)
Alphanumeric (huruf dan angka)
Recommended: huruf kapital + angka

✅ Valid:

AHMAD9354

IKRAM2693

user123

JohnDoe2025

🔒 Unique Fields (Tidak Boleh Duplikat)

⚠️ Duplicate Handling Strategy - SKIP ALL

SEMUA DUPLICATE AKAN DI-SKIP (tidak di-import) untuk menjaga data integrity:

Email duplicate → SKIP (tidak di-import)
NIK duplicate → SKIP (tidak di-import)
opsId duplicate → SKIP (unique per prefix, SPX-001 ≠ SCP-001)
Username duplicate → AUTO-RESOLVE (tetap di-import)

Field	Jika Duplikat	Action	Report Message
✋ Email	Email sudah ada di database	SKIP RECORD	Email duplicate: [email protected] (existing user: John Doe) ❌ Record di-skip, tidak di-import 🔍 Check order: FIRST 📝 Report: Status SKIPPED, reason: email_duplicate
✋ NIK	NIK sudah ada di database	SKIP RECORD	NIK duplicate: 3201234567890123 (existing user: Jane Smith) ❌ Record di-skip, tidak di-import 🔍 Check order: SECOND 📝 Report: Status SKIPPED, reason: nik_duplicate
✋ opsId	opsId sudah ada di database (per prefix)	SKIP RECORD	opsId duplicate: SPX-12345 (prefix: SPX) ❌ Record di-skip, tidak di-import 🔍 Check order: THIRD (checked BEFORE user creation) ✅ Unique per PREFIX (SPX-001 ≠ SCP-001) 📝 Report: Status SKIPPED, reason: opsId_duplicate 💡 Prefix auto-extracted: SPX-123 → prefix "SPX"
✅ Username	Username sudah digunakan	AUTO-RESOLVE	john.doe → john.doe2 (add suffix) ✅ Record tetap di-import dengan username baru 🔧 Resolution: Add numeric suffix (2, 3, 4, ...) 📝 Report: Status SUCCESS with resolved username

💡 opsId Prefix System

Sistem otomatis extract prefix dari opsId untuk pengecekan duplikat yang lebih cerdas:

SPX-12345 → prefix: SPX

SCP001234 → prefix: SCP

BMT-999 → prefix: BMT

12345 → prefix: none (global check)

Artinya: SPX-001 dan SCP-001 adalah opsId yang BERBEDA (tidak konflik) karena prefix-nya berbeda!

Jika opsId tidak punya prefix (contoh: 12345), sistem akan cek secara global (semua opsId).

✅ Keuntungan Skip Strategy

Data Integrity Terjaga - Tidak ada duplicate email, NIK, atau opsId
No Orphan Records - opsId di-check SEBELUM create user
Prefix-Aware - opsId unique per prefix (SPX-001 ≠ SCP-001)
Clear Audit Trail - Semua skip tercatat dengan detail
Easy Troubleshooting - Report menunjukkan existing user info

📋 Consolidated Report

Semua record (success, skipped, error) tercatat di consolidated report CSV:

SUCCESS: status=SUCCESS, username=john.doe, password=Pass123!

SKIPPED: status=SKIPPED, error_message="Email duplicate: [email protected] (existing user: John Doe)"

SKIPPED: status=SKIPPED, error_message="opsId duplicate: SPX-001 (prefix: SPX)"

💡 Best Practices

Gunakan DRY RUN mode untuk detect duplicates SEBELUM import
Review consolidated report untuk lihat semua skip reasons
Fix duplicate data di CSV berdasarkan report
Re-import setelah fix untuk ensure 100% success rate
Check existing user info dari report untuk merge manual jika perlu

🔧 Cara Resolve Konflik Data

Scenario 1: NIK Duplikat

Error: NIK 1401202505060002 sudah ada di database

🔧 Solusi:

Cek apakah NIK benar-benar sama dengan user existing
Jika salah ketik, perbaiki NIK di file CSV
Jika memang user yang sama:
- Gunakan ops_id untuk update data existing
- Atau skip record ini (user sudah ada)

# Contoh update via ops_id:
Ops_ID,name,nik,email,...
947952,AHMAD RESKI,1401202505060002,[email protected],...

Scenario 2: Email Duplikat

Error: Email [email protected] sudah ada di database

🔧 Solusi (SKIP RECORD):

Record di-SKIP dan tidak di-import
Muncul di consolidated report dengan status SKIPPED
Error message: "Email duplicate: [email protected] (existing user: Ahmad Reski)"

Manual Fix: Update email di CSV dengan alamat yang berbeda, lalu re-import record tersebut

Scenario 3: ops_id Duplikat

Error: ops_id OPS-947952 sudah ada di database

🔧 Solusi (SKIP RECORD):

Record di-SKIP dan tidak di-import
User tidak dibuat (prevent orphan records)
Muncul di consolidated report dengan status SKIPPED
Error message: "ops_id duplicate: OPS-947952"

Manual Fix: Jika memang user baru, generate ops_id baru yang unique. Jika user yang sama, tidak perlu import lagi.

Scenario 4: Username Duplikat

Info: Username ahmad.reski sudah digunakan

🔧 Solusi (AUTO-RESOLVE):

Sistem akan otomatis generate username baru
Format: username + suffix angka (contoh: ahmad.reski → ahmad.reski2)
Record tetap di-import dengan username baru
Muncul di consolidated report dengan status SUCCESS

Good News: Username conflict di-handle otomatis, tidak perlu manual fix!

Scenario 5: Format Telepon Salah

Error: Format telepon tidak valid (harus 08xxx dengan 9-13 digit total)

🔧 Solusi:

Periksa nomor telepon di file CSV
Pastikan format: 08xxxxxxxxxx (9-13 digit total)
Hapus karakter non-digit (spasi, dash, dll)

# ❌ WRONG:

telepon: 0895-3498-8772 (ada dash)

telepon: 8953498877 (tidak ada 0 di awal)

telepon: 08951234567890 (14 digit - terlalu panjang!)

telepon: 08123456 (8 digit - terlalu pendek!)

# ✅ CORRECT:

telepon: 089534988772 (12 digit ✓)

telepon: 089123456 (9 digit - minimum ✓)

telepon: 0895349887729 (13 digit - maximum ✓)

Scenario 6: NIK Format Tidak Valid

Error: NIK tidak valid: harus 16 digit angka, ditemukan '140120250506002' (panjang: 15)

🔧 Solusi:

Periksa NIK di file CSV
Pastikan NIK tepat 16 digit
Cek di KTP asli untuk memastikan NIK yang benar
Hapus karakter non-digit (spasi, dash, dll)

# ❌ WRONG:

nik: 140120250506002 (15 digit - kurang 1)

nik: 14012025050600022 (17 digit - kelebihan 1)

nik: 1401-2025-0506-0002 (ada dash)

nik: 1401 2025 0506 0002 (ada spasi)

# ✅ CORRECT:

nik: 1401202505060002 (tepat 16 digit, tanpa separator)

Common Issue: Excel sering menghilangkan leading zero. Pastikan format cell adalah "Text" sebelum paste NIK!

Scenario 7: End Date < Start Date

Error: shiftEndDate (06/01/2025) tidak boleh lebih kecil dari shiftStartDate (07/11/2025)

🔧 Solusi:

Periksa tanggal di file CSV
Perbaiki shiftEndDate agar >= shiftStartDate
Kemungkinan salah tahun (2025 vs 2026)

# ❌ WRONG:

shiftStartDate: 07/11/2025

shiftEndDate: 06/01/2025 ← 11 bulan lebih awal!

# ✅ CORRECT:

shiftStartDate: 07/11/2025

shiftEndDate: 06/01/2026 ← Ubah tahun ke 2026

✨ Best Practices

✅ DO

Gunakan DRY RUN mode untuk testing
Validasi data di Excel sebelum import
Gunakan leading zero untuk tanggal (01, 02, dst)
Format tanggal: DD/MM/YYYY, YYYY-MM-DD, atau YYYY/MM/DD
Cek NIK tidak ada duplikat
Pastikan NIK tepat 16 digit tanpa spasi/dash
Format cell NIK sebagai Text di Excel (cegah leading zero hilang)
Pastikan nomor telepon 9-13 digit
Pastikan positionName sesuai daftar valid
Download semua report files untuk audit
Backup database sebelum import besar

❌ DON'T

Import langsung tanpa DRY RUN test
Gunakan NIK duplikat
Kosongkan positionName (REQUIRED)
Format tanggal tidak konsisten (1/9 vs 01/09)
Nomor telepon dengan spasi atau dash
shiftEndDate < shiftStartDate
Nama dengan titik di akhir (akan di-trim otomatis)
Spasi di depan/belakang data (akan di-trim otomatis)
Format email salah

💡 Pro Tip:

Gunakan DRY RUN Mode untuk preview hasil import tanpa menyimpan ke database. Anda bisa melihat semua validation errors dan conflicts sebelum commit.

💡 Contoh CSV File

✅ Valid Example ❌ Invalid Example 📄 Minimal Required

# ✅ Contoh LENGKAP - 11 REQUIRED + 7 OPTIONAL name,email,phone,password,nik,opsId,startDate,endDate,start,end,position,hubId,vendorName,isDedicated,birthDate,birthPlace,gender,address AHMAD RESKI,[email protected],083199395415,ESBCGT,1401202505060002,SPX-947952,01/01/2025,31/12/2025,08:00,17:00,Rider,1,Vendor ABC,false,15/05/1995,Jakarta,Laki-laki,Jl. Sudirman No. 1 SITI AMINAH,[email protected],085775999308,VVZYKA,3602120305000002,SCP04794,15/02/2025,15/02/2026,09:00,18:00,Driver,2,Vendor XYZ,true,20/08/1998,Bandung,Perempuan,Jl. Asia Afrika No. 10

📥 Download Template

Anda bisa download template CSV kosong dengan semua field yang tersedia.

📊 Export Reports

ℹ️ Report Files

System generate 3 file CSV + 1 summary text setiap import:

Report File	Isi	Kapan Muncul	Columns
`{timestamp}_consolidated.csv`	SEMUA record dengan status: SUCCESS - berhasil import SKIPPED - di-skip (duplicate) ERROR - gagal import	Selalu	status, row_number, name, email, username, password, ops_id, jabatan, lokasi, shift_name, error_message, created_at
`{timestamp}_success.csv`	Record yang berhasil di-import dengan credentials lengkap	Jika ada success	name, email, username, password, ops_id, jabatan, lokasi, perusahaan, shift_name, tgl_lahir, tgl_join, start_date, end_date, created_at
`{timestamp}_errors.csv`	Record yang gagal di-import dengan error message	Jika ada error	row_number, name, email, ops_id, jabatan, lokasi, shift_name, error_message
`{timestamp}_summary.txt`	Summary statistik import (total, success, error, skipped, duration)	Selalu	Text format (bukan CSV)

📝 Consolidated Report - Complete Data

File consolidated.csv berisi SEMUA informasi:

✅ Success records dengan username & password
⏭️ Skipped records dengan detail reason (email_duplicate, nik_duplicate, ops_id_duplicate)
❌ Error records dengan error message lengkap

Tip: Gunakan consolidated.csv untuk review lengkap semua record dalam 1 file!

🕐 Timestamp Format

File menggunakan timestamp ISO format:

Example: 2025-11-14T10-30-00_consolidated.csv