Plesk Email migration extension manual

Plesk migration extension manual

Introduction

Thank you for using the migration extension for Plesk. This manual describes this extension, what can be done and how.

The migration extension for Plesk is a frontend for our SaaS service - all you have to do is to enter your credentials for source and target account, choose a time at which the migration should start and submit the form. The data you entered will then be transferred via a ssl-encrypted connection to our servers, when the start time you chose has come, the migration will start.

Your credentials will be stored for only as long as needed, i.e. after the migration is finished, these data will be deleted, so you do not have to worry. However, if you want to even more security, we recommend the following procedure:

1. Change your credentials for source and target accounts before migration
2-. Use the email migration extension to migrate the account contents
3. After migration (or after resync) has finished, change the credentials again, either to the previous or completely new credentials
4. The credentials you entered are deleted on our servers now, and also changed - double security!

This way, you can be double safe!

1. Installation

To use the extension, you need to install it first - so log in to your plesk server backend (:8443) as admin user.

1.1 Installing the extension

Once logged in as admin, click on extensions in the left menu bar, this takes you to the extension catalog. Search for email migration and install the email migration extension by extro-media.

After installation, the extension is already usable, but is in free mode.
Please refer to chapter 2 (modes) to find out more about the different modes.

1.2 Installing and registering a license

After purchasing a license for the email migration, you should have received a "Activation Key" by your seller - e.g. from the official plesk extension shop.
You'll need this Key in order to install the license - installing the license will activate the commercial mode for the extension.
Licenses are available for 5, 10, 25,50 and 100 migrations. This means that if you purchase a license for one of these options, you can do the respective number of migrations, no matter how long you need to use them up.

To actually install the license, click on Tools&Settings, and then on License Management, then switch to the Tab Additional License Keys. Now click on Install Key and enter your activation key - after clicking ok, the key will be checked, and if the key is valid, be installed. Installing the key however is only the first step - now click on Extensions, go to the Tab My Extensions and find the Email Migration Extension in the list. Click on the button that says open to open the extension. by doing so, the license will be registered on our saas service, and you can view this license in the Tab License list, this list displays all your registered licenses for this server incl the respective number of migrations.

2. Modes

The Email Migration Extension is a freemium extension - this means that it has 2 different operation modes, free and commercial.
The difference is, that in free mode, you only have 2 migrations available (for evaluation purposes). In commercial mode, you can purchase and use as many migration as needed.

Additionally, in commercial mode you can use the mass migration feature which lets you enter multiple migrations at once. So if you need to migrate many accounts, there is no need to use the single migration form over and over again for each account to migrate.

2.1 Free mode overview

The free mode lets you access 3 tabs - Free migration, Migration status and Information.
The first tab lets you perform a migration by entering the respective credentials, and the start date resp. the resync date. After submitting the form, the entered data will be checked and if correct, transferred to our migration servers. The migration will then be started according to the start date you entered.

The second tab shows the status of the migrations that have already been submitted. During migration, you can see the number of messages that have already been transferred, the remaining messages, etc.

The third tab is the information tab which displays some more information about the extension and gives useful tips.

2.2 Commercial mode overview

The commercial mode lets you access 6 tabs - Migration, Massmigration, Active migrations, Finished migrations, License list and Information.

Like in the free mode, the first tab lets you perform a migration by entering the respective data like credentials, start and resync time etc.

The mass migration lets you do multiple migrations at once, just by entering a list of migrations. Please refer to chapter 4 for more information.

The tab active migrations displays the migrations that are currently active, i.e. not yet started or currently in progress.

Tab finished migrations - as soon as a migration is finished, it is removed from the active migrations list and will be listed in the finished migrations tab.

The license list tab displays the licenses that have already been registered. please refer to chapter 1.2 for more information about installing and registering a license.

Finally, the tab information displays more information about the extension and gives useful tips.

3. Performing a single migration (free/commercial)

In the single migration view, you can enter the data to do a single migration. Simply follow the steps and enter the data for 1. source 2. target and 3. timing

Please note that when entering your start and resync sate, do this according to your local time zone which is stated below the resync date

In the first line, you'll see number of remaining migrations and the number of total migrations you purchased(see license installation and registering). If you purchased, installed and registered 2 licenses (e.g. 10 and 5), you will see that your total number of migrations you purchased is 15. If you have already done 4 migrations, your available migrations counter is 11. If you have used up all your migrations, i.e. if the remaining counter drop to 0, you will see a message that informs you that all your migrations are used up. In this case you cannot do another migration, unless you purchase another license, install and register it.

Next, enter your data for source and target account. If you want to migrate from or to a an account that is hosted on your current server, you can use the quick selection, which lets you select one of the email accounts hosted on the server you are configuring. By doing so, the fields for email address, email username and server will be filled in automatically, all you have to do is to enter the pasword since this cannot be retrieved.

After entering the data for source and target accounts, the last step is to choose when your migration should start and resync. To prevent timing issues, like the migration starting too late or too early, you should enter the dates according to your local time zone, which is stated below the timing input fields. With this information, we can do a timezone correction, so your migration will start at the desired time. (Please note, the time zone displayed is the time zone of the server you are using, this is not neccessarily your time zone. Enter the start/resync time according to the time zone displayed.)

Now click the ok button to submit your data. The data will be checked - if the credentials are not correct, you will receive a respective message stating which data is not correct, source, target or both. In this case, the migration is not successfully submitted and thus the counter of remaining migrations is still the same. Check your input again and correct if necessary. If your input is correct, the data is transferred to our migration servers, and your migration will start according to the start date you entered. Also, you will see the migration in the active migrations list now.

This procedure is the same for free and commercial mode.

4. Performing a mass migration (commercial)

Mass migration is an interesting feature for all those who have a lot of migrations to do.

Imagine this: you have to do 50 migrations at once, or even more. Now you could enter all one by one via the single migration tab. But this is a very boring and lengthy task do.
If you need to to that much migrations at once, you probably already have a list of accounts to migrate (from-to). Now why not use this list to create a mass migration? Lets take a closer look at this tab.

As always, you'll see the number of remaining and total purchased migrations.
Next you see a simple input box, a description and some buttons, which obviously is quite different to the single migration form. This is because each line you enter in the input box is treated as one migration record. each record must contain the relevant data like type, email address, etc etc. Also, you cannot submit the form directly - first, a formal check must be done. This means, the extension chcks whether the data are correctly entered. checking for correct credentials is done once successfully submitted. After submitting, each record is checked like in the single migration tab. This means that if the credentials of one record are not correct (though formally it may be correct), this record will not create a migration, and afterwards, you will receive a warning stating the lines that contain erroneous credentials.

You must enter your records in the following format:

source.type;This email address is being protected from spambots. You need JavaScript enabled to view it.;source.username;source.password;source.server;target.type;This email address is being protected from spambots. You need JavaScript enabled to view it.;target.username;target.password;target.server;startdate;resyncdate

You can download a example file in the extension which exactly explains the single fields and what to enter. Basically, all data already known from the single migration form are needed according to the ordering as the line displayed above, separated by a semicolon (;) each.

The formal check: After entering your records, click the button 'formal check'. As already mentioned, this performs a formal check, i.e. the extension checks if the entered data is plausible, e.g. are all expected data present, are duplicates present, etc etc. After doing the check, you will see a result below the input box listing all records you entered.

If a field has a red background color, it means that this field contains an error you must correct.
If a line has a blue background, then this line is recognized as duplicate line, and you must remove it.
A transparent (white) background means that the formal check is ok for this field.
If the formal check says that no errors are detected, you can click the ok button to submit your migration records.

As the formal check alone cannot guarantee the the data are really valid credentials, these are checked before transmitting them to our migration servers. If one (or more) of the records (lines) contains invalid credentials, the respective line numbers are reported. The erroneous lines (records) are not transmitted to a migration server and must be corrected before re-submitting them.

After submitting, you can see the migrations in the active migrations list.
If one or more migrations had wrong credentials and thus did not get transmitted, you must re-enter these line(s).

5. Viewing status

As its name says, this tab displays the status of migrations currently active (not yet started or in preogress). Here you can view how many migrations are still to be done or currently running, also, you can see the status of each migration.

You can see how many messages are already transferred and the total number. If you are migrating from groupware to groupware, you can also see the calendar, contacts and tasks status.

5.1 Status in free mode

In free mode, the status is a combination of the commercial tabs 'active migrations' and 'finished migrations'. Since in free mode, you can only do 2 migration, it makes sense to keep things as simple as possible, so this tab displays both the finished and active (not yet started or running) migrations. The information you get are basically the same as in the commercial mode: You can see the source and target address, the start and resync date and the number of already migrated resp. total number of messages/items

Please note, if you have already done migrations in free mode and uninstall the extension, you will lose these personal data due to data protection regulations. However, you can still see that and how many migrations have been done.

5.2 Status in commercial mode

In commercial mode, the status is divided into 2 parts: active migrations and finished migrations.

In the tab active migrations, you can see the list of migrations that are currently active, i.e. these migrations are either waiting for migration to start, are currently treansfering mails or are waiting for resync. Like in the free status view, you see the source and target address, start and resync date etc. Click on a item in the list to get more information like the ETA (estimated remaining time) or number of total and remaining items for messages or groupware items.

In the tab finished migration, the already finished migrations are listed, i.e. these migrations that are fully migrated (incl optional resync) Like in the free mode, if you uninstall and reinstall the extension, you will only see that and how many migrations have been done before, but not the personal data due to data protection regulations.

6. Uninstallation

Uninstallation is easy and follws the general plesk extension uninstallation rule:

Click on Extension, then switch to the tab My Extensions - you will now see a list of your installed extensions on this server.
Now find the E-Mail Migration module for Plesk, and click on its title. Do not click on the open button, the extension will open in this case.
If you clicked the title, you will see the description of the extension, and the changelog.
To uninstall, find the 'more' button below the Title and click it. the button will expand and display the options disable and remove.
To finally uninstall, click on remove - the email migration extension will then be removed.
By doing so, the extension and its locally stored data will be removed. that means that the list of finished migrations will be cleared. If you reinstall the extension afterwards, you will only be able to see that migrations have been done, but not the account data. this is due to gdpr regulations.

7. Supported systems

Our system supports the following email systems

-IMAP
-Zimbra
-Exchange (office365)
-Exchange (on-premise)
-Plesk kolab
-Openexchange

Some limitations apply to these systems:

-Generally the servers must be reachable from the public internet
-IMAP accounts do not support groupware functionalities, i.e. contacts, calendars and tasks cannot be migrated to/from these accounts
-The servers to migrate to/from must be reachable from the internet, i.e. direct routing
-Exchange: ews must be activated and reachable in order to migrate groupware data (o365 has this)
-Exchange: imap must be activated and reachable (o365 has this)
-Calendar names with spaces might be converted, depending on the system
-Systems like gmail (imap) that apply special access rules must be configured first to allow access ("less secure apps" resp. "third party apps")
-further limitations not listed here may apply

8. General tips and tricks

Here are some helpful tricks that may make your life easier when migrationg email accounts

-Do not change the credentials of source and target account after adding a migration job and before finishing it - the migration might fail!
-Credentials will be checked by the extension before they are transferred to our migration servers. If you get a warning, it is most likely that you accidentially entered the wrong credentials.
-If your 2 free migrations are used up, you cannot add more migrations, except if you purchase a license. You will then see a message saying that all migrations are used up
-The active migrations list also shows how many messages already have been transferred, and the total number. the eta is not 100% exact, as the duration depends on many factor beyond our control, such as speed and load of source/target server, size and number of messages, connection speed, etc etc.
-Mass migration is a great way to migrate many accounts at once. however, it requires you to prepare your data. We recommend to create a template, copy it and add the respective data
-Licenses: if you already have a license installed and registered, and you need more migrations, you must terminate the old license before purchasing a new one. This is a requirement by Plesk
-IMAP is a standardized protocol for email servers. If your email server is IMAP compatible, then chances are good that a migration works (provided you meet the other requirements)
-If you need more information or have a problem, take a look at our kb/faq section, you can find many helpful tips there. most question should already have been answered there!