Importing from a WHMCS database

CoreInto can copy the records of an existing WHMCS installation (version 7.10 to 8.x) straight from its database: clients and their users, products and prices, orders, services, domains, invoices, payments, credit, quotes, tickets, the knowledgebase, downloads, affiliates and, if you want, the history of emails sent. Client, invoice, order, service, domain and ticket numbers stay the same, and clients keep their passwords. WHMCS itself is never changed; CoreInto only reads from it. The import can be run again as often as you like until the day you switch over. Secrets that WHMCS kept encrypted with its own key (gateway, server and registrar passwords, stored cards, service passwords) cannot be read and are left out on purpose; you enter them again in CoreInto afterwards.

This is the one chapter of the manual that names WHMCS, because the import page does.

Before you start

• Install CoreInto, run the installer, and sign in once. The import does not create staff: your administrators are made in CoreInto first.
• Have a database user that can read the WHMCS database, and the database name (in the WHMCS configuration.php as $db_name). When WHMCS and CoreInto are on the same hosting account, the server is usually localhost. When they are on different servers, the WHMCS database must accept remote connections from the CoreInto server.
• The permission "Import data" (import) is needed for the page. The command line needs shell access and reads configuration.php of the CoreInto install.
• An import into a CoreInto that already holds clients or invoices has to be a fresh import: everything an import brings in is removed first (see "What wipe removes"). Do not import into a CoreInto you have already started using for real, unless you mean to replace its records.
• A large WHMCS (tens of thousands of invoices or emails) imports faster from the command line, which has no web time limit.

Utilities > Import Data

The page has one form, "Copy from WHMCS".

Both the name and the user are required; without them the page says so.

Step 1: Check the Database

Press "Check the Database". CoreInto connects, checks that the database is a WHMCS database (it looks for the tblclients and tblconfiguration tables) and reads the WHMCS version, the company name and the number of clients, services, domains, invoices and tickets. It shows them in a notice such as "Found WHMCS 8.1.3 (Example Hosting): 2,310 clients, 1,980 services, 1,420 domains, 31,200 invoices, 8,900 tickets." followed by "Nothing has been copied yet. Press "Import Now" to copy it."

If the connection fails the page says "The WHMCS database could not be opened. Check the address, name, user and password." If the database is not a WHMCS database it says so.

After a successful check the password box is empty again, with the help text "Remembered for this import (leave empty); it is not saved." The password you typed is carried in the form sealed with the encryption key, for 30 minutes, and only for the staff member who typed it. Leave the box empty for the next step, or type the password again. After 30 minutes, or when another staff member picks up the page, it has to be typed again.

Step 2: Import Now

Two buttons appear under the notice:

• Import Now: asks "Start the import? It can take a few minutes for a large WHMCS." and runs the import. The page stays busy until it is finished; do not close it.
• Check Again: reads the counts again without importing.

When CoreInto already holds clients or invoices, a box appears above the buttons: "Remove the clients, products, invoices and tickets now in CoreInto first (needed to import again)". Tick it to run a fresh import; without it the import refuses with "CoreInto already has clients or invoices. Import again with "remove what is there" ticked."

While the import runs, PHP's time limit is lifted and the import carries on even if the browser connection drops. If it stops with an error, the message is shown on the page and written to the activity log ("WHMCS import stopped: ..."). Whatever was copied before the error stays; fix the cause, tick the remove box and import again.

When it finishes

The page shows "Import finished" with:

• A button "Open the client list".
• The table "Compared with WHMCS" (see "The comparison" below).
• "Everything that was copied": every count the import kept, folded away.
• "Please note": the notes the import made about things you must do by hand (see "The notes").

The activity log gets a line "Imported WHMCS VERSION: N clients, N invoices". The form is shown again below the result, with the remove box unticked, so the import can be repeated later.

The command line: php cli.php import-whmcs

On a server with shell access, from the CoreInto folder:

php cli.php import-whmcs --db=NAME --user=USER [--host=localhost] [--port=3306] [--socket=PATH] [--wipe] [--no-emails]

The password is read from the environment variable WHMCS_DB_PASS if it is set; otherwise the command asks for it without echoing it. The command first brings the CoreInto database up to date (the same as php cli.php migrate), then prints a line such as WHMCS 8.1.3 (Example Hosting): 2310 clients, 1980 services, 1420 domains, 31200 invoices, one line per step as it goes (... clients and users, ... products and prices, and so on), then every count, the comparison table with <- differs on any row that does not match, and the notes. Other commands of cli.php are in Command line.

What wipe removes

"Remove ... first" on the page, or --wipe on the command line, empties exactly the tables an import fills, so the import can be run again until the switch-over. These are:

It also ends every client session, and removes the payment methods that an earlier import created (they are marked as imported). The import of domain extensions, when WHMCS has any, replaces the whole extension list and its domain prices too.

Wipe never touches: staff accounts, roles and permissions, API credentials, settings (apart from the handful the import sets, listed below), email templates, currencies (they are added to or updated, never deleted), payment gateways you added yourself (but a gateway the import created is removed, even if you have since entered keys into it), registrars, order statuses and ticket statuses you added, banned addresses, the logs other than the email log.

What is brought across

The import runs in this order and reads these WHMCS tables. Numbers (ids) are kept, so a client who was #482 in WHMCS is #482 in CoreInto, invoice 10231 is invoice 10231, and ticket links keep working.

Currencies and staff

• tblcurrencies: each currency is matched by code to a CoreInto currency (prefix, suffix, format and rate are updated) or added. If the WHMCS default currency differs from CoreInto's, it becomes the default, with a note.
• tbladmins: staff are not copied. Each WHMCS administrator is matched to a CoreInto staff member by email or username, so notes, to-do items and ticket notes are credited to the right person. An administrator with no match is credited to the first CoreInto staff member.

Clients and users

• tblclientgroups: client groups with colour, discount, suspension exemption and separate-invoices flag.
• tblusers (WHMCS 8): users with their bcrypt or Argon password hashes, names, verification and last sign-in. A password in an older format is not carried; the user must use "Forgotten your password" once, and the notes say how many. Users who had two-step sign-in must set it up again (the count is in "Everything that was copied").
• tblusers_clients: which users belong to which client, who the owner is, and their permissions (only permissions CoreInto knows are kept).
• WHMCS before 8.0 (no tblusers): one user is made per client from the client's own email and bcrypt password.
• tblclients: name, company, email, address, country, phone, tax id, currency, group, status (active, inactive, closed), credit balance, default payment method, billing contact, the flags (tax exempt, late fee exempt, overdue notices off, separate invoices, automatic card capture off, auto-close exempt, marketing opt-in, single sign-on), email preferences, staff notes, sign-up address, last sign-in and creation date.
• tblcontacts: contacts with their email preferences.
• tblnotes: staff notes on clients, sticky flag kept.
• tblmarketing_consent: the consent history.
• tblcustomfields and tblcustomfieldsvalues: custom fields for clients, products, add-ons and support departments (type, options, validation pattern, admin-only, required, shown on order and invoice) and their values. Values of password-type fields are skipped because WHMCS encrypted them; the notes say how many.

Products and prices

• tblproductgroups and tblproduct_group_features: groups with headline, tagline, hidden payment methods, hidden flag, order and their feature lists.
• tblproduct_upgrade_products and tblproduct_recommendations: which products a product may be upgraded to, and recommended products.
• tblproducts: products with type, group, description, featured, hidden and retired flags, pay type, "set up automatically" (order, payment, accept), the server module when CoreInto has a module of that name, the server group, the module settings, free subdomains and the free-domain rules. The welcome email is cleared on every product; a note reminds you to choose it again.
• tblproductconfiggroups, tblproductconfiglinks, tblproductconfigoptions, tblproductconfigoptionssub: configurable option groups, their links to products, options and values with prices.
• tbladdons: product add-ons with pay type, quantity, tax, suspend-with-parent and "set up automatically".
• tblpricing: price lists for products, add-ons and option values in every currency. Free products get no price rows.
• tbldomainpricing and the domain tblpricing rows: domain extensions with EPP code requirement, DNS management, email forwarding, ID protection, grace and redemption periods and fees, the "hot/new/sale" label, and register, transfer and renew prices per year and currency. The registrar set for automatic registration is kept when CoreInto has a module of that name (LogicBoxes, NetEarthOne, ResellerCamp and Stargate are mapped to ResellerClub). The allowed registration periods follow the years that have a register price.
• tblpromotions: promotion codes with type (percentage, fixed amount, price override, free setup), value, what they apply to and require, cycles, start and expiry dates, uses, lifetime and once-only flags, upgrades and notes.

Servers and payment methods

• tblservers: servers with hostname, address, assigned addresses, module (when CoreInto has it; otherwise the name is kept as it was), username, port, TLS, maximum accounts, monthly cost, datacenter, status address, nameservers, default and disabled flags. Passwords and API tokens are not copied (they were encrypted); a note reminds you to enter them again.
• tblservergroups and tblservergroupsrel: server groups with their fill rule (least full or fill first) and members.
• tblpaymentgateways: each payment method is created by name so that past invoices and payments keep showing the method they were paid with. Bank Transfer and Mail-in come across turned on, with their instructions text. PayPal and Stripe are created as those gateways but turned off, without keys. Every other method is created as a manual method, turned off. A note lists the methods that were turned off. Methods that already exist in CoreInto are left alone.

Orders, services and domains

• tblorders: orders with number, client, contact, status, amount, currency, payment method, invoice, promotion, nameservers, notes, address and fraud result.
• tblorderstatuses: order statuses that CoreInto does not have yet are added.
• tblhosting: services with product, server, status (pending, active, suspended, terminated, cancelled, fraud, completed), domain, username, dates (registration, next due, next invoice, termination), cycle, amounts, payment method, subscription id, dedicated IP, assigned IPs, disk and bandwidth usage, suspension reason and notes. Service passwords are not copied (encrypted); the notes say how many, and how to set a new one.
• tblhostingaddons: add-ons on services with status, quantity, cycle, amounts, dates and notes.
• tblhostingconfigoptions: the configurable options chosen on each service.
• tbldomains: domains with client, order, type (register or transfer), registrar (the CoreInto module name when there is one, otherwise the name as it was), registrant country, status (pending, pending registration, pending transfer, active, grace, redemption, expired, transferred away, cancelled, fraud), period, amounts, payment method, subscription id, registration, expiry, next due and next invoice dates, DNS management, email forwarding, ID protection, premium flag, auto-renew and notes. Nameservers are not read from WHMCS; they fill in on the first sync with the registrar. EPP codes are not copied.
• tblcancelrequests: cancellation requests (immediate or end of period); requests for services already closed are marked as done.
• tblupgrades: upgrade and downgrade records with status and paid flag.

Invoices and payments

• tblinvoices: invoices with number, client, status (paid, unpaid, cancelled, refunded, collections, draft, payment pending), dates (created, due, paid, last capture attempt), subtotal, credit applied, two tax amounts with their rates and the tax names from tbltax, total, payment method and notes.
• tblinvoiceitems: invoice lines with type and the related record, description, amount, tax flag and due date.
• tblaccounts: transactions with client, invoice, payment method, provider reference, date, currency, amount in, fees, amount out, exchange rate, description and the refund link. When the same provider reference appears twice for one method, the later ones get " (#id)" appended so they stay unique.
• tblcredit: the credit history with staff member, date, description, amount and invoice. After the import, every client's credit balance is compared with the sum of their history; a note says how many differ (the balance WHMCS showed is kept).
• tblbillableitems: billable items with quantity, amount, invoice action, due date and recurrence.
• tblquotes and tblquoteitems: quotes with stage (draft, delivered, on hold, accepted, lost, dead), validity, client or prospect details, totals, proposal text, notes and dates, and their lines.

Saved cards and other payment tokens are not copied; they were encrypted by WHMCS.

Support

• tblticketdepartments: departments with name, description, email address, the clients-only, replies-only, no-autoresponder, hidden and feedback-request flags, and the mailbox host, port and user. Mailbox passwords are not copied. Staff assignments are not read: the first CoreInto staff member is put in every department, so assign your staff to departments again.
• tblticketstatuses: ticket statuses CoreInto does not have yet are added.
• tbltickets: tickets with number, department, client, contact or name and email, subject, status, priority (low, medium, high), dates, the staff member assigned, flags and the first message. HTML entities WHMCS stored in ticket text are decoded.
• tblticketreplies: replies, by client or staff, with their dates.
• tblticketnotes: staff notes.
• tblticketlog, tblticketstags, tblticketfeedback: the ticket log, tags and ratings.
• Attachments are not copied: the files live in the WHMCS attachments folder. A note says how many messages had attachments.
• tblticketpredefinedcats and tblticketpredefinedreplies: predefined reply categories and replies.
• tblticketspamfilters, tblticketescalations: spam filters and escalation rules.
• tblknowledgebasecats, tblknowledgebase, tblknowledgebaselinks, tblknowledgebasetags: the knowledgebase. WHMCS stores articles as HTML; CoreInto shows Markdown, so headings, lists, links, bold, italic and code are kept and other formatting is dropped.
• tbldownloadcats, tbldownloads, tblproduct_downloads: download categories, downloads and their links to products. A download that is a web address stays a link. A download that was a file in the WHMCS downloads folder is created without its file; a note says how many, and you upload each file again under Support > Downloads.
• tblnetworkissues: network issues with status and dates.
• tblannouncements: announcements, HTML turned into Markdown.

Affiliates

• tblaffiliates: affiliates with client, date, visitors, commission settings, one-time flag, balance and withdrawn total.
• tblaffiliatesaccounts: referrals (the services an affiliate brought in; a referral whose service no longer exists is skipped).
• tblaffiliatespending, tblaffiliateshistory, tblaffiliateswithdrawals: pending commissions, the commission history and withdrawals (recorded as paid, with reference "Imported").
• tblaffiliates_hits with tblaffiliates_referrers: the click history with the referring site, 2,000 rows at a time.

Skipped when WHMCS has no affiliates table.

To-do list, email history and settings

• tbltodolist: to-do items with title, description, staff member, status and dates.
• tblemails (only when "Also copy the history of emails" is ticked): every email sent, 1,000 rows at a time, into CoreInto's email log with template name "imported", the recipients, subject, HTML body and a plain-text copy, status sent or failed with the failure reason. Each client's email history in the admin and client areas then shows them.
• tblconfiguration: only these settings are copied, and only when WHMCS has a value: company name, company email, invoice pay-to text, default country, date format, invoice number increment, sequential invoice numbering with its format and next number, order grace days, and tax inclusive or exclusive. Everything else keeps its CoreInto setting.

What is skipped on purpose

The comparison

After each import CoreInto counts the same things in both databases and shows them side by side with "Same" or "Differs":

Money rows are shown to two decimal places. Every row should be "Same"; a difference means something was skipped or changed, and the counts under "Everything that was copied" and the notes usually say why. The owner's own installation imported with every total matching.

The notes

Depending on the data, the import adds notes such as:

• "The default currency is now EUR, as in WHMCS."
• "12 users had passwords in an old format and must use "Forgotten your password" once."
• "3 password custom field values were encrypted by WHMCS and were not copied."
• "Welcome emails chosen on products were not carried over; choose them again on each product (Settings, Products/Services, Setup)."
• "Server passwords and API tokens were encrypted by WHMCS; enter them again on each server."
• "These payment methods were copied turned off, so past payments show their names: PayPal, Stripe, ... PayPal and Stripe can be turned on after entering your keys (Settings, Payment Gateways); the others arrive in a later update."
• "840 service passwords were encrypted by WHMCS and were not copied; set a new one with Change password on the service page when it is on a server."
• "5 clients have a credit balance that differs from their credit history in WHMCS; the balance was kept as WHMCS showed it."
• "260 ticket messages had attachments; the files live in the WHMCS attachments folder and were not copied."
• "17 downloads were files in the WHMCS downloads folder; upload them again on each download (Support, Downloads)."
• "Copied from the WHMCS settings: company name, email, pay-to text, default country, date format and invoice numbering. Everything else keeps its CoreInto setting."
• "Email templates were not copied; CoreInto's own texts are used. Change them under Settings, Email Templates."

Running it again until the switch-over

A good way to move:

1. Install CoreInto beside WHMCS and import. Look through clients, invoices, services and tickets, and set up servers and registrars (they are kept by the next import). The payment methods the import created are removed and made again by every later import, even after you have entered keys into them, so enter gateway keys after the final import.
2. Keep using WHMCS. Import again whenever you want a fresh copy, with the remove box ticked (or --wipe). Each run removes the earlier copy and brings everything in again, so changes made to imported records in CoreInto are lost each time; changes to settings, staff, templates, gateways and registrars stay.
3. On the day of the switch-over, stop taking orders in WHMCS, run the final import, check the comparison table, then point the client area address at CoreInto and turn its automation on.

The automation (cron) of CoreInto may run during a trial period, but note that it will create invoices, send reminders and suspend services for the imported records as if they were live. If you do not want that yet, leave the tasks off under Utilities > Automation Status until the switch-over.

After the import

• Settings > Payment Gateways: enter keys and turn the gateways on; past payments already show the right method names. See Payment gateways.
• Settings > Servers: enter each server's password or API token and test the connection. See Services and servers.
• Settings > Domain Registrars: set up each registrar and run the domain sync; the registrar module on each domain and extension is already set where CoreInto has that module.
• Settings > Products/Services: choose the welcome email on each product, and check modules and server groups.
• Settings > Email Templates: read CoreInto's texts and adjust them to your wording. See Email.
• Support > Downloads: upload the files of each download again. See Support.
• Settings > Support Departments: enter mailbox passwords.
• Tell users with old-format passwords, or with two-step sign-in, that they must reset once or set it up again.
• Check Settings > General Settings: only the handful of settings listed above were copied.

Related: domains at the registrar

Separate from the WHMCS import, each registrar's settings page has a "Domains at the registrar" tool. It reads the list of domains held in your registrar account, shows the ones not yet in CoreInto with the registrant's name and email as the registrar reports them, suggests the matching client, and lets you tick domains and enter a client number or email to bring them in. It is useful after the WHMCS import for domains that were never in the billing system, and for the .pk domains of a PKNIC account. See Domains and registrars.