Data Import

Bulk import helps you stand up or refresh Waqti quickly by loading users, departments, and vendors from structured files—typically CSV or JSON payloads sent through the import API or admin tooling.

Overview

Waqti supports three primary import types for system setup and ongoing maintenance:

Import type	Primary use
Users	Onboard staff at scale; resolve departments and managers; optionally attach roles.
Departments	Build or update the org tree; assign managers; link parents in a second pass when needed.
Vendors	Load or refresh the supplier master from spreadsheets or exports from another system.

Validate in a sandbox first

Run a small file (5–10 rows) on a non-production tenant, inspect the JSON response counts, then scale up.

Importing Users

User import accepts an array of records (JSON) or row sets (CSV mapped to the same fields).

Behavior

Concern	How it works
Upsert key	Records are matched and updated by email (unique identity). New emails create users.
Department	Resolved from your file (e.g., department code or name—follow the template your admin UI or API documents).
Manager	Resolved by manager email so reporting lines stay consistent.
Roles	Optional: attach one or more roles per row if your import schema supports it.

Step-by-step (typical admin flow)

1. Prepare a file with required columns (email, name, department reference, etc.).
2. Open Settings → Data Import → Users (or the equivalent path in your tenant).
3. Upload CSV or paste JSON per your integration.
4. Review validation errors before committing if the UI offers a preview.
5. Run import and read the summary response (see Response format).

Stable email as the anchor

Always use the corporate email as the upsert key; personal or alias emails cause duplicate identities on the next import.

Importing Departments

Department import creates or updates org units and links them into a hierarchy.

Behavior

Concern	How it works
Create / update	Rows are matched by code and/or name (per your template)—existing rows update, new codes insert.
Manager	Set department manager by user email; the user should exist or be imported in the same batch order your runbook recommends.
Parent department	If a parent must exist first, use a two-pass approach: (1) import all departments without parent, (2) second file or pass setting parent by parent code.

Step-by-step

1. Export or draft a flat list of departments with code, name, and optional parent code.
2. Import root-level departments first if the tool requires parents to pre-exist.
3. Run a second pass to attach parent_code (or equivalent) for child units.
4. Assign manager email per department row where applicable.
5. Verify the org chart under Settings → Departments.

Consistent department codes

Treat department code as immutable once in use; renames are fine, code churn breaks historical reports and imports.

Importing Vendors

Vendor import is designed for bulk upsert of supplier records.

Behavior

Concern	How it works
Upsert key	Typically contact email; if missing, vendor name may be used as a fallback key (confirm against your tenant’s import schema).
Duplicates	Matching rows update; non-matching rows create; invalid rows are skipped with errors listed in the response.

Step-by-step

1. Prepare vendor rows: legal name, contact email, phone, VAT/CR if applicable.
2. Open Data Import → Vendors (or API endpoint).
3. Upload file and process.
4. Review skipped rows and error messages; fix source data and re-import.

Response format

Imports return structured JSON with aggregate counts:

Field	Meaning
created	New records inserted.
updated	Existing records matched and modified.
skipped	Rows not applied (often duplicates or validation failures—see errors).
errors	Array of row-level or field-level messages for correction.

Example shape (illustrative):

{
  "created": 42,
  "updated": 8,
  "skipped": 3,
  "errors": [
    { "row": 15, "field": "email", "message": "Invalid email format" }
  ]
}

Tips for data preparation

Practice	Why it matters
One row per entity	Avoid merged cells and multi-line cells in CSV.
UTF-8 encoding	Preserves Arabic names and special characters.
Normalize emails	Lowercase, trim spaces—prevents false “new user” creation.
Order dependencies	Import departments (and optionally users) before rows that reference them.
Keep a changelog	Note file version and date for audit and rollback discussions.

Document your column map

Maintain a short internal sheet that maps each CSV column to Waqti fields and required vs. optional—onboarding the next admin is much faster.

Related Topics

• Admin Guide
• Configuration