ERPNext CRM to Frappe CRM: What the Migration Leaves Behind

Press Run Migration in rtCamp's ERPNext CRM to Frappe CRM migrator and your opportunities are not so much copied as moved out. Each one reappears as a CRM Deal under its own name, owner and creation date. In the same run the comments, emails, attachments and version history that pointed at it are rewritten to point at the deal, and the contacts and addresses linked to it are repointed too. The ERPNext record stays in its table until somebody presses the second button, Clean up ERPNext source data. Its history has already gone.

That is the design, and the tool documents it. This is a reading of its code rather than a run: the migrator's develop branch (version 1.0.0, AGPL-3.0) against ERPNext 16.53.0, ERPNext's develop branch and Frappe CRM's develop branch, with every count below taken from the code and the DocType definitions on each side. It is serious work, with a field-mapping screen per record type and an undo button that refuses once cleanup has emptied the source tables. Undo is blunt, though: it empties the eight Frappe CRM tables the run filled, including the industries, lead sources and lost reasons Frappe CRM installed for itself. Its mapping notes also assume a site that already carries rtCamp's companion app, frappe_crm_xt, which adds columns a stock Frappe CRM does not have.

On a stock ERPNext and a stock Frappe CRM, four things behave differently from what a sales manager expects, and they decide the order of work when CloudSpinx moves a sales team in Kenya from ERPNext CRM onto Frappe CRM, one of the two platforms our CRM practice builds on.

What the migrator copies from ERPNext CRM, and what it leaves

ERPNext 16.53.0 defines 28 DocTypes in its CRM module. Thirteen are child tables and two are settings pages, which leaves 13 kinds of record people actually fill in. The migrator moves four of them: Lead to CRM Lead, Opportunity to CRM Deal, Prospect to CRM Organization and Opportunity Lost Reason to CRM Lost Reason. It also copies four shared masters from outside the CRM module (Territory, Industry Type, UTM Source and Item) into their Frappe CRM equivalents.

The other nine get no step: Appointment, Campaign, Competitor, Contract, Contract Template, Email Campaign, Market Segment, Opportunity Type and Sales Stage. Most are short reference lists. Contracts, email campaigns and appointments are not, so decide where they live before you start.

Opportunity fields with no column on a stock CRM Deal fall through too, among them the opportunity type, market segment, customer group and opportunity date. Two matter more. A stock CRM Deal has no sales stage field, so the opportunity's stage (ERPNext fills in Prospecting by default) has nowhere to land; the migrator's notes carry it through a frappe_crm_xt custom field. The competitors recorded against an opportunity get no step at all.

Statuses arrive as values Frappe CRM does not have

ERPNext's statuses are fixed lists in the DocType. Frappe CRM's are records its installer creates. Our scan of ERPNext 16.53.0 and Frappe CRM's installer, trimmed:

ERPNext Lead.status (9, default 'Lead'): ['Lead', 'Open', 'Replied', 'Opportunity', 'Quotation', 'Lost Quotation', 'Interested', 'Converted', 'Do Not Contact']
Frappe CRM Lead statuses (7): ['New', 'Contacted', 'Nurture', 'Qualified', 'Converted', 'Unqualified', 'Junk']
shared: ['Converted']
ERPNext Opportunity.status (6, default 'Open'): ['Open', 'Quotation', 'Converted', 'Lost', 'Replied', 'Closed']
Frappe CRM Deal statuses (7): ['Qualification', 'Demo/Making', 'Proposal/Quotation', 'Negotiation', 'Ready to Close', 'Won', 'Lost']
shared: ['Lost']

The migrator maps status to status and copies the text as it is. Its own mapping notes say it renames columns and does not translate values, and it writes rows with bulk inserts that skip Frappe's validation, so nothing stops a deal landing with a status record that does not exist. The mapping screen flags the row as a type mismatch, Select to Link, and lets it through. Its design notes list the deal statuses as Open, Won, Lost, Stalled and Not Pursued, which is not a set any stock Frappe CRM install has created. On a stock install, the most ordinary opportunity there is, an open one, arrives pointing at a status called Open that Frappe CRM never made.

Fix it before the run. Create a lead status and a deal status in Frappe CRM for each ERPNext value you actually use, run the migration, move the records onto the pipeline you want, then delete the temporary statuses.

The cleanup button deletes tables, not the records you migrated

Cleanup runs one delete per table, with no filter, on Lead, Opportunity, Prospect and Opportunity Lost Reason. Every row goes, including a lead created after the migration ran by anything still writing ERPNext leads, such as a web form or an email account. Switch those off before the run, the same discipline as a mailbox cutover. Eight child tables are cleared by parent type, and the competitor rows that were never copied are one of them. The guards are a typed DELETE, all eight mapping tabs locked, and any run in the migration log marked Succeeded. An undo that finishes with no failed step is logged as a Succeeded run too, and the guard accepts it.

ERPNext keeps pointing at what it deleted. In 16.53.0, 7 link fields in 5 other DocTypes hold those names: the customer's lead, opportunity and prospect, the quotation's opportunity, the same field on supplier quotations and requests for quotation, and the lead on a support issue. A quotation made out to a lead carries the lead as its party too. The migrator keeps names identical on purpose, so the deal can still be found under the name a quotation prints, but the field itself names a row that no longer exists.

Contacts and addresses go earlier. The run repoints them to the Frappe CRM records, so an ERPNext lead loses its contacts the moment you migrate, not at cleanup. The migrator's design notes say so in as many words: "ERPNext-side queries against the source doctypes break the moment migration runs."

That is why the run belongs on a copy of the production site first, and why cleanup waits until sales, accounts and support have stopped opening the old records. Undo stays available until then. If you would rather have someone read your site before anyone presses either button, tell us what you run through the CRM scoping form.

Is ERPNext CRM really being removed in version 17?

Frappe's manual says so, and the code has not moved yet. The ERPNext CRM documentation states that the CRM workspace on the develop version announces the module "is scheduled for deprecation and will be completely removed in version 17", and recommends Frappe CRM. That sentence did head the CRM workspace in ERPNext's code, and it went when the workspaces were redesigned. 16.53.0 keeps it only as a leftover string in three translation files, and the develop branch not at all. Develop now shows a sidebar banner suggesting Frappe CRM instead, and all 28 CRM DocTypes are still in it.

So nothing forces the move on a version 16 site. If you want Frappe CRM's interface now, there is a path that needs no migrator at all. Frappe CRM ships an ERPNext integration that works on the same site or a separate one: it can create the customer in ERPNext when a deal reaches a status you choose, and on the same site it can also sync products both ways. New deals start in Frappe CRM, while the quotation, the invoice and its eTIMS transmission to KRA stay in ERPNext, and the old opportunities stay where they are as history. For a team with a few dozen open deals, that beats the migrator outright. Import the open ones through Frappe's Data Import, which CRM Lead, CRM Deal and CRM Organization all accept, and leave the rest alone.

The step that reaches past the CRM: your item master

The activity rewrite does not stop at sales records, and this is where a CRM migration turns into ERP work. It walks 15 DocTypes, among them comments, emails, files, version history, tags and document shares, plus assignment ToDos, and changes the document type on every row that names any of its eight source types. It matches on the type alone. Item is one of the eight.

The Item step copies the whole Item table into CRM Product, raw materials and purchased parts included. The rewrite then hands every item's attached files, comments and version history to its CRM Product twin. Frappe's form loader finds a document's attachments and versions by document type and name, so on the ERPNext item form, the one your storekeeper and your accountant open, those rows no longer belong to the item. Cleanup leaves Item alone. Undo puts the rewrite back, but it refuses once Lead, Opportunity and Prospect are empty, which is what cleanup leaves, and from then on that history belongs to a CRM record the warehouse has no reason to open.

A team that runs ERPNext CRM happily on version 16, with no pull toward Frappe CRM's interface, has nothing to migrate yet, and we would tell it to wait for a version 17 date. If you are planning the move, send us how many leads, opportunities and prospects you hold, the status values you use, the custom fields on each, and whether quotations or customers link back to opportunities. Use the scoping form, choosing ERPNext CRM as what you run today, or WhatsApp on +254 713 403 044. You get back each record type marked as copies, needs a status first, or stays behind, the order we would run it in on a copy of your site, and one figure for the move. We run the move with you rather than handing over a script, and the scoping answer commits you to nothing.