OneMigrationDocumentation

How OneMigration Works

OneMigration is a local-first desktop app that helps you import data into Zoho CRM safely and iteratively. No data is written to Zoho until you explicitly commit.

The Core Concept

Traditional migration tools work in one shot: you upload a file, click import, and hope for the best. If something goes wrong, you're left cleaning up duplicates and bad data inside Zoho.

OneMigration takes a different approach. It treats migration as a project that you iterate on until the data is right. Nothing touches Zoho until you're confident.

The Workflow

Create a project

Choose which Zoho CRM module you want to import into (Contacts, Accounts, Deals, etc.) and upload your CSV file. The source file is copied into the project — your original stays untouched.

Map your fields

A visual field mapper shows your CSV columns on the left and Zoho fields on the right. OneMigration auto-matches columns by name. You can adjust mappings, add transformations (lowercase, phone cleanup, date normalization), and set static values.

Validate

The validator checks every record against Zoho's requirements: required fields, picklist values, field lengths, email formats. Errors and warnings are shown per-row so you know exactly what to fix.

Scan for duplicates

Before importing, OneMigration scans your data against existing Zoho records. Matches are scored by email (+70 points), phone (+50), and name (+30). For each match, you decide: skip, update the existing record, or import as new.

Save a revision

Your mapping, validation results, and prepared records are saved as an immutable revision. Each revision is a snapshot of one iteration. You can create as many revisions as you need.

Preview in OneView

If you have OneView installed, your staged records automatically appear in OneView's search and browse views with an amber "Staged" badge. You can see exactly how your data will look alongside existing Zoho records — before anything is written.

Iterate

Not happy? Go back to step 2. Adjust your mapping. Save a new revision. The previous revision is preserved in the timeline — you can always go back to it.

Commit

When everything looks right, click Commit. OneMigration writes the records to Zoho via API, in batches of 100 with automatic rate limiting. Every created record is tagged with a batch ID.

Rollback if needed

Changed your mind after committing? One-click rollback deletes all records created by that import using the batch tag. No manual cleanup.

Revisions

Each time you adjust your mapping and validate, OneMigration saves a revision. Revisions are numbered (#1, #2, #3...) and immutable — editing the mapping creates a new revision rather than modifying the old one.

This gives you a full audit trail: what mapping was used, what the validation results were, how many records would be created vs updated vs skipped. You can compare revisions to see what changed between iterations.

You can also load a previous revision's mapping as a starting point for a new one — useful when you want to tweak just one field without redoing everything.

OneView Integration

OneMigration writes staged records to a shared folder on your machine.OneView (our unified customer 360 app) detects these files and loads the staged records into its search and browse views.

This means you can search for a customer name and see both the existing Zoho records and the staged migration records side by side. Staged records appear with an amber badge so you always know what's real vs pending.

The integration is automatic — no configuration needed. If both apps are installed, a "Migration" section appears in OneView's sidebar whenever there's an active project.

Duplicate Detection

Before importing, OneMigration searches your existing Zoho data for records that match what you're about to import. Matching is scored:

Email match: +70 points (high confidence)
Phone match: +50 points (high confidence)
Name match: +30 points (medium confidence)

Records scoring 80+ are almost certainly duplicates. Records scoring 50-79 are likely matches. For each match, you choose: skip the import, update the existing record, or import as a new record anyway.

Data Transformations

Each mapped field can have a transformation applied:

Trim: Remove leading/trailing whitespace
Lowercase / Uppercase: Normalize case
Phone cleanup: Strip dashes, spaces, parentheses
Date normalize: Convert various date formats to Zoho's expected format
First word / Last word: Split "John Smith" into separate first/last name fields
Static value: Set a field to a constant (e.g., Lead Source = "Imported")

Supported Sources

Currently OneMigration supports CSV files as the import source. The parser auto-detects delimiters (comma, semicolon, tab) and column types (email, phone, date, number, URL, boolean).

Excel, JSON, and SQL database sources are planned for future releases.

Privacy & Security

OneMigration runs entirely on your machine. Your source data is never uploaded to any server. Migration projects are stored locally in your application data folder. The only network calls are to the Zoho API — and only when you explicitly commit.