Importing

XenForo has the ability to import information from other forums, including users, forums, threads, posts and private messages, along with various other data.

This can be extremely useful if you are migrating your forum from another software package, or if your forum needs to merge with, or absorb another forum site.

At the time of writing, XenForo 2 supports importing data from the following sources:

  • XenForo 2
  • vBulletin 3.6 to 5.3
  • Invision Forums 3.0 to 4.2

Note

Indirectly, you can also collect data from a number of other systems by importing into XenForo 1.5, which currently has a larger selection of importers, and the running an upgrade on the XenForo 1.5 database to version 2.

Selecting an importer

You can start the import system by clicking on Import data, in the Tools section of the XenForo admin control panel.

On this page, you will be asked to choose an import source. The sources listed are grouped by the system into which they are designed to import.

Note

At the time of writing, all existing importers target XenForo itself, but in time there may be importers that target the XenForo Media Gallery, the XenForo Resource Manager, or even third party add-on products.

Once you have selected an importer that matches the source data you want to import, hit the Continue button.

Configuring an import

Each importer defines its own requirements, and will present you with a series of forms to complete in order to gather the information it needs in order to proceed. Generally, this will involve the database connection details for the source system.

Some importers will attempt to make your life easier, by looking for a config file for the source system, assuming that your XenForo is installed in the same location as the source system was previously. If a config file is found, the import system will attempt to fill in as many of the form fields as possible with the data from the config file.

After you have completed the necessary details, click the Continue button and the importer will attempt to connect to the source database. If a successful connection is made, the system will be able to proceed. If not, the system will show an error message that may help you to diagnose the connection problem.

Selecting import steps

On the next page, you will be presented with a list of steps that the importer can run, each corresponding to a different data type. Some steps are dependent on other steps - for example, posts can not be imported without threads, and threads can not be imported without forums.

Notwithstanding step dependencies, you may un-check the steps that you want to skip - for example you might want to import users but not bother with their avatars.

Note

Once the import has started, you can not go back and change the steps you want to import. Ensure that you have selected all the steps you want to import before you set the system running.

Retain content IDs

At this point, you will also be asked if you want to Retain content IDs. This option can only be used on a completely empty XenForo installation, that has no threads and posts. The setting will attempt to retain the IDs of the data that is imported, so that a thread that has an ID of 2563 in the source database will be imported with an ID of 2563 in the XenForo database.

If Retain content IDs is not selected, data will be imported with sequential IDs that do not match the source database. This is the default option, and in most cases is faster and more reliable.

Don't worry about existing links in search engines etc. pointing to URLs using the old source IDs. Many importers supply redirection scripts that can seamlessly redirect visits to old pages in your source system to their corresponding new pages in XenForo.

Import log table

You will also be asked to provide the name of a database table that can be used to store the log of the import. You can use any valid database table name, provided that the table does not already exist, or is an empty table.

We would suggest a name using only lower-case letters, digits and underscores, such as import_log.

If the table does not exist, the system will attempt to create it. If it does exist but already contains data, you should run a TRUNCATE TABLE your_table_name; query, assuming that you are certain that the data contained within the your_table_name table is okay to delete.

Once you have completed the form successfully, hit the Continue button...

Step configuration

In some cases, some steps will require additional configuration before the import can commence.

If the system imports users, you will usually be asked if you want to automatically merge users with the same email address, and if you want to merge users with the same user name. These options are particularly important if you are importing into a XenForo installation that is already live and has a collection of users.

It is usually a good idea to enable these user-merge options, particularly the same email option, as it is highly likely that two users with the same email address are in fact the same person. Whether or not you enable the same user name option depends on whether or not you know that some of the users in your source database share names with users in your XenForo database, and are in fact the same user.

For example, if your XenForo installation has a user called 'Admin', and so does your source database, the merge option will import all data belonging to 'Admin' in the source system as data belonging to 'Admin' in your XenForo installation, rather than creating an 'Admin2' user and attributing all the threads and posts to them.

Depending on the source system, other steps may need configuration. For example, the vBulletin importers need you to verify the location of your avatar and attachment files if they are not stored in the database.

Sometimes, the system will make a best-guess, based on the information it can retrieve from the database, but this often needs to be double-checked in order to ensure that the information is correct before starting the import. Most importers will do as much error-checking as is necessary to ensure a successful import before allowing you to proceed.

When your steps are configured, click the Continue button, hopefully for the last time.

Running the importer

After all configuration is successfully completed, the importer will be ready to run.

Warning

Always perform a full backup of your XenForo database, and the data and internal_data directories before running an import. Your source database and source files will never be modified, but a backup of your XenForo database and files provides for a safety net in the event that the import goes wrong and you need to start again. It is also a good idea to close your forums (using the Board Active option) for the duration of the import process.

There are two ways to run the import process, either through your web browser in the admin control panel, or via a command line / terminal connected to your web server via SSH or similar.

The command line (CLI) import method is significantly faster than the browser method, but requires that you have shell access to your server to run the command.

Browser importer

If you select the Browser importer option, simply click the Start import button and follow the on-screen prompts until the import is complete. You will see counters incrementing for each step as it runs, which may give you some indication of the time remaining for your import to complete.

You will need to prompt the browser to continue to the next step each time it completes the previous step.

CLI importer

To run the CLI importer, you will need to leave your web browser open on the Start import page, and log in to your web server using SSH or a similar method that allows you to run commands directly on your server.

Once logged in, change the current working directory to the folder in which your XenForo installation resides, for example /var/www/public/. You will know that you are in the correct directory, because it will contain a file called cmd.php.

We will use this cmd.php file to run the import, using the following command:

php cmd.php xf:import

Enter this command and hit the enter key and the import will start. All steps will run sequentially and without interruption, showing you progress indicators for each step.

Note

Both the browser importer and the CLI importer can be resumed if they are interrupted for any reason. While you should aim to allow the processes to complete without interruption, as some data may be lost, you can resume the import process by clicking on Tools > Import data in your admin control panel, or running the CLI command again.

Completing the import

Once the import process has run its course, either through the browser or the command line, you will either be taken to the Complete import page, or directed to refresh your browser so that the Complete import page is shown.

Here, you will see a summary of all the steps that were run, along with the time taken to run each step, and how many items were imported by each step.

Only one thing remains before your imported data is ready to be used, which is a rebuild of all the caches that XenForo uses. These will be built when you hit the Complete import button. This process may take a few moments, or several minutes to complete, depending on the volume of data that was imported, and how much data was already in your XenForo database.

Redirection

Some importers provide redirection scripts, which are designed to sit in the location of your original source software and intercept request for content from that source system.

The redirection scripts can then query the table you defined as the import log table in order to get the necessary URL for the content in your XenForo installation that corresponds to the data requested by the original URL.

The scripts the seamlessly redirect the visitor to the new content, while sending an HTTP header that tells the browser that the content has permanently moved to a new location.

This permanent redirection HTTP header allows search engines to find any content they previously indexed from your original source software, and they will update their URLs to point to the new location as a result.

Import speed

While it is entirely possible for importers to fetch data from a remote server, network latency will be a significant factor in these instances, due to the fact that each import step could be running several thousand queries to fetch and import the data.

The time spent waiting for the data to be fetched over even a very fast local area network will result in massive slow-down compared to imports performed on a single server.

For the fastest possible import process, back up the database and files on your servers and then perform the import on the fastest possible server available to you, with both the source and destination databases and files located on that server. Once the import is complete, you can deploy the resulting database and files to your live production environment.