Export / Import Configuration

Migrate complete plugin configuration between servers using JSON export/import, ideal for dev → staging → production workflows or disaster recovery.

Overview

The Export/Import page provides a safe, portable way to migrate all plugin configuration to a new server without manual re-entry. With one click:

Export all settings, credentials, connections, environments to JSON file
Import on new server in seconds
Choose merge or replace strategy
Maintain configuration consistency across environments

Access: GSM Middleware → Tools → Export/Import

Permission Required: manage_gsm_middleware

Use Cases:

Server migration (moving from old hosting to new infrastructure)
Environment promotion (dev → staging → production)
Disaster recovery (restore from backup)
Multi-site setup (configure one, replicate to many)
Developer onboarding (clone production config to local dev)

What Gets Exported

Complete Configuration Package

Export includes:

Category	What's Included	Example Data
Plugin Settings	General, Business Central OData, Order Sync settings	BC API URL, timeout values, sync toggles
API Connections	SOAP, OData, OAuth configurations with credentials	All connection configs from API Connections page
Merchant Accounts	MID → NMI key mappings with API keys	PayArc MID linked to NMI security key
Database Environments	Tasks DB connection configs with passwords	Dev, staging, prod database credentials

Metadata Included

Export file starts with:

{
  "metadata": {
    "plugin_version": "1.10.0",
    "export_date": "2024-12-15 10:30:45",
    "site_url": "https://old-server.com"
  },
  "settings": { ... },
  "api_connections": [ ... ],
  "merchant_accounts": [ ... ],
  "db_environments": [ ... ]
}

Metadata uses:

Version check: Warn if importing from older/newer plugin version
Audit trail: Know when/where export came from
Documentation: Remind you which environment config came from

Export Process

Step-by-Step

1. Navigate to Export Page:

GSM Middleware → Tools → Export/Import
Click left panel: "Export Configuration"

2. Review What Will Be Exported:

Plugin Settings (General, BC OData, Order Sync)
API Connections (SOAP, OData, OAuth with credentials)
Merchant Accounts (MID → NMI key mappings)
Database Environments (Tasks DB connection configs)

3. Read Security Warning:

⚠️ Security Warning: The export file contains all credentials in plaintext. Store it securely and delete it after import on the new server.

4. Click "Export Configuration" Button:

Button shows: 🔽 Export Configuration
While exporting: "Exporting..." (disabled)

5. Download JSON File:

File downloads automatically via browser
Filename format: gsm-middleware-config-oldserver-2024-12-15-103045.json
Location: Browser's default download folder

6. Success Message:

✅ Success! Exported 5 API connection(s), 8 merchant account(s), and 3 database environment(s).

Export File Structure

Example (simplified):

{
  "metadata": {
    "plugin_version": "1.10.0",
    "export_date": "2024-12-15 10:30:45",
    "site_url": "https://old-server.com"
  },
  "settings": {
    "bc_odata_url": "https://bc.example.com/odata",
    "bc_timeout": 30,
    "order_sync_enabled": true
  },
  "api_connections": [
    {
      "id": 1,
      "name": "BC Production SOAP",
      "type": "soap",
      "url": "https://bc.example.com/soap",
      "username": "admin",
      "password": "decrypted_password_here",
      "is_active": true
    }
  ],
  "merchant_accounts": [
    {
      "mid": "MID12345",
      "nmi_security_key": "decrypted_key_here",
      "description": "PayArc Main Account"
    }
  ],
  "db_environments": [
    {
      "id": 1,
      "name": "Production",
      "host": "db.example.com",
      "database": "gsm_tasks",
      "username": "db_user",
      "password": "decrypted_password_here",
      "is_active": true
    }
  ]
}

Key points:

✅ All passwords/keys decrypted (plaintext in export)
✅ IDs preserved (important for foreign key relationships)
✅ Human-readable formatting (JSON_PRETTY_PRINT)
✅ Complete - no manual adjustments needed

Import Process

Step-by-Step

1. Navigate to Import Page:

GSM Middleware → Tools → Export/Import
Click right panel: "Import Configuration"

2. Choose Import Strategy:

Merge (default):

Update existing records (by ID)
Add new records
Keep records not in import file
Best for: Incremental updates, adding new connections

Replace:

Delete ALL existing configuration
Import everything from file
Best for: Clean slate setup, exact replica

3. Select Configuration File:

Click "Choose File" button
Select exported .json file
Import button enables when file selected

4. Click "Import Configuration" Button:

Confirms: "Are you sure you want to import this configuration? This will update your current settings."
Click "OK" to proceed
Button shows: "Importing..." (disabled)

5. Review Results:

Success:

✅ Success! Imported 5 API connection(s), 8 merchant account(s), and 3 database environment(s).

Error:

❌ Error: Invalid JSON file. Missing required field 'metadata'.

Import Strategies Explained

Merge Strategy (Recommended)

How it works:

Reads each record from import file
If record ID exists in database → Update with imported values
If record ID doesn't exist → Insert as new record
Records in database but not in import file → Keep unchanged

Example:

Before import (database):

API Connection #1: BC SOAP (old credentials)
API Connection #2: BC OData (not in import file)

Import file contains:

API Connection #1: BC SOAP (new credentials)
API Connection #3: BC OAuth (new)

After merge import:

API Connection #1: BC SOAP (updated credentials)
API Connection #2: BC OData (kept unchanged)
API Connection #3: BC OAuth (added new)

Best for:

Adding new integrations to existing setup
Updating credentials without losing other configs
Incremental configuration changes
Safe imports (doesn't delete anything)

Replace Strategy (Destructive)

How it works:

Deletes ALL existing settings/connections/accounts/environments
Imports everything from file
Result: Database exactly matches import file

Example:

Before import (database):

API Connection #1: BC SOAP
API Connection #2: BC OData
Merchant Account: MID12345

Import file contains:

API Connection #1: BC SOAP (different credentials)
API Connection #3: BC OAuth

After replace import:

API Connection #1: BC SOAP (from import file)
API Connection #2: BC OData (deleted)
API Connection #3: BC OAuth (added)
Merchant Account: MID12345 (deleted)

Best for:

Clean server setup (new production box)
Exact replication (dev → staging)
Removing old/unused configs automatically
"Nuclear option" when merge causes issues

Common Workflows

Workflow 1: Dev → Production Migration

Goal: Move fully tested configuration from development to production server

Steps:

On Dev Server:

Test all integrations thoroughly
Navigate to Export/Import page
Click "Export Configuration"
Download gsm-middleware-config-dev-2024-12-15.json
Store file on secure USB or encrypted cloud storage

On Production Server:

Install GSM Middleware plugin (if not already)
Navigate to Export/Import page
Select import strategy: Replace (for clean slate)
Choose downloaded JSON file
Click "Import Configuration" → Confirm
Wait for success message
Verify: Check API Connections page, test one connection
Verify: Check Site Management, ensure sites appear
Verify: Run Test Order from Testing page
Delete import file from downloads folder (security)

Time savings: 5 minutes vs. 2-3 hours of manual re-entry

Workflow 2: Credential Rotation Across Environments

Goal: Update NMI API keys on all environments after security audit

Steps:

Preparation:

Generate new NMI API keys for all MIDs
Export config from production:
- Navigate to Export/Import
- Click "Export Configuration"
- Save prod-config-before-rotation.json (backup)

Update Production:

Navigate to Merchant Accounts page
Update all NMI keys with new values
Test one payment to verify new keys work
Export updated config: prod-config-after-rotation.json

Apply to Staging:

On staging server, navigate to Export/Import
Select Merge strategy (keep other diffs between environments)
Import prod-config-after-rotation.json
Verify: Check Merchant Accounts page, keys updated
Test payment

Apply to Dev:

Repeat staging process on dev server
Test payment

Result: All 3 environments updated in 15 minutes vs. 2+ hours manual

Workflow 3: Disaster Recovery

Goal: Restore configuration after server crash

Prerequisite: Regular exports saved to off-server backup

Steps:

Setup New Server:

Provision new WordPress installation
Install GSM Middleware plugin
Activate plugin

Restore Configuration:

Download most recent export from backup:
- prod-config-2024-12-14-daily-backup.json (yesterday's export)
Navigate to Export/Import page
Select Replace strategy (empty database)
Import backup file
Success message confirms all data restored

Verify Restoration:

Check API Connections → Test each connection
Check DB Environments → Verify active environment
Check Merchant Accounts → Confirm all MIDs present
Run manual sync from Testing page
Check Orders page for recent orders

Downtime: < 30 minutes from zero to fully operational

Workflow 4: Developer Onboarding

Goal: Set up local dev environment matching production

Steps:

Export from Production (by admin):

Navigate to Export/Import page
Click "Export Configuration"
Save to shared secure location (not public repo!)
Share with developer via encrypted email or internal system

Import to Developer's Local:

Developer installs WordPress + GSM Middleware locally
Downloads shared config file
Navigate to Export/Import page
Select Replace strategy (empty local database)
Import production config
Adjust DB Environment:
- Navigate to DB Environments page
- Add "Local Dev" environment pointing to local MySQL
- Set as active
Test connection to local tasks database

Result: Developer has identical config in minutes, ready to start work

Security Considerations

⚠️ Critical Security Warnings

1. Export Files Contain Plaintext Credentials

The exported JSON file includes:

Database passwords
API keys and tokens
OAuth secrets
NMI security keys

Never:

❌ Commit export files to Git repositories (even private ones)
❌ Email export files unencrypted
❌ Store in shared Dropbox/Google Drive without encryption
❌ Leave in browser downloads folder long-term
❌ Include in public documentation or screenshots

Always:

✅ Delete export file immediately after successful import
✅ Use encrypted storage if keeping backups (1Password, LastPass, encrypted USB)
✅ Transfer via HTTPS only (never HTTP, FTP, or unencrypted protocols)
✅ Use company VPN when transferring between servers
✅ Set file permissions chmod 600 if storing on Linux server temporarily

2. Production Exports Should Be Restricted

Access control:

Only grant manage_gsm_middleware capability to trusted administrators
Use separate WordPress admin accounts for dev vs. production access
Enable audit logging to track who exports configuration

Backup strategy:

Automate daily exports via WP-CLI cron job (store encrypted off-server)
Rotate backups: Keep 7 daily, 4 weekly, 12 monthly
Test restore process quarterly to ensure backups valid

3. Verify Import Source

Before importing:

Check file source: Ensure it came from trusted colleague/system
Scan for tampering: Compare file size, check JSON structure
Test on staging first: Never import untested file directly to production
Backup before import: Export current production config before importing new one

Best Practices

Export:

Export regularly — Automate weekly exports as backup (WP-CLI cron)
Label clearly — Use descriptive filenames: prod-config-2024-12-15-before-migration.json
Encrypt backups — Use GPG or 7-Zip with strong password for long-term storage
Document changes — Note what changed in export (e.g., "Updated NMI keys for MID12345")
Version control exports — Keep last 3 exports for rollback capability

Import:

Export current config first — Always backup before import (rollback safety)
Use staging — Test import on staging environment before production
Choose strategy carefully — Merge for updates, Replace for clean setup
Verify immediately — Test connections and run sync after import
Delete file after success — Remove import file from server/downloads

Automation:

WP-CLI exports — Schedule via cron:

wp gsm export-config --path=/var/www/html > /backups/gsm-config-$(date +%Y%m%d).json

Rotate backups — Delete files older than 90 days
Off-server storage — Rsync to separate backup server
Encrypt in transit — Use scp or rsync over SSH

Troubleshooting

"Invalid JSON file" Error

Cause: File corrupted, wrong format, or not a valid GSM export

Solution:

Open file in text editor (Visual Studio Code, Sublime)
Verify starts with { "metadata": ... and ends with }
Check for syntax errors (missing commas, quotes)
Validate JSON with online tool: https://jsonlint.com/
If corrupted, re-export from source server
If from email, ensure not auto-converted to .txt (should be .json)

"Missing required field 'metadata'" Error

Cause: File is not a GSM Middleware export (wrong format)

Solution:

Confirm file was exported from GSM Middleware plugin (not manual JSON)
Check metadata object exists and contains plugin_version, export_date, site_url

If someone manually created JSON, add metadata section:

{
  "metadata": {
    "plugin_version": "1.10.0",
    "export_date": "2024-12-15 10:30:45",
    "site_url": "https://old-server.com"
  },
  ...
}

Import Succeeds But API Connections Don't Work

Cause: Imported credentials/URLs differ from new environment

Solution:

Verify URLs: If importing from production to dev, URLs may be different:
- Production BC: https://bc.company.com
- Dev BC: https://bc-dev.company.com
- Fix: Navigate to API Connections, update URLs for dev environment
Check credentials: Some credentials are environment-specific:
- OAuth tokens tied to specific domain
- Fix: Regenerate OAuth credentials for new environment
Test individually: Go to API Connections page, test each connection
Review error messages: debug.log shows API connection errors

"You do not have permission" Error

Cause: User lacks manage_gsm_middleware capability

Solution:

Or grant capability to user:

$user = get_user_by( 'login', 'username' );
$user->add_cap( 'manage_gsm_middleware' );

Or use WP-CLI as admin:

wp user add-cap username manage_gsm_middleware

Replace Import Deleted Needed Config

Cause: Used "Replace" strategy, deleted config not in import file

Solution:

Immediate recovery: If just happened, restore from backup:
- Navigate to Export/Import
- Import backup file exported before this import (should have created one!)
No backup: Manually re-configure deleted items:
- Check what's missing (API Connections, Merchant Accounts, etc.)
- Re-enter from documentation or source systems
Prevention: Always export current config before any import:
- Click "Export Configuration" first
- Save as before-import-backup-[date].json
- Then proceed with import

File Upload Fails (Large File)

Cause: PHP upload size limit exceeded (rare, but possible with 100+ connections)

Solution:

Check file size: Typical export is 10-50 KB, should never exceed 1 MB
If large, check for data anomalies (repeated text, large credential strings)

Increase PHP limits in php.ini or wp-config.php:

@ini_set( 'upload_max_filesize', '10M' );
@ini_set( 'post_max_size', '10M' );

Or split config manually:
- Export once
- Edit JSON to remove half the connections
- Import as "merge"
- Repeat with other half

API Connections — Managing API integrations
Merchant Accounts — Payment provider configuration
DB Environments — Database configuration
Site Management — Site-level settings
Security Best Practices — Credential management

WP-CLI Commands

Export via WP-CLI

# Export all configuration to file
wp gsm export-config --output=/path/to/export.json

# Export and pipe to encrypted storage
wp gsm export-config | gpg --encrypt --recipient [email protected] > config.json.gpg

# Automated daily backup
0 2 * * * wp gsm export-config --path=/var/www/html > /backups/gsm-$(date +\%Y\%m\%d).json

Import via WP-CLI

# Import with merge strategy (default)
wp gsm import-config /path/to/import.json

# Import with replace strategy (clean slate)
wp gsm import-config /path/to/import.json --strategy=replace

# Import from encrypted backup
gpg --decrypt config.json.gpg | wp gsm import-config --stdin

Note: WP-CLI commands available in plugin version 1.11.0+

API Reference

Export Endpoint

POST wp-admin/admin-ajax.php?action=gsm_export_configuration

Parameters:

nonce — WordPress nonce (wp_create_nonce('gsm_export_configuration'))

Response:

{
  "success": true,
  "data": {
    "message": "Exported 5 API connection(s), 8 merchant account(s), and 3 database environment(s).",
    "json": "{...}",
    "filename": "gsm-middleware-config-example-2024-12-15-103045.json"
  }
}

Import Endpoint

POST wp-admin/admin-ajax.php?action=gsm_import_configuration

Parameters:

nonce — WordPress nonce (wp_create_nonce('gsm_import_configuration'))
json — JSON string (configuration file contents)
strategy — merge or replace

Response:

{
  "success": true,
  "data": {
    "message": "Imported 5 API connection(s), 8 merchant account(s), and 3 database environment(s)."
  }
}

Maintenance Schedule

Daily (Automated):

Export configuration to encrypted backup
Rotate old backups (keep 7 days)

Weekly:

Verify latest backup can be restored (test on staging)

Monthly:

Archive monthly backup (keep 12 months)
Audit who has access to export/import feature

Quarterly:

Full disaster recovery drill (restore from backup to clean server)
Review and update backup encryption keys

Overview​

What Gets Exported​

Complete Configuration Package​

Metadata Included​

Export Process​

Step-by-Step​

Export File Structure​

Import Process​

Step-by-Step​

Import Strategies Explained​

Merge Strategy (Recommended)​

Replace Strategy (Destructive)​

Common Workflows​

Workflow 1: Dev → Production Migration​

Workflow 2: Credential Rotation Across Environments​

Workflow 3: Disaster Recovery​

Workflow 4: Developer Onboarding​

Security Considerations​

⚠️ Critical Security Warnings​

Best Practices​

Troubleshooting​

"Invalid JSON file" Error​

"Missing required field 'metadata'" Error​

Import Succeeds But API Connections Don't Work​

"You do not have permission" Error​

Replace Import Deleted Needed Config​

File Upload Fails (Large File)​

Related Documentation​

WP-CLI Commands​

Export via WP-CLI​

Import via WP-CLI​

API Reference​

Export Endpoint​

Import Endpoint​

Maintenance Schedule​

Overview

What Gets Exported

Complete Configuration Package

Metadata Included

Export Process

Step-by-Step

Export File Structure

Import Process

Step-by-Step

Import Strategies Explained

Merge Strategy (Recommended)

Replace Strategy (Destructive)

Common Workflows

Workflow 1: Dev → Production Migration

Workflow 2: Credential Rotation Across Environments

Workflow 3: Disaster Recovery

Workflow 4: Developer Onboarding

Security Considerations

⚠️ Critical Security Warnings

Best Practices

Troubleshooting

"Invalid JSON file" Error

"Missing required field 'metadata'" Error

Import Succeeds But API Connections Don't Work

"You do not have permission" Error

Replace Import Deleted Needed Config

File Upload Fails (Large File)

Related Documentation

WP-CLI Commands

Export via WP-CLI

Import via WP-CLI

API Reference

Export Endpoint

Import Endpoint

Maintenance Schedule