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.

The importer is a generic parent plus one submodule per source. The parent
(entity_forum_importer) owns only the shared migrate map; each source is its
own submodule. WordPress bbPress (entity_forum_importer_wpbb) is the
implemented source today, appearing as a card in the Acuity Migration Centre
under WordPress. Backdrop Forum, Forum NG and comments converters are
planned as further submodules.

Only the WordPress source submodule depends on the Acuity Migration Centre and
the WordPress connection hub; the parent does not. A site enables just the
converter it needs, and the planned Backdrop converters read Backdrop's own
database and won't require any WordPress module.

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 an image or file field
  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://.
• Automatic field routing by allowed extensions, not mime, and zero config.
  The importer discovers every image/file field on the topic type and its replies
  and sends each attachment to the most specific field that accepts its
  extension (a pdf-only Documents field beats a catch-all Files field; images
  keep an image field for their styles). Nothing needs naming. Anything no field
  accepts is reported for action and skipped before any copy, so nothing is
  orphaned on disk. Add a field for the extension, re-run, and only the missed
  files are copied.
• Asset scan & prune (the Assets tab). Before importing, scan the source for
  every file the forum actually references (attachments, inline images, avatars)
  and write a downloadable manifest with a planning report — which extensions
  appear on topics vs replies, each mapped to the field that would receive it, so
  you can build fields and set upload limits before the first import. Optionally
  copy just the referenced files into a pruned folder, so a large migration
  uploads ~1,000 files instead of tens of thousands.
• 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 Migration Centre (acuity_migration), the dashboard framework the
  bbPress source registers on (a dependency of the WordPress source submodule).
• Acuity WP Migration Centre (acuity_wpmc), the WordPress source-database
  connection (a dependency of the WordPress source submodule).
• 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 appears as a card
in the Acuity Migration Centre's WordPress section at
admin/config/acuity-migration/wordpress/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 WordPress Migration
   Centre (under Acuity Migration Centre → WordPress) at your source 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. You do not name them
   anywhere: routing is automatic, by each field's allowed extensions. Run the
   Assets tab's scan first to see exactly which extensions your source uses
   on topics vs replies, so you can build fields that cover them. A file whose
   extension no field accepts is reported and skipped, never guessed.
3. Run the user migration first (acuity_wpuser), so forum posts can be
   attributed to their authors. The Overview warns if it has not been run.

Settings (admin/config/acuity-migration/wordpress/bbforum/settings):

• 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.
• Three directories, each one job (all absolute filesystem paths):
  
  • Source for pruning - the full source uploads tree the Assets tab prunes
    from.
  • Prune destination - where the Assets tab writes the trimmed file set.
  • Import source - where the attachment, inline-image and avatar steps read
    files from during the import (typically the prune destination once pruned,
    or wherever you uploaded it on the destination server). Leave empty to skip
    the file steps.
• Old base URL - the source site's address, used to recognise and rewrite
  inline image URLs.

There is no image-field/file-field setting: attachment routing is automatic (see
Key Features).

The Assets tab (optional but recommended for large sites): Scan reads the
source database for every referenced file and writes a downloadable JSON manifest
plus a planning report (extensions per topic/reply → the field that would receive
each, unrouted ones flagged, largest-file estimate). Copy pruned set then
copies just those files from Source for pruning into Prune destination,
preserving the Y/m structure — so you upload only the referenced files. The
copy is incremental (files already present with a matching size are skipped) and
reports the exact total and largest file from disk.

The run (the Overview tab's Run button) 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 a field for, 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 them before
the attachment step runs (routing into them is then automatic; see
Configuration). The Assets scan tells you which extensions to cover.

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.

⚠️ Disable file rename/relocate modules before importing

The importer places each private forum's files directly in the
private file system and gives every file a unique name. A module that
rewrites file paths or names on save (for example
File (Field) Paths) will
break this two ways: it can push private files into the public path —
leaking them to anyone with the URL — and it can rename two files onto
the same path, which aborts the attachment save so the file never lands on
the post. Turn any such module off on Entity Forum's file and image
fields before you import. See Entity Forum's own README for the full
rationale.

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 Migration Centre (acuity_migration, required by the WordPress
  source submodule), the dashboard framework.
• Acuity WP Migration Centre (acuity_wpmc, required by the WordPress source
  submodule), WordPress source database connection.
• Acuity WP User Migration (acuity_wpuser, recommended), imports the
  WordPress users this importer attributes forum posts to.

Planned Features

The generic parent + per-source submodule split is done (the WordPress
bbPress source is the first submodule). Planned further source submodules:

• 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.