Importing from Blesta

The Blesta importer reads an existing Blesta installation’s MySQL database directly and rebuilds its clients, packages, services (domains included), invoices, payments and support tickets inside RackHelm. It lives at Import Data → Blesta Data Import (/admin/import/blesta) and is part of the import family described in Data Import Tools. If you are moving from WHMCS or ClientExec instead, see Importing from WHMCS or Importing from ClientExec.

Before you start #

Warning: Import into a fresh install, and take a database backup first. The importer writes directly into your live catalogue, users, orders, invoices and tickets. There is no undo.

You need read access to the Blesta MySQL database — host, port, database name, username and password. A read-only account is sufficient, and importing from a restored copy of the database works just as well as the live one. In a default install only a Super Admin sees the Import Data menu; the permission details are in Data Import Tools.

What does not come across #

Blesta encrypts service field values, module credentials and stored card data with a key held in that installation’s config/blesta.php, so none of it is imported. Two things follow from that:

• Client passwords are not portable. Imported clients are created with a random password and use Forgot password the first time they log in.
• Saved payment methods do not transfer. Card data is encrypted with the old installation’s key, so customers re-authorise their payment method once after the move.

Note: Blesta has no separate domains table — a registered domain is an ordinary service whose package uses a registrar module. Domains are therefore imported as part of Services, not as their own group.

Connection #

Field	Notes
Database Host	Required. Pre-filled with 127.0.0.1 — but see the warning below.
Database Port	Required. Defaults to 3306.
Database Name	Required. Typically blesta; it is named in config/blesta.php on the Blesta server.
Database Username	Required. A read-only account is sufficient.
Database Password	Required.

The credentials are used once to run the import and are not saved to the system.

Warning: By default the database importers refuse private and reserved addresses, including 127.0.0.1 and anything on your LAN — the host is resolved and pinned to a public IP before connecting, to stop the form being used to probe internal services. To import from a local or internal database, enable the importer’s allow-private override in .env first — see the private-address guard in Data Import Tools and The .env File Explained. Without it you get the same generic “Could not connect to the specified database” message as a genuine connection failure.

Import options and sync modes #

Five entity groups can be imported independently:

Group	What it reads	Needs
Clients & Contacts	Clients, their contacts and their login users. Imported clients are given your default client role.	—
Packages & Pricing	Package groups, packages, their terms and configurable options. Terms become billing cycles; configurable options become configurable options.	—
Services & Domains	Services — including domains, which Blesta stores as services of registrar-module packages.	Clients + Packages
Invoices & Payments	Invoices, invoice lines and transactions.	Clients
Support Tickets	The Support Manager plugin’s departments, tickets and replies. If the installation never used Support Manager, there is nothing to import here.	Clients

The dependencies are enforced on the screen and again on the server: untick Clients and everything that needs it unticks and disables itself, so a group can never run without its prerequisites in the same run.

Each group has its own sync mode:

Mode	Behaviour
Try Update Before Insert	Updates an existing record where one matches, otherwise creates it. The default and the right choice for a re-run.
Only Insert (Skip existing)	Creates new records and leaves anything already present untouched.
Only Update (Skip new)	Refreshes records that already exist and creates nothing.

Tip: The modes make the import safely re-runnable. A common cutover plan: import everything early with Try Update Before Insert, keep trading in Blesta, then run the importer again just before the switch to pick up the delta.

Blesta-specific options #

Pricing currency #

The Pricing Currency field controls the catalogue only. RackHelm stores one price per product and billing cycle and converts at display time, so only a single Blesta currency can be imported as the catalogue. Leave it blank to use whichever currency Blesta has set as the default for the company being imported, or enter a three-letter code to pick another.

Your customers, their invoices and their credit are not limited to that currency: Blesta’s currency list, tax rules, per-client currency and VAT numbers are all imported alongside, and historic invoices keep the currency they were issued in.

Unpaid invoices that are already overdue #

Imported unpaid invoices arrive as pending, and RackHelm chases pending invoices on a schedule — reminder emails, then automatic suspension of every active service on the order (see System Schedules and the Scheduler). There is no limit on how old an invoice can be for that to happen, so the importer asks what to do with unpaid invoices that are already overdue:

Choice	Behaviour
Import them (they will be chased)	The overdue invoices come across as pending and enter the reminder and suspension cycle.
Leave them behind	The overdue invoices are skipped. Choose this if you settled or wrote off the old ledger before migrating.

The log reports how many invoices were affected either way.

Blesta Company ID #

Blesta can run several brands (companies) from one database. Leave the field blank to import every company, or set a company ID to import only one of them. The log lists every company it finds either way, so a blank first run is an easy way to discover the IDs.

Running it #

1. Fill in the connection details and choose your entity groups and modes.
2. Start the import. RackHelm tests the connection first and refuses to start if it fails.
3. The import runs in the background; the log panel on the page polls for progress every couple of seconds. You can navigate away — it keeps running.

Only one import runs at a time — a second attempt while one is in flight is refused as already running. The credentials are held briefly in the cache under a single-use key and cleared as soon as the background process picks them up; if they expire before it starts, just start the import again. The on-screen panel mirrors a log file under storage/logs/ on the server, and the run finishes with an Import Summary: block listing what was processed.

Tip: Do a first pass with Packages & Pricing only and check the catalogue looks right before importing clients, services and invoices on top of it. Everything downstream inherits whatever the packages pass produced.

After the import #

• Spot-check the catalogue, a few clients, their services and a handful of invoices against the Blesta originals.
• Tell your customers to use Forgot password on first login, and to re-add their payment method.
• Check your queue workers are running so any jobs queued by the import are processed — see Maintenance, Logs and Health.

Troubleshooting #

Symptom	Cause and fix
“Could not connect to the specified database” with details you know are correct	Almost always the private-address guard — the importer refuses internal hosts by default. See Data Import Tools for the .env override. The message is deliberately identical for every failure reason.
“Connection credentials expired”	The cached credentials are short-lived. Start the import again.
A group was skipped or cannot be ticked	Its prerequisites are not enabled in the same run. Services & Domains needs Clients and Packages; Invoices and Tickets need Clients.
“already running”	Only one import runs at a time. Wait for the current run’s Import Summary: before starting another.
The log panel stops updating	Read the importer’s log file under storage/logs/ directly on the server; the panel only mirrors that file.
No tickets were imported	Tickets come from Blesta’s Support Manager plugin. If it was never installed, there is nothing to import.
Only one brand’s data arrived	A Blesta Company ID was set. Clear it and re-run to import every company.