Import

The following sections or pages explains the information required in order to successfully import records into a Drupal 5.x database.

Import Form - details required

To access the actual importing form or window click on the 'Continue to Importer Form' button. Another window will appear, as per the screen shot to the left. It is this form that accepts all the information.

Information required

Database type

'wp' - Wordpress (default)

'b2' - b2evolution

This should be obvious, if you're wanting to convert a Wordpress blog then 'wp' should be selected.

Host

If accessing the MySql database remotely, that is, on a hosted server, somewhere, other than your computer, then you will need to input the IP number. If you are unsure of the IP number it can be found at your CPanel, failing that, your hosting company can provide it.

If you are accessing the MySql database locally, that is, on your home computer, then 'localhost' should suffice.

Port

The default is '3306'. Regardless of whether you are accessing your MySql database remotely (across the internet) or locally (on your computer) the number will probably be '3306'. If not, your hosting company can provide the correct figure.

Database Name

The name of the MySql database file of either the Wordpress or b2evolution database. If unsure, simply check the relevant 'config' or 'settings' php file from either system.

Username

Enter the 'Username' that has access rights to the database. Again, if unsure, check the 'config' or 'settings' php file from either system for confirmation.

Password

Self-explanatory. If unsure check the 'config' or 'settings' php file from either system for confirmation.

Table Prefix

If your database (Drupal, Wordpress or b2evolution) was setup with the inclusion of table prefixes, then the correct table prefix must be entered. If no prefixes then no entry is required.

All the information explained above from 'Host' through to 'Password' is also applicable to the Drupal 5.x database setup settings.

Test Connection

All the database information above is required to be inputted. Clicking on the 'Test Connection' button merely confirms that a connection can be made. If a connection can't be made the user is advised. Unfortunately you will have to work out which piece of information is incorrect.

Preview Permalinks

Clicking this button will open a new window displaying the permalinks, if a Wordpress file. Can't do much with it, it's just for display purposes.

Source Summary

Clicking on this button will merely display the number of records for Posts, Comments, Users, Categories and Post/Category links. Can't do much with it, it's just for display purposes.

If available, import Permalinks

If importing a Wordpress blog and permalinks are active, it's from here where you can choose to either import them or not. Only choices available are "Yes" or "No". The default is "Yes".

Records to get (per Grab)

This figure corresponds to how many records (posts) are retrieved in one hit. The default is 200. The limit is from 10 through to 1000. If attempting to convert a massively huge database, problems can arise with overloading which ultimately, is probably, the cause of program hanging. This setting merely says only grab a small bit a time but keep returning grabbing a small bit until the whole lot is got. For massively huge databases we don't want 10,000 records coming down the line in one go, it simply doesn't work.

Post Types to be:

Prior to version 5-05 the converter transferred posts and created them as Blog entries in Drupal. Now the user has the option of selecting whether the posts to be transferred are either:

1. Blog
2. Page
3. Story

Start Importing Process

Clicking this button will start the importing process. The process will only start if the correct database connection settings have been input. Hence the reason for the 'Test Connection' buttons.

Upon successful commencement a pop-up window appears which reports the progress of the Users, Categories and Posts being imported.

Search and Replace

To be completed.

Versions

In the following pages I'll attempt to explain the reasons and features of any updates.

Problems, Issues and/or Bugs

This section details most of the problems regarding the converter. Why some things simply don't work. Actually, it won't be known initially why some things don't work but at least here I'm highlighting that I'm in fact addressing it, somehow.

Users

The steps that take place when importing users.

1. Prior to import, Usernames are scanned in Wordpress.
2. The Username about to be imported into Drupal is firstly checked against Usernames already in Drupal. If the username is a username in the Drupal database then the Wordpress username is prefixed with "u_" and a number.
   • eg. if 'Steve' is a Wordpress username and it is also a username within Drupal then it may become 'u_1_Steve'. If 'u_1_Steve' was already taken (as a result of a previous import) then the Drupal username could be 'u_2_Steve' etc. Within Drupal, no matter how many times Wordpress blogs are imported, usernames will be unique.

I suppose in the normal course of transferring a Wordpress Blog to Drupal, it's most likely going to be to a clean fresh Drupal installation. If that is the case, one would half assume that all the Wordpress usernames are unique and accordingly they will be transferred across, as is.

Categories

All Wordpress categories are imported into Drupal 5.x and they retain their hierarchical structure.

Within Wordpress it is possible to create sub-categories of categories. I'm not sure how deep they can be nested but that is not a limiting factor.

The converter scans the Wordpress categories and identifies the 'top level' categories. It maybe the case where all the Wordpress categories are 'top level', and not have any sub-categories. If that is the case see the tip at the end of this page.

As a 'top level' category is identified, a Vocabulary is created within Drupal by the same name prepended with a prefix, "v_" and a number. This is to ensure a unique vocabulary name.

A term (category) is then created in Drupal using the same Wordpress category name (no prefixes). This is required as it is possible in Wordpress to link posts to a 'top level' category. Within Drupal, 'top level' categories are Vocabularies and is not possible to link posts directly to a vocabulary.

If the converter identifies any Wordpress sub-categories, those sub-categories are imported into Drupal, as terms (categories) associated to the correct Vocabulary.

Tip

Prior to importing categories into Drupal it maybe beneficial to re-visit your existing Wordpress category structure. If there are 15 categories, all 'top level' categories and no sub-categories then 15 vocabularies are created. Each vocabulary will contain a term (category) of the same name as in Wordpress. This may not be your desired result.

As an example, if you have a sporting theme and created categories such as Football, Squash, Running, Golf etc it may be wise to create another category called 'Sports'. Edit all your other categories to be sub-categories of 'Sports'. Do not link any posts to 'Sports', only link to the sub-categories. During the conversion process, only one vocabulary will be created called "v_1_Sports" and all the other categories will be associated to "v_1_Sports". After conversion simply edit the vocabulary to a name of your choosing.

Permalinks

If Permalinks for Wordpress are enabled the Converter will correctly import them.

The user has a choice here. It may be the case that permalinks are enabled but the importing of them is not required. There is an option that can turn off permalink importing. The default is 'YES' import.

How permalinks work.

At the Wordpress end the permalink structure maybe something similar to "/index.php/2007/02/my_post". The actual URL therefore would be something similar to

"www.yoursite.com/index.php/2007/02/my_post".

Two options are available

(1) Install Drupal to the same sub-directory (as per Wordpress) and no other fiddling required.

(2) If Drupal is installed to a higher level directory ie root then it's simply a matter of changing your options at the Wordpress end. At Wordpress navigate to 'Options/Permalinks'. You will notice that the 'custom' permalink is already populated with something similar to:-

"/index.php/%year%/%monthnum%/%post_name%/".

Simply edit that line by prefixing it with the sub-directory name. Your edited custom value may be similar to this

"/blog/index.php/%year%/%monthnum%/%post_name%/"

Be advised though, that this permallink will not work for Wordpress, it's only a means to copy across the sub-directory name included in the permalink. Wordpress will accept the saving of this permalink even though Wordpress will not recognise it from a browser.

Clean URL's

Make sure to turn on 'Clean URLs' in Drupal. If not "?q=" will be included in the permalink.

Path Module

By default, upon a new or fresh installation of Drupal, the Path Module will not be enabled. This is not a problem. Permalinks will be recognised even with this module disabled.

With this module disabled, it merely means that it's not possible to edit the permalink. Enable it and editing will be possible.

Posts and Comments

The whole reason why this converter was written.

After each post is imported from Wordpress, comments, categories (post/category links) and permalinks are imported. The cycle continues until all posts imported.

If the user elected not to import permalinks then permalinks will be ignored.

If permalinks are to be imported, only non-draft posts will have permalinks.

If, for some unknown reason, there is a duplicate permalink, only the first will be imported. The duplicates will be ignored. At this point the user is not notified of this.

Teasers

Prior to version 5-05 the teaser was set at the first 600 characters of the body of the post. It became apparent that in some cases the teaser was, in a sense, left hanging, in that there were no closing HTML tags. This creates havoc for the main page.

What now occurs is this process. If there is any entry in a Wordpress 'post_excerpt' field then the contents of this field are added to the teaser field. Wordpress, at this point, has already stripped out any HTML. If there is no entry in the excerpt field then the entire body of the post is added to the teaser field. In effect, as if the option setting for teasers had been set to 'unlimited'. At least with this approach there will be no issues of any unclosed HTML tags.

Connect to MySql Databases

Before any importing can be done a connection must first be made to both the Wordpress and Drupal databases. From the main opening window, clicking the 'Continue to Importer Form' button will open the connection form (if a connection hasn't already been established) or purposely clicking 'Connect to Databases' button.

All connection details must be entered correctly and connection is established via clicking the 'Connect' button. When successful connections have been established to both databases only then will the 'OK' button become active. Clicking the 'OK' button will progress the user to the 'Importing' screen.

Please be aware that upon successful connection the connection settings are saved in a text file (connect.txt) in the same directory where this program resides. This 'connect.txt' file is insecure in that the passwords are easily determined. If this file is present upon loading then the connection settings are automatically filled in.

The following is a brief description of the information required.

Version

Select the appropriate Wordpress and Drupal versions. As of this writing only Wordrpess version 2.5 is available and for Drupal you have a choice between 5.x and 6.x.

Host

If accessing the MySql database remotely, that is, on a hosted server, somewhere, other than your computer, then you will need to input the IP number. If you are unsure of the IP number it can be found at your hosting administration site (CPanel), failing that, your hosting company can provide it.

If you are accessing the MySql database locally, that is, on your home computer, then 'localhost' should suffice. If 'localhost' doesn't work then '127.0.0.1' will.

Port

The default is '3306'. Regardless of whether you are accessing your MySql database remotely (across the internet) or locally (on your computer) the number will probably be '3306'. If not, your hosting company can provide the correct figure.

Database Name

The name of the MySql database file of either the Wordpress or Drupal database (depending upon whether your at the 'source' or 'target' connection setting tab. If unsure, simply check the relevant 'config' or 'settings' php file from either system.

Username

Enter the 'Username' that has access rights to the database. Again, if unsure, check the 'config' or 'settings' php file from either system for confirmation. If you are accessing the MySql database files locally, that is, on your computer, and have installed MySql with all default settings, then the odds are that the user name will be 'root' and no password.

Password

Self-explanatory. If unsure check the 'config' or 'settings' php file from either system for confirmation.

Table Prefix

If your database (Drupal, Wordpress) was setup with the inclusion of table prefixes, then the correct table prefix must be entered. If no prefixes then no entry is required.

Import

In order to arrive at this form a successful connections must have been established. It is from this window where the importing process begins. As of version 1.03 the user now has more options to control how the import should proceed.

The following briefly describes the various options.

Records to get (per Grab)

This figure corresponds to how many records (posts) are retrieved in one hit. The default is 200. The limit is from 10 through to 1000. If attempting to convert a massively huge database, problems can arise with overloading which ultimately, is probably, the cause of program hanging. This setting merely says only grab a small bit a time but keep returning grabbing a small bit until the whole lot is got. For massively huge databases we don't want 10,000 records coming down the line in one go, it simply doesn't work.

If available, import Permalinks

If permalinks are active, it's from here where you can choose to either import them or not. Only choices available are "Yes" or "No". The default is "Yes".

In order to preview the permalinks click the 'Preview Permalinks' button. A separate window appears listing all the permalinks per post. Only published posts will have permalinks.

Filter Format

The values stored in these (node & comment) dropdown controls are retrieved from your Drupal database. By default, the options available will probably be 'Filtered HTML' and 'Full HTML'. If there are other filter format types they will be displayed and available to be selected.

If your posts and comments contain numerous HTML tags, styles and attributes then most likely you will want to select 'Full HTML' as under that mode Drupal will correctly render the pages. That is, the HTML tags are adhered to. If choosing 'Filtered HTML' then some of the HTML tags, styles and attributes might not be recognised and the page not displayed as intended.

Empty Drupal Tables

Clicking this button wipes out all posts, comments, categories and users (except user 1) from your Drupal database. This is useful if you wish to start over again and again.

Import

When all configuration items have been dealt with the 'Import' button will become active and clickable. This button starts the importing routine. Upon successful commencement a pop-up window appears which reports the progress of the Users, Categories and Posts being imported.

Importing Progress

If all the correct information has been entrered and the button 'Import' has been clicked the whole process starts. A pop-up window appears which merely indicates the progress of the entire operation.

It should be self-explanatory what is being indicated though I'll explain anyway.

You will notice there are two components to the progress indicator. One is the 'bar' indicating percentage done and the other is a figure to the right of the bars. This figure reports the number of records processed per bar.

There are six progress bars:-

• Categories
• Users
• DB Accesses (Record Grab)
• Posts (Imported)
• Comments (Imported)
• Analysing Categories

Most likely Categories and Users should be progressed fairly quickly before DB Accesses and Posts start. Most of the time will probably be spent processing DB Accesses and Posts and their associated comments and categories.

As previously explained, 'DB Accesses' merely represents how many times the program is accessing the database in order to retrieve 'x' number of records in one hit. The 'x' number of records by default is 200. So 1 DB Access equals 200 records received.

As records are retrieved from the database they are processed and converted into Drupal. The actual process of converting into Drupal should tick over at a steady speed. Where the delays will occur are in the retrieving of the records. If retrieving 200 records from a 10,000 record database, that will take some time, be patient.

At the conclusion and barring any problems the program merely reports 'Done'.

That's it, you should have successfully converted records into a Drupal 5.x/6.x database. All you have to do is check from your browser that everything worked.

There are other areas of concern, such as how images and links should be handled. This can be addressed by the use of the 'Search and Replace' module.

Users

The steps that take place when importing users.

Prior to import, Usernames are scanned in Wordpress.

The Username about to be imported into Drupal is firstly checked against Usernames already in Drupal. If the username is a username in the Drupal database then the Wordpress username is prefixed with "u_" and a number.

eg. if 'Steve' is a Wordpress username and it is also a username within Drupal then it may become 'u_1_Steve'. If 'u_1_Steve' was already taken (as a result of a previous import) then the Drupal username could be 'u_2_Steve' etc. Within Drupal, no matter how many times Wordpress blogs are imported, usernames will be unique.

I suppose in the normal course of transferring a Wordpress Blog to Drupal, it's most likely going to be to a clean fresh Drupal installation. If that is the case, one would half assume that all the Wordpress usernames are unique and accordingly they will be transferred across, as is.

Categories

Wordpress categories are the main reason for the upgrade from Wordpress 2.2 to 2.3. Wordpress 2.5 is based upon version 2.3. The actual importing of Wordpress categories is now simpler.

Wordpress 2.3/2.5 introduced vocabularies and terms, similar to the Drupal way of doing things.

By default, Wordpress 2.5 records three vocabularies and within each vocabulary terms (categories) are recorded.

The vocabularies are:

• category;
• link_category and
• post_tag

The 'category' vocabulary is where formal categories (terms) are recorded beforehand. That is, when creating a post the category must exist and can not be created at that time.

The 'post_tag' vocabulary is where 'tags' are freely created at post creation. In effect 'free form' categories. In the old days these were referred to as keywords.

The 'link_category' vocabulary relates to url links that are created and reside to the sidebar of a Wordpress 2.5 page. The terms created within this vocabulary are ignored by the converter. They are simply not relevant to the posts.

The above three vocabularies are imported into Drupal, even the 'link_category' even though the terms will not be imported. Each vocabulary is prepended with "v_" and a number followed by the Wordpress vocabulary name ie v_1_category or v_2_post_tag. This is to ensure a unique vocabulary name.

All Wordpress categories are imported into Drupal 5.x and they retain their hierarchical structure within their associated vocabulary.

Permalinks

If Permalinks for Wordpress are enabled the Converter will correctly import them.

The user has a choice here. It may be the case that permalinks are enabled but the importing of them is not required. There is an option that can turn off permalink importing. The default is 'YES' import.

How permalinks work.

At the Wordpress end the permalink structure maybe something similar to "/index.php/2007/02/my_post". The actual URL therefore would be something similar to

"www.yoursite.com/index.php/2007/02/my_post".

Two options are available

(1) Install Drupal to the same sub-directory (as per Wordpress) and no other fiddling required.

(2) If Drupal is installed to a higher level directory ie root then it's simply a matter of changing your options at the Wordpress end. At Wordpress navigate to 'Options/Permalinks'. You will notice that the 'custom' permalink is already populated with something similar to:-

"/index.php/%year%/%monthnum%/%post_name%/".

Simply edit that line by prefixing it with the sub-directory name. Your edited custom value may be similar to this

"/blog/index.php/%year%/%monthnum%/%post_name%/"

Be advised though, that this permalink will not work for Wordpress, it's only a means to copy across the sub-directory name included in the permalink. Wordpress will accept the saving of this permalink even though Wordpress will not recognise it from a browser.

Clean URL's

Make sure to turn on 'Clean URLs' in Drupal. If not "?q=" will be included in the permalink.

Path Module

By default, upon a new or fresh installation of Drupal, the Path Module will not be enabled. This is not a problem. Permalinks will be recognised even with this module disabled.

With this module disabled, it merely means that it's not possible to edit the permalink. Enable it and editing will be possible.

Posts and Comments

The whole reason why this converter was written.

After each post is imported from Wordpress, comments, categories (post/category links) and permalinks are imported. The cycle continues until all posts imported.

If the user elected not to import permalinks then permalinks will be ignored.

If permalinks are to be imported, only non-draft posts will have permalinks.

If, for some unknown reason, there is a duplicate permalink, only the first will be imported. The duplicates will be ignored. At this point the user is not notified of this.

Teasers

Teasers are created under two conditions.

If the Wordpress post entry contains the tag <!--More--> a teaser will be created. At the same time the tag <!--More--> is replaced with the Drupal version break.

If there is any entry in a Wordpress 'post_excerpt' field then the contents of this field are added to the teaser field. Wordpress, at this point, has already stripped out any HTML.

If there is no reference to either <!--More--> or the post excerpt field then the entire body of text is added to the teaser field.

Comments

If the 'Comment Status' of a Wordpress post is 'open' then the corresponding Drupal comment moderation is assigned as 'Read/Write'. If 'Comment Status' is 'closed' then Drupal comment moderation is assigned as 'Read Only'.

1.03

As promised the Wordpress to Drupal 6.x converter (Version 1.03) is now available for download.

What's new.

• Conversion to 5.x and 6.x
• Filter Formats specifically retrieved from Drupal
• More flexibility re - Content types, Promote to Front page and published
• Teasers created re - <!--More--> tag
• More thorough snapshot of the Wordpress database

For full details see the manual.

1.04

Bug fixes and enhancements for Version 1.04.