Entity Forum Importer

Entity Forum Importer migrates existing forum content into
Entity Forum, forums, topics,
replies, attachments and member avatars, landing it all as native Entity
Forum entities.

It is disposable by design: enable it, run your migration, then uninstall
it. It leaves the imported content (and its idempotency map) behind and takes
only its own settings with it.

WordPress bbPress is the implemented source today, via the
Acuity WP Migration Centre dashboard.
The importer is built multi-source, each source lives in its own include —
with Backdrop Forum, Forum NG and comments converters planned.

Why a separate module

Entity Forum ships primitives, not policy, and knows nothing about where
your old content came from. The importer keeps all of that source-specific
knowledge, WordPress table layouts, the bbPress attachments plugin, avatar
plugins, out of the forum module, so Entity Forum stays clean of any one
migration's quirks and you remove the migration code the moment it has done its
job.

It is also idempotent. Every imported record is recorded in Entity Forum's
migrate map, so a run can be repeated safely: re-running imports only what is
new or was previously missed, never a duplicate.

Key Features

• Full bbPress import: forums (order and privacy preserved), topics,
  replies, and threaded reply relationships, in one batched run.
• Attachments import into your fields, not a bespoke store. bbPress
  attachments are copied to managed files and appended to the image or file
  field you nominate on the topic type (and its replies), so imported
  attachments arrive with a widget, and members can manage them like any other
  upload. Files a private forum owns land in private://.
• Routing by allowed extensions, not mime. Each attachment goes to whichever
  of your fields accepts its extension (image field wins ties); anything neither
  field accepts is reported for action and skipped before any copy, so
  nothing is orphaned on disk. Widen the field, re-run, and only the missed
  files are copied.
• Inline images handled correctly. Images embedded in post text are copied
  local and their URLs rewritten to site-relative paths, kept distinct from
  field attachments (their URLs are part of the content and must not move).
• A persistent Missing-files report. Source files that could not be found —
  attachments and inline images alike, are collected into a durable "Missing
  files" tab (with a download-as-text link), each inline entry carrying the new
  post's URL so you can find and fix it. It survives the one-shot batch results
  page and is rebuilt on every run.
• Full author attribution. Author accounts are matched from a prior user
  migration; a member's forum posting name is seeded from their WordPress
  display name; posts whose author no longer exists are attributed as "No longer
  a member" rather than orphaned.
• Member avatars from the Basic User Avatars plugin are imported as Entity
  Forum forum pictures (never overwriting a member's own choice).
• Idempotent and re-runnable via Entity Forum's migrate map.

Requirements

• Backdrop CMS 1.x
• PHP 8.0+
• Entity Forum
• Acuity WP Migration Centre (acuity_wpmc), provides the source-database
  connection and the migration dashboard the bbPress source registers on.
• Acuity WP User Migration (acuity_wpuser), recommended for the bbPress
  source: run it first so forum posts can be matched to their imported authors.

Installation

Install this module using the official Backdrop CMS instructions at
https://docs.backdropcms.org/documentation/extend-with-modules

Enable the module, then clear your system caches. The importer dashboard appears
under the Acuity WP Migration Centre at admin/config/acuity/wpmc/bbforum.

Configuration

The importer is run from a dashboard, not left running, there is a setup order
to follow.

Before you import:

1. Install and configure Entity Forum, and point the Acuity WP Migration
   Centre at your source (WordPress) database.
2. Build your attachment fields first. Entity Forum owns no attachment
   mechanism, attachments are ordinary fields. Add an image field and/or a
   file field to the topic type and its Replies tab, then name them on the
   importer settings form. If you skip this, the attachment step reports the
   problem and skips rather than guessing.
3. Run the user migration first (acuity_wpuser), so forum posts can be
   attributed to their authors. The import form warns if it has not been run.

Settings (admin/config/acuity/wpmc/bbforum):

• Table prefix - the source WordPress prefix (wp_ by default).
• Batch size - records processed per batch step.
• Default author - the account WP-orphaned posts fall back to (0 = "No
  longer a member"; consider a dedicated "Archived member" account).
• Text format - the format imported post bodies are stored with.
• Uploads directory - the source site's uploads folder, for copying
  attachment and avatar files.
• Old base URL - the source site's address, used to recognise and rewrite
  inline image URLs.
• Image field / File field - the fields imported attachments are appended
  to (only fields present on both the topic type and its replies are offered).

The run processes, in order: forums → topics → replies → reply threading →
attachments → avatars → inline-URL rewrite → topic statistics. Spam and trash
are skipped; pending posts import as unpublished. When it finishes it reports
anything that needs your attention, skipped extensions to add, the largest file
size to allow, and any missing source files, with links to act on each.

This is a Beta release for deployment testing.

Limitations

One source forum per site. The importer migrates from one forum system;
you cannot combine two different forums into a single Entity Forum. (This is
such a fringe case it was decided against, raise an issue if you need it.)

Attachment fields must exist first. Because Entity Forum's attachments are
your own fields, the importer cannot create them for you, you build and name
them before the attachment step runs (see Configuration).

Inline images stay public. Images embedded in post text are part of the
content, so, as with Entity Forum itself, their URLs cannot be gated by forum
privacy. Only field attachments are gated.

Some source files are unrecoverable. Many "missing" inline files on a
bbPress source are the attachments plugin's temporary staging paths
(hm_bbpui/temp/…), ephemeral previews that never had permanent storage and
were already dead links in the original posts. The report distinguishes these
from real misses worth locating.

Related Modules

• Entity Forum (required) —
  the forum system this importer fills. It provides the migrate map that makes
  imports idempotent.
• Acuity WP Migration Centre (acuity_wpmc, required), WordPress source
  database connection and the migration dashboard.
• Acuity WP User Migration (acuity_wpuser, recommended), imports the
  WordPress users this importer attributes forum posts to.

Planned Features

• Split into a generic parent module plus one submodule per source, so a site
  enables only the converter it needs.
• Backdrop Forum importer (the contrib forum module)
• Forum NG importer
• Comments importer

Each planned converter includes a post-import "clean up source data" step, so
the source content can be removed cleanly once migrated.

Issues

Bugs and feature requests should be reported in the Issue Queue: https://github.com/backdrop-contrib/entity_forum_importer/issues

Current Maintainer(s)

• Steve Moorhouse (albanycomputers) (https://github.com/albanycomputers)
• Additional maintainers and contributors welcome.

Credits

• Steve Moorhouse - Zulip (DrAlbany)

• Assisted by AI.

• Current development is sponsored by Albany Computer Services, providers of computer support, web design, and web hosting.

License

This project is GPL v2 or later software. See the LICENSE.txt file in this directory for complete text.