WHMCS - Domain Migrator Addon

Introduction

WHMCS-based automatic Domain Migration and Consolidation Addon. 

This tool is made for migrations at point of domain renewal to minimize costs and for optional customer communication within the migration process to avoid transfer rejections. The scope of this Addon is therefore not about getting domain names imported from your registrar account to WHMCS. It is about consolidating from Registrar A to Registrar B via Transfer. If you're looking for a way to get domains names imported, please check the article WHMCS - Domain Importer Addon.

If you have doubts related to prices, please contact our Sales Department. We'll be happy discussing options with you. The more domains you have with us, the better your prices.

We are highly interested in helping you getting your entire domain portfolio migrated to us. We are experienced with migrations in case of questions / support.

The customer is king, is a principle to which we ascribe.

Features

  • Migrate from different registrars to one or multiple registrar brands of the CentralNic Group PLC (HEXONETCentralNic ResellerTPP Wholesaleinternet.bs) in parallel
  • Migrate all TLDs or just a subset of TLDs per losing registrar
  • Bulk transfer for domains that can be transferred for free (0Y period) e.g. .qa, .ae, .es, .au, …
  • User Interface for configuration and management of domain migrations
  • Support for WHMCS Notification System allows for flexible notifications
  • Email Notifications to your WHMCS Administrators (or custom email address) about the migration process
  • Fully customizable Customer Notification over Email - language and tld-specific Email-Templates supported!

Benefits

  • Saving costs: Migrate at the point of domain renewal
  • Fully automated, you just need to spend time on installation, configuration and checking logs

How it works

The module intercepts domain renewals, and if a configuration mapping matches, it aborts the renewal and initiates the Migration / Transfer to the gaining registry instead. Still, the domain renewal order itself is left in WHMCS and is used for invoicing the transfer.

By default, only Domains in Status Active, Expired and Grace Period (Expired) are considered by the migration tool. For all other cases the renewal will be processed normally. You can configure the module to also ignore domains in Expired and Grace Period (Expired) status.

The necessary EPP/Authorization codes are retrieved either from the configuration or dynamically through the losing registrar’s module.

If locked, we'll try to unlock the domain for the transfer process automatically. In addition this tool can inform your clients by mail about the process.

Migration Best Practices

Customer Communication in advance is the key and better than using our migration tool client mail-out functionality. Get in touch with your clients directly and inform them about the provider change. Our tool would inform them where the migration happens - at the expiration date of the domain name. This doesn’t leave you much time for communication and fixing transfer issues - That’s the reason why we suggest to inform your customers earlier. The losing registrar will send an email per domain transfer to your customer allowing to accept or reject it. Important is that your customers are informed so that the risk of rejected transfers are minimized.

Automatic unlocking of domain names right before initiating the migration / transfer doesn’t work for some registrars. Find known cases documented in the Troubleshooting section at the end. We suggest to unlock domains then manually if this case applies to your situation.

A good idea might be to configure the due date for renewals to give a customer enough time for paying the renewal invoice. Our tool will only be invoked at expiration date in case the invoice is (marked as) paid. That’s basically how WHMCS Core behaves - a Renewal will just be forwarded to the underlying registrar if paid. We intercept at that point and reject the renewal in favour of a migration/transfer in case your custom configuration of our migration tool identifies the appropriate domain name / TLD as a migration case.

Best case would be to have a development / QA system that is connected to the OT&E environment of the losing registrar and the gaining registrar to test how our tool works. This allows you to identify in advance upcoming issues or in general topics that might need your attention. Still, you can skip that part if not available on your side or if one of the registrars does not offer an OT&E environment.

Premium Domains: As of a bug WHMCS solved with v7.8, any premium domain registered before v7.8 has incomplete data in the database and therefore a renewal won’t be working. This also applies when trying to transfer. Please get in touch with us.

Installation / Upgrade

Read the article "WHMCS - Module Installation & Upgrade". We are shipping all Modules as part of our Software Bundle.

Configuration

Addon configuration

Navigate to WHMCS Admin Area > System Settings > Addon Modules

Activate the CNIC Migrator Add-on, give the module “Full Administrator” Access Control right.

Setting

Default

Description

Send mails to admins

Enabled

Notify WHMCS admins about transfer activity. We recommend leaving this enabled.

Send mails to clients

Disabled

Notify clients about transfer activity.

Log activity

Enabled

We recommend leaving this enabled for easier diagnostics.

WHMCS Instance ID

WHMCS

Used for distinguishing different WHMCS instances in logging.

Renew if expired

Enabled

Renew expired domains at current registrar instead of migrating.

Reseler name

Company Name from WHMCS General Settings

This will be used in notification e-mails.

Reseler URL

URL from WHMCS General Settings

This will be used in notification e-mails.

Reseler email

Email Address from WHMCS General Settings

This will be used in notification e-mails.

Access Control

None

Set this to the admin groups that should have access to the addon.

Define mappings

In the WHMCS Admin Area, navigate to Addons > CNIC Migrator, then click on the Mappings tab.

adminareaerror

Here you can define your desired mappings, specifying the desired losing and gaining registrars, any specific TLD, and wether the migrator should automatically retrieve the EPP auth codes via the losing registrar’s WHMCS module.

EPP/Authorization Codes

The migrator will attempt to retrieve the EPP code automatically via the losing registrar’s module.

Some registrars however, do not support this functionality. Their module will return an error, but send the code out to the current registrant’s email address instead. So, not reliable for real-time processing. A good example is the registrar Enom.

As a workaround, you should get hold of the EPP codes manually (for example by requesting it and having your customer send you the code they recieve via e-mail). Then, you can specify those EPP codes beforehand in the EPP Codes tab in the Addon.

adminareaerror

When initiating a transfer, the migration addon will first check if any EPP code has been specified for the related domain, and then fallback to the losing registrar’s registrar module functionality, if enabled in the mappings.

Email Notifications

This migration tool also takes care about sending emails to your clients explaining them what is going on to avoid domain transfer rejections as far as possible. This is by default turned off to leave you the possibility to reach out to your customers using a different way. Still, you can turn that on to let this migration tool do that work. This can be done by enabling the Send mails to clients option in the addon configuration.

By default this tool is also sending mails to you, the reseller, to allow a bit of monitoring. This can also be turned off over Send mails to admins setting.

Client Email Templates

This migration tool comes with a default email template in english that will be used for mail-out to your clients. You can define more languages, customized subjects and messages, as well as TLD-specific messages. Later, you can check the System Email Message Log in WHMCS for mails sent to your clients and view them.

The default configuration entry is always used as fallback, see below. Important is to have that empty string array key entry which represents the case “no language set”. Without this entry the email template won’t work in WHMCS as WHMCS by default selects email templates using language filter set to empty string.

The configuration file dist.configuration.json contains the mappings to the email templates. Here is an example:

{
  "templates": {
    "default": {
      // <-- the default configuration entry
      "": {
        // <-- this one is important, just reuse the english template
        "subject": "{$resellerLabel}: Change of domain provider for your domain {$domain_name}",
        "file": "tpl_client_default_english.tpl"
      },
      "english": {
        "subject": "{$resellerLabel}: Change of domain provider for your domain {$domain_name}",
        "file": "tpl_client_default_english.tpl"
      },
      "french": {
        "subject": "{$resellerLabel}: Changement de fournisseur de domaine pour votre domaine {$domain_name}",
        "file": "tpl_client_default_french.tpl"
      }
    },
    "com": {
      "": {
        // <-- this one is important, just reuse the english template
        "subject": "{$resellerLabel}: Change of domain provider for your .COM domain {$domain_name}",
        "file": "tpl_client_com_english.tpl"
      },
      "english": {
        "subject": "{$resellerLabel}: Change of domain provider for your .COM domain {$domain_name}",
        "file": "tpl_client_com_english.tpl"
      },
      "french": {
        "subject": "{$resellerLabel}: Changement de fournisseur de domaine pour votre .COM domaine {$domain_name}",
        "file": "tpl_client_com_french.tpl"
      }
    }
  }
}

Email Templates Customization

NOTE: There’s no need to provide a full HTML template structure including head and body in the template files, just the HTML code part you need.

Even though the templates are HTML files, they are finally processed in WHMCS as Smarty templates and allow therefore the use of variables. This follows the principles of Smarty Syntax to use e.g. {$someVariable}.

The following variable names are available for the client email templates:

  • {$id}: The internal ID of your domain in WHMCS (indexed no.)
  • {$domain_name}: The Internationalized Domain Name
  • {$gainingRegistrarLabel}: A speaking label of the gaining registrar
  • {$losingRegistrarLabel}: A speaking label of the gaining registrar
  • {$resellerLabel}: Your/Reseller’s Label e.g. Reseller Pty Ltd
  • {$resellerContactEmail}: Your/Reseller’s contact email address
  • {$resellerContactURL}: Your/Reseller’s web page URL for a contact form or similar
  • {$client_name}: Name of your client
  • {$signature}: Your/Reseller’s signature

If you need something in addition, let us know.

Logging

If logging is enabled in the addon settings, it will happen in a variety of ways.

Addon Logging

In the Logs tab, you will find detailed logs about each transfer or renewal process initiated by the addon.

adminareaerror

The table is entirely searchable and sortable, and can be exported as CSV or Excel file if desired.

System Activity Log

In addition to the addon logging, some basic logging will be done in the WHMCS System Activity log. The messages will be prefixed by [cnicmigration].

WHMCS Notification System

  1. In the WHMCS Admin Area, navigate to System Settings > Notifications, then click on Create New Notification Rule. adminareaerror
  2. Give it a name and select the API > Custom API Triggerevent.
  3. Set the Trigger Identifier to Exact Match with cnic.migration.log as value.
  4. Last but not least, select and configure the desired notification provider.

Feedback Messages

Transfer initiated

Whenever our Migration Tool was able to initiate a Transfer in direction of the gaining Registrar, it will still abort the Renewal as this is the idea behind the migration approach. You can customize the message used to cancel the Renewal in WHMCS and to display in Domain Synchronization Report in the language files, for example modules/addons/cnicmigration/lang/english.php

$_ADDONLANG = [
    "defaultSuccessMsg" => "Domain Migration to the new subcontractor initiated. Don't renew the domain.",
];

In our logs it will show like:

  • [INIT_TRANSFER_SUCCESS]: Initiating the Transfer succeeded.

Even though we are talking about a success message here, it will still be displayed as an Error Result by WHMCS. We can’t change this.

Transfer skipped

Wherever a domain is not being transferred and instead still renewed at its current registrar, this could have one of the following reasons that are being logged:

  • [SKIP_DOMAIN_STATUS]: the domain status did not allow a transfer
  • [SKIP_DOMAIN_EXPIRED]: the domain is expired and the addon is configured to renew expired domains at their current registrar
  • [SKIP_NO_MATCH]: the registrar and/or tld are not configured for migration (see Define mappings)
  • [SKIP_MANUAL_RENEW]: the domain was manually renewed at the current registrar

Transfer not initiated

Whenever our Migration Tool is running into an error, it still aborts the renewal. Still the transfer is then not initiated as of the error occurred. This will be shown to your clients when it comes to the Domain Synchronization Mail.

You can configure the feedback messages in the language files, for example modules/addons/cnicmigration/lang/english.php

$_ADDONLANG = [
    "defaultErrorMsg" => "Domain Migration to the new subcontractor open. Don't renew the domain.",
];

The migration tool will append an error identifier to make it more transparent which kind of error might have happened, e.g. Domain Migration to the new subcontractor. Don't renew the domain.[ERROR_CONFIG].

  • [ERROR_CONFIG:...some reason...]: Configuration file migration/configuration.json couldn’t be loaded (missing or invalid json). Further Details provided.
  • [ERROR_DOMAIN_DATA]: Domain Data couldn’t be loaded over WHMCS - should never happen
  • [ERROR_AUTH_CODE:...some reason...]: Getting the EPP/Authorization code of the domain did not work. Further Details provided.
  • [ERROR_REG_MODULE]: Loading the gaining registrar’s registrar module failed or the module is not activated or not integrating the TransferDomain method
  • [ERROR_TRANSFER_FAIL:...some reason...]: Initiating the Transfer failed. Further Details provided.

Uninstall

After Migration has finished - this might take a while of course, cleanup as follows:

  • Disable the addon in the WHMCS Admin Area under System Settings > Addon Modules
  • Delete the folder modules/addons/cnicmigration

… et voila!

Troubleshooting

Find here some cases brought up to our hands:

resellerclubcrm module ending in an PHP Error - backtrace is pointing to language files. Even though this got escalated to the Module Devs, they just provided a workaround and not a new release.
Edit the file

/modules/addons/resellerclubmods_core/modlang/English_admin_lcdrm.php
and insert above line 25 the following code

$_ADMINLANG = array();

Such manual changes will be lost when upgrading your resellerclub core parts.

Illegal mix of collations error when opening the addon in the WHMCS Admin Area. This can happen on older WHMCS installations where database updates between WHMCS upgrades did not go smoothly, leaving some tables in a different collation. To solve this issue, it is necessary to convert the affected tables to the correct default collation, with a command like this:

ALTER TABLE tblexample CONVERT TO CHARACTER SET utf8 COLLATE utf8_unicode_ci;

Where tblexample should be replaced by the affected table. IMPORTANT: please backup your database befor making any changes! More information can be found in this WHMCS article

Was this article helpful?
0 out of 0 found this helpful