Migration Guide — WordPress → Association App Platform

Who this is for: Associations currently running their site on WordPress with the 2DC Association App WordPress Plugin installed, and migrating to the new Association App Platform (Spring Boot backend + React Admin Dashboard + updated mobile app).

What Is Changing

Component	Before (WordPress)	After (New Platform)
Backend / API	WordPress REST API (`/api/v1/`)	Spring Boot API (new URLs)
Admin interface	WordPress Admin (`/wp-admin`)	Association Dashboard (web app)
Database	WordPress MySQL	PostgreSQL
Authentication	Custom JWT + Firebase	JWT with 1-hour access tokens + 30-day refresh
File storage	WordPress Media Library	Cloud storage (GCS / S3 / Local)
Multi-tenancy	Single site per WordPress install	Multiple organisations on one platform
Member directory	WordPress user list	Organisation Members page
Events	`event` custom post type	Events module
Documents	`document`, `policy`, `recall` post types	Documents module
Push notifications	Firebase connected via plugin	Firebase connected via platform settings

What stays the same

All your existing members, events, documents, conferences, companies, articles, and notifications are migrated
Member profiles are preserved (name, email, phone, job title, address, certifications)
The mobile app continues working during the migration window — it switches APIs after the cutover update is published
Document folders (taxonomy) are recreated automatically
Sync is idempotent — running it more than once does not create duplicates

What does not migrate

Member passwords — WordPress password hashes cannot be used in the new platform; members set a new password via email
WordPress page content (standard pages, blog comments, widget configurations) — only association-specific content types are migrated
WordPress user roles beyond membership status — roles are mapped to membership status (see Member mapping)
Plugin-specific shortcodes and blocks embedded in pages

Migration Phases

Phase 1  ──▶  Prepare WordPress (update plugin, get sync key, backup)
Phase 2  ──▶  Set up your new platform account
Phase 3  ──▶  Connect WordPress to the platform (Connector wizard)
Phase 4  ──▶  Run the Initial Import (full data migration)
Phase 5  ──▶  Verify your data
Phase 6  ──▶  Migrate member accounts (send password reset emails)
Phase 7  ──▶  Coordinate mobile app update with 2DC
Phase 8  ──▶  Cutover (go live)
Phase 9  ──▶  Post-migration cleanup

Each phase is reversible until Phase 8. You can safely pause between any two phases. The WordPress site continues operating normally throughout.

Estimated total time: 2–4 hours of active work, spread over 1–2 weeks.

Phase 1 — Prepare WordPress

1.1 Update the Plugin

Confirm you are running plugin version 1.2.0 or later.

Go to WordPress Admin → Plugins → Installed Plugins
Find 2DC Association App and check the version number
Click Update Now if an update is available
Confirm the plugin is active (not deactivated)

1.2 Configure Permalinks

The sync API uses pretty permalinks. If your WordPress site does not use them:

Go to WordPress Admin → Settings → Permalinks
Select Post name
Click Save Changes

1.3 Get the Sync API Key

Go to WordPress Admin → Settings → Association App
Open the Sync tab
Copy the Sync API Key — store it somewhere safe (you will paste it in Phase 3)
If no key exists, click Generate Key and Save Settings

1.4 Verify Sync Endpoints Respond

Open each URL in a browser (replace your-site.com). A 401 response is correct — it means the endpoint exists and is protected by the key:

GET https://your-site.com/api/v1/sync/ping
GET https://your-site.com/api/v1/sync/members
GET https://your-site.com/api/v1/sync/events
GET https://your-site.com/api/v1/sync/articles
GET https://your-site.com/api/v1/sync/documents
GET https://your-site.com/api/v1/sync/conferences
GET https://your-site.com/api/v1/sync/companies
GET https://your-site.com/api/v1/sync/notifications

If you receive a 404, the plugin is not registering its routes. Fix: Settings → Permalinks → Save Changes.

1.5 Take a Full Backup

Do not skip this step

A backup is your only rollback safety net. Export both the database and all uploaded files. Download the backup to your local machine — not just to the server.

Recommended tools:

UpdraftPlus (free version is fine)
Your hosting control panel (cPanel, Plesk, Kinsta backup, WP Engine backup)
mysqldump on the command line for the database

Phase 2 — Set Up the New Platform Account

Open the Association Dashboard URL provided by your 2DC account manager
Log in with the temporary credentials and set a permanent password
Go to Organisation → Settings → General and confirm your organisation name and slug
Go to Organisation → Branding and upload your logo, set your colours, and upload a favicon
Go to Organisation → Settings → Mail Settings and configure your email (SMTP or leave as platform default for now)

Phase 3 — Create the WordPress Connector

The Connector is the bridge between your WordPress site and the new platform. Creating it does not start any sync — it just saves the configuration.

In the dashboard sidebar, click Connectors
On the Integration Hub page, find WordPress and click Connect
Complete the 5-step wizard:

Step 1 — Basic Info

Field	Value
Connector Name	e.g. `My Association WordPress` (any descriptive name)

Step 2 — Authentication

Field	Value
WordPress Site URL	`https://your-wordpress-site.com.au` (exact URL, no trailing slash)
Sync API Key	The key from Phase 1.3

Click Test Connection — all 5 diagnostic checks must pass before continuing.

Step 3 — Sync Settings

Enable the entity types you want to migrate. Recommended: enable all:

Articles (WordPress posts / news)
Members (WordPress users)
Events
Documents (includes Policies and Recalls)
Conferences
Companies
Notifications

Set Sync Interval: 60 minutes (for ongoing sync after migration).

Enable Copy Images and Copy Document Files so that files are stored in platform storage and remain accessible if WordPress is later decommissioned.

Step 4 — Field Mapping

The default field mappings work for the standard plugin setup. Only change these if your WordPress site uses custom meta keys different from the plugin defaults.

Review the mappings (see Data Mapping Reference below for full details) and click Next.

Step 5 — Review & Connect

Confirm the settings and click Connect. The connector is created.

Phase 4 — Run the Initial Import

The Initial Import is a one-time bulk operation that imports all your existing WordPress data.

This can only be run once

After the Initial Import completes, the button is permanently disabled. Subsequent syncs use Full Sync or Incremental.

Go to Connectors → [your WordPress connector]
Click Run Initial Import
Confirm in the dialog

The import processes entities in this order:

Articles (WordPress posts)
Members (WordPress users)
Events
Conferences
Companies
Documents
Notifications

Watch the Live Sync Panel — it updates every 2 seconds with the current phase, records processed, and any errors.

What to expect

Data type	Import behaviour
Articles	Imported as news articles. Status mirrors WordPress (`publish` → `PUBLISHED`, `draft` → `DRAFT`). Original WordPress publish date is preserved in `sourceCreatedAt`. HTML content is parsed into structured content blocks.
Members	Imported with all profile fields. Status mapped from WordPress role (see mapping table). Passwords are NOT migrated.
Events	Imported with full location and date details. Start/end timestamps converted from WordPress Unix milliseconds to ISO-8601 UTC.
Conferences	Imported as events with type `CONFERENCE`. Same fields as events.
Documents	Metadata imported (title, folder, file URL). If Copy Document Files is enabled, the actual files are downloaded to platform storage. Otherwise only the URL is recorded.
Companies	Imported with description, contact details, and logo (if image mirroring enabled).
Notifications	Imported with type and link data.

The import is idempotent — if you re-run it (via Full Sync), records are matched by their WordPress ID (externalId) and updated rather than duplicated.

Phase 5 — Verify Your Data

Before cutting over, verify that data has migrated correctly. Work through this checklist:

Members

Total member count matches your WordPress user count (check WordPress Admin → Users → All Users count)
Spot-check 5–10 members: open each in the platform and verify name, email, phone, membership status
Members with association-member role show as ACTIVE
Members with pending-review role show as PENDING

Events

Upcoming events appear with correct title, dates, and location
Past events are present and correctly marked
Virtual events have isVirtual: true
Event date/times are in the correct timezone (see Timezone note)

Articles

Article count matches WordPress post count
Published articles show as PUBLISHED
Featured images load correctly (if image mirroring was enabled)
Article content displays without broken layout

Documents

All folders were created (matching your WordPress taxonomy)
Documents are inside the correct folders
Download a document to confirm the file is accessible

Sync errors

Go to Connectors → [connector] → Sync Jobs → [import job] → Logs
Review all FAILED entries and resolve each one before proceeding

Timezone note

WordPress stores event start/end times as Unix milliseconds in post meta, in the local timezone of the WordPress server. The platform converts these to UTC using the WordPress Timezone setting in the connector. If events appear offset by several hours, update the timezone setting in the connector (e.g. +10:00 for AEST) and re-run a Full Sync.

Phase 6 — Migrate Member Accounts

Members are imported but cannot log in until they set a new password. This is by design — WordPress password hashes are not compatible with the new platform.

Send password reset emails

Go to Organisation → Members
Click Actions → Send Password Reset to All
Confirm — each member receives an email with a secure link to set their new password

Best practice: Send to a small group first (your committee or board) to verify the email flow and the member experience before sending to all members.

Member communication

Send members a notice before cutover explaining:

The association is upgrading its platform
They will receive an email to set a new password — they must do this to continue using the app
Their membership, events, documents, and history are all preserved
Include the cutover date and what to do if they need help

Phase 7 — Mobile App Update

Contact your 2DC account manager to request the app configuration update. Provide:

Your new platform API URL
Your Organisation Slug (shown in Organisation → Settings → General)
Confirmation that the Initial Import is complete and data is verified
Your target cutover date

The 2DC team will prepare and submit a new app version. After App Store / Google Play review (typically 1–3 days), the update is available for members to install.

API endpoint changes (for technical reference)

The mobile app communicates with a new set of API endpoints after the update:

Feature	Old WordPress endpoint	New platform endpoint
Login	`POST /api/v1/auth`	`POST /api/auth/org/login`
Register	`POST /api/v1/auth/signup`	`POST /api/auth/org/register`
Refresh token	`POST /api/v1/auth/refresh`	`POST /api/auth/refresh`
User profile	`GET /api/v1/user`	`GET /api/orgs/{orgId}/users/{userId}`
Events list	`GET /api/v1/events`	`GET /api/orgs/{orgId}/events`
Documents	`GET /api/v1/documents`	`GET /api/orgs/{orgId}/documents`
Members	`GET /api/v1/members`	`GET /api/orgs/{orgId}/users`
Articles/News	`GET /api/v1/posts`	`GET /api/orgs/{orgId}/news`
Notifications	`GET /api/v1/notifications`	`GET /api/notifications`

Phase 8 — Cutover (Go Live)

Pre-cutover checklist

Initial Import completed with no unresolved errors
All data verified (members, events, documents, articles)
At least 5 members (including you) have logged in with their new passwords
Mobile app update is published and you have tested it on both iOS and Android
Firebase push notifications are configured and tested
Email configuration is verified (send a test email from platform settings)
Member communication sent
Maintenance window communicated to members

Recommended maintenance window: Weekend night, 10 PM – 2 AM local time.
Expected member downtime: 15–30 minutes (time to install the app update).

Cutover steps

Run a final incremental sync — Connectors → Run Incremental Sync. This catches any last-minute WordPress changes.
Enable Read-Only Mode in WordPress — WordPress Admin → Settings → Association App → Sync → toggle Read-Only Mode ON. This prevents content edits in WordPress from being overwritten after cutover.
Publish the mobile app update — Confirm with 2DC that the app update is live on App Store and Google Play.
Notify members — Send the "We are now live!" message with instructions to update the app and set their new password if they haven't already.
Monitor — Watch the platform dashboard for login activity and member support queries.

Phase 9 — Post-Migration Cleanup

Week 1

Monitor Audit Logs daily (Platform → Audit Logs)
Watch for member support queries — most will be password-reset related
Leave the WordPress connector active with auto-sync running in case content updates are still being made in WordPress

After 30 days

If your team has moved fully to managing content in the new platform, disable the WordPress sync endpoints — WordPress Admin → Settings → Association App → REST API → Disable
Optionally pause or delete the connector if WordPress sync is no longer needed

Ongoing (optional)

If your team prefers to continue managing some content in WordPress (e.g. articles/news), leave the connector enabled with auto-sync. Changes in WordPress will sync automatically at your configured interval.

Data Mapping Reference

Member field mapping

WordPress source	WordPress meta key	Platform field	Notes
User email	`user_email`	`email`
User meta	`first_name`	`firstName`
User meta	`last_name`	`lastName`
User field	`display_name`	`displayName`
User meta	`mobile_number`	`phoneNumber`
User meta	`job_title`	`jobTitle`
User meta	`company_organization`	`company`
User meta	`birthday`	`dateOfBirth`
User meta	`street_address`	`addressLine1`
User meta	`city`	`city`
User meta	`zip`	`postalCode`
User meta	`is_certified`	`isCertified`	Boolean
User meta	`renewal_date`	`membershipRenewalDate`
User meta	`is_exclude_listing`	`isExcludedFromListing`	Boolean
User field	`user_registered`	`createdAt`

WordPress role → membership status:

WordPress role(s)	Platform membership status
`association-member`	`ACTIVE`
`pending-review`	`PENDING`
`administrator`	`ADMIN`
Any other role	`INACTIVE`

Article / News field mapping

WordPress source	Platform field	Notes
`post_title`	`title`
`post_content`	`content`	HTML parsed into content blocks
`post_excerpt`	`summary`	Falls back to first 30 words of content if empty
`post_name`	`slug`	URL slug
`post_status`	`status`	`publish` → `PUBLISHED`, otherwise `DRAFT`
Featured image	`featuredImageUrl`	Full-size image URL
`display_name` (author)	`authorName`
`user_email` (author)	`authorEmail`
Category names	`category`	First category name is used
Tag names	`tags`	All tags as an array
`post_date_gmt`	`sourceCreatedAt`	Original WordPress publish date preserved
`post_modified_gmt`	`sourceUpdatedAt`

Event field mapping

WordPress meta key	Platform field	Notes
`post_title`	`title`
`post_content`	`description`
`post_excerpt`	`excerpt`
`_event_date_time_start`	`startDate`	Unix ms → ISO-8601 UTC
`_event_date_time_end`	`endDate`	Unix ms → ISO-8601 UTC
`_event_all_day`	`isAllDay`	Boolean
`_event_is_virtual`	`isVirtual`	Boolean
`_event_cost`	`cost`
`_event_url`	`registrationUrl`
`_location_address`	`location.address`
`_location_city`	`location.city`
`_location_state`	`location.state`
`_location_zip_code`	`location.postalCode`
Featured image	`featuredImageUrl`
`_event_attending_count`	`attendingCount`
`post_date_gmt`	`createdAt`
`post_modified_gmt`	`updatedAt`

Event status mapping:

WordPress `post_status`	Platform status
`publish`	`PUBLISHED`
`draft`	`DRAFT`
`private`	`DRAFT` (review required)
`trash`	Not imported

Conference field mapping

Same as events, with eventType: 'CONFERENCE' set automatically. Conference-specific meta keys:

WordPress meta key	Platform field
`_conference_date_time_start`	`startDate`
`_conference_date_time_end`	`endDate`
`_conference_all_day`	`isAllDay`
`_conference_is_virtual`	`isVirtual`
`_conference_url`	`registrationUrl`
`_conference_cost`	`cost`
`_location_*`	`location.*`

Document field mapping

Covers three WordPress post types: document, policy, recall

WordPress source	Platform field	Notes
`post_title`	`title`
`_document_file` (or `_policy_file`, `_recall_file`)	`fileUrl`	File attachment URL
File extension	`mimeType`	Detected automatically from URL
Taxonomy term (`document_folder`, `policy_folder`, `recall_folder`)	`folder`	Folder name and hierarchy
`post_status`	`status`	`publish` → `PUBLISHED`
`post_date_gmt`	`uploadedAt`
`post_modified_gmt`	`updatedAt`

Document folder mapping:
WordPress document folder taxonomy terms are mapped directly to platform document folders. Folders are created automatically if they don't exist. Documents with no taxonomy are placed in a root folder named after the post type (Document / Policy / Recall).

Company field mapping

WordPress source	Platform field
`post_title`	`companyName`
`post_content`	`description`
`_company_url`	`website`
`_company_phone`	`contactPhone`
`_company_email`	`contactEmail`
Featured image	`logoUrl`
`post_status`	`status`

Notification field mapping

WordPress source	Platform field	Notes
`post_title`	`title`	HTML entities decoded
`post_excerpt`	`content`	HTML entities decoded
`post_date`	`date`	Formatted as `Mon, Jan 1, 2024`
`_notification_type`	`type`
Link meta	`link`	Depends on notification type (see below)

Notification link types:

WordPress `_notification_type`	Platform link structure
`post-type`	`{type, id, slug}` from linked post
`external-link`	`{type: 'external-link', url: '...'}`
`website-page`	`{type, slug}`
`notification`	`null` (no link)

Rollback Plan

If you need to roll back after completing Phase 8:

Disable Read-Only Mode — WordPress Admin → Settings → Association App → Sync → Read-Only Mode OFF
Re-enable the REST API if it was disabled
Contact 2DC to roll back the mobile app to point to the WordPress API
Notify members of the temporary rollback and expected timeline for the next cutover attempt

Your database backup from Phase 1 is the ultimate safety net for the WordPress side. The new platform data is not affected by a rollback.

Troubleshooting

Problem	Solution
Test Connection fails (step 1)	Check HTTPS, no trailing slash on URL, site is publicly accessible
Test Connection fails (step 4 — key invalid)	Re-copy key from WordPress Admin → Settings → Association App; regenerate if needed
Sync endpoint returns 404	Plugin not active, or permalinks not flushed — Settings → Permalinks → Save Changes
Members imported as INACTIVE unexpectedly	Check WordPress user roles — only `association-member` maps to ACTIVE
Duplicate email error during member sync	Find and merge the duplicate in Organisation → Members
Documents imported but files 404	Enable "Copy Document Files" in connector settings and re-run sync
Events missing	Confirm they are `publish` or `draft` in WordPress (not `trash`)
Event dates wrong	Set correct WordPress Timezone in connector settings and re-run Full Sync
Articles have broken image URLs	Enable image mirroring in connector and re-run sync
Sync stuck in RUNNING for 1+ hour	Open the sync job and click Force Stop; check Diagnostic Panel; re-trigger
Member cannot log in after migration	Send password reset from Members page; verify email config in Settings
Push notifications not working	Verify Firebase Server Key (not Web API Key) in Platform → Settings
Sync API key error 503	Key not generated in WordPress — go to Settings → Association App → Generate Key

For the full troubleshooting guide, see Connector Troubleshooting.

Support

Channel	Use for	Response time
In-app chat (dashboard)	Quick questions, connector issues	< 4 hours (business hours)
[email protected]	Non-urgent issues, data questions	< 1 business day
Phone (account manager)	Migration day support, critical issues	Immediate (scheduled)

To book live migration support, contact your account manager at least 3 business days before your planned cutover date.

What Is Changing​

What stays the same​

What does not migrate​

Migration Phases​

Phase 1 — Prepare WordPress​

1.1 Update the Plugin​

1.2 Configure Permalinks​

1.3 Get the Sync API Key​

1.4 Verify Sync Endpoints Respond​

1.5 Take a Full Backup​

Phase 2 — Set Up the New Platform Account​

Phase 3 — Create the WordPress Connector​

Phase 4 — Run the Initial Import​

What to expect​

Phase 5 — Verify Your Data​

Members​

Events​

Articles​

Documents​

Sync errors​

Timezone note​

Phase 6 — Migrate Member Accounts​

Send password reset emails​

Member communication​

Phase 7 — Mobile App Update​

API endpoint changes (for technical reference)​

Phase 8 — Cutover (Go Live)​

Cutover steps​

Phase 9 — Post-Migration Cleanup​

Week 1​

After 30 days​

Ongoing (optional)​

Data Mapping Reference​

Member field mapping​

Article / News field mapping​

Event field mapping​

Conference field mapping​

Document field mapping​

Company field mapping​

Notification field mapping​

Rollback Plan​

Troubleshooting​

Support​