Lesson 7.1: From WordPress #

WordPress is the source trainers meet most often. This lesson follows the WordPress guide of the documentation: what WordPress can export, how its content maps, the nine steps from export to cut-over, and the addresses that must keep working. It applies the frame of modules 1 to 3 to one real source.

At a glance #

Learning objectives #

After this lesson, learners can:

• name the four export sources of WordPress and say which one is the frozen source of the import;
• map posts, pages, attachments, categories, tags, custom fields and SEO fields to Exponential;
• put the nine steps of the WordPress guide in order;
• decide for each kind of WordPress address how it keeps working;
• explain the delta import before the cut-over.

Trainer's notes #

How to present it #

Source: WordPress and Exponential.

1. Exports (4 minutes). Tools > Export and wp export give WXR (posts, pages, custom post types, comments, custom fields, terms, users), without site configuration and without the files. The REST API gives JSON with pagination. The wp-content/uploads directory holds the files. WXR is the frozen source; the REST API serves the delta of the last days.
2. Mapping (6 minutes). Show the mapping table: posts to article objects below a blog folder; pages as a tree following post_parent; post_content to ezxmltext with block comments stripped and images as embeds; featured image explicitly from _thumbnail_id; categories as folders or eztags; shortcodes converted or rendered; SEO plugin fields to xrowmetadata. Passwords: WordPress formats are not read; plan resets.
3. Nine steps (5 minutes). Inventory, classes, export, convert, media first, inner links, redirects and SEO, delta, cut-over.
4. Addresses (5 minutes). Permalinks become redirecting custom aliases from WXR <link>; /?p=123 goes to the web server; feeds to an RSS export; /wp-content/uploads/... to the media objects or kept at that path; the login addresses get 410 or a redirect.

Common questions #

Our site uses a page builder plugin. Its layout lives in post meta or shortcodes: give it its own conversion, or fall back to rendered HTML (fetch the published page and take the content area). Test the most complex pages first.

How do we find the shortcodes? The guide's example: grep -o '\[[a-z_]*' over the content, then convert or render each.

Can we go the other way later? Yes: section 5 of the guide describes Exponential to WordPress with xrowextract and the WordPress Importer (lesson 8.1).

Is there an importer that reads WXR directly? The extension 7x SQLI Import does, where it is installed: its format WordPress export (WXR) reads posts and pages (with author, date, categories, tags, excerpt and featured image), or the media, categories, tags and authors, one kind per import. Import the media first, then the posts. It takes the place of the conversion script, shows a dry run first, and for the delta import before the cut-over you run it again with the newer export: items it made before are updated, not duplicated (7x SQLI Import: start here).

Pitfalls #

• Forgetting the files. WXR has attachment URLs, not files; copy the uploads directory.
• Shortcodes left in text. They show as [gallery ...] on the new site.
• Telling users about the password reset on launch day. Tell them before.

Hands-on exercise #

A planning exercise in groups of three, with the WordPress guide open. The scenario: a WordPress site with 1 200 posts, 60 pages in three levels, 4 000 attachments, categories and tags, an SEO plugin, a contact form plugin, the permalink structure /%year%/%monthnum%/%postname%/, and 25 editor accounts.

1. Write the inventory commands and checks of step 1 of section 3 of the guide, including wp post list --post_type=post --format=count.
2. Write the export command for a frozen WXR without a size limit, and what else you copy.
3. Fill in a mapping table for posts, pages, attachments, categories, tags, the SEO plugin's fields and the contact form, using section 2.
4. Write the remote id pattern for posts, pages and attachments.
5. Put the import in order: comments, pages, media, posts. Say why.
6. Write a redirect table of six rows covering the permalink structure, /?p=, a category archive, a feed, an upload and /wp-login.php, with the Exponential tool for each (section 4).
7. Write how the delta before the cut-over is exported and why it does not create duplicates.
8. Write the four risks of section 6 that apply and the counter-measure of each.

Expected result #

• Step 2: wp export --dir=<dir> --max_file_size=-1 (or Tools > Export), plus a copy of wp-content/uploads.
• Step 3: posts to articles below a blog folder, pages as a tree, attachments as image or file objects in a media folder, categories as folders or tags, tags as ezkeyword or eztags, SEO fields to xrowmetadata, the form rebuilt with information collection and its submissions archived.
• Step 5: media, pages (in parent order), posts, comments: content that relates comes after what it relates to.
• Step 6: permalinks as redirecting custom aliases generated from <link>, /?p= in the web server.
• Step 7: the WXR date filter or the REST API with modified_after; remote ids make it an update.
• The trainer checks steps 5 to 7 with each group.

Quiz #

1. What does a WXR file not contain, according to WP-CLI's documentation? A. Posts B. Comments C. The attachment files themselves D. Custom fields
2. Where does a WordPress featured image come from in the export, and why map it explicitly?
3. How is /?p=123 redirected, and why not with a URL alias?
4. Which source serves the delta import of the last days before the cut-over?
5. Can WordPress users keep their passwords?

Further reading #

• WordPress and Exponential: both directions with sources.
• Mapping content to Exponential: the building blocks.
• Exponential's import and export tools, section 4: the script skeleton the conversion feeds.

Related pages #

• Module 7: From other systems
• Migrating to Exponential: course overview
• Trainers: start here
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.