OX CSV Importer

A powerful WordPress admin-only plugin for importing CSV data into posts, users, meta tables, and taxonomy relationships. Designed for one-off or occasional imports by site administrators with flexible field mapping and comprehensive data validation.

Features

• Flexible Field Mapping - Map CSV columns to any WordPress database field or meta key
• User Imports - Create users with custom meta data and optional email notifications
• Post Imports - Import posts with categories, tags, and custom fields
• Deduplication Logic - Update existing records or skip duplicates based on unique fields
• Default Values - Set fallback values for missing or empty CSV fields
• Category/Tag Lookup - Built-in tool to find taxonomy term IDs
• Multi-format Support - Handles CSV, TSV, and pipe-delimited files
• Encoding Detection - Automatic UTF-8 conversion for various character encodings
• Admin-Only Access - Secure, admin-only interface with proper capability checks
• Database Compatibility - Works with MySQL and SQLite databases

Installation

1. Upload the ox-csv-importer folder to your /wp-content/plugins/ directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Access the CSV Importer from the admin menu (CSV Importer)

Multisite Compatibility

The plugin automatically handles multisite table prefixes transparently. When you see table names like wp_users, wp_posts, wp_usermeta, and wp_postmeta in the interface, the plugin internally maps these to the actual table names used by your WordPress installation (e.g., wp_2_users, wp_3_posts, etc.).

No special configuration is required - the mapping is handled automatically and is completely transparent to the user. This ensures the plugin works correctly in both single-site and multisite installations without any user intervention.

Usage

Step 1: Select File and Options

1. Upload CSV File - Choose your CSV file (first row should contain column headers)
2. Field Separator - Select the character that separates fields in your file:
   • Comma (,)
   • Tab (\t)
   • Pipe (|)
3. Target - Choose what you're importing:
   • Posts - Import into WordPress posts table
   • Users - Import into WordPress users table
4. Options:
   • Overwrite - Check to update existing records, uncheck to skip duplicates
   • Notify Users - Send WordPress welcome emails to new users (users only)

Step 2: Map Fields

For each CSV column, specify:

• Table - Which database table to import into:
  • wp_users - Main user fields (username, email, etc.)
  • wp_usermeta - User meta data
  • wp_posts - Main post fields (title, content, etc.)
  • wp_postmeta - Post meta data
• Column - The specific database field or meta key
• Unique - Check if this field should be unique (used for deduplication). Only one field can be selected as unique per import.

Required Fields

For Users:

• user_login - Username (must be unique)
• user_email - Email address (must be unique)

For Posts:

• post_title - Post title
• post_content - Post content
• post_status - Post status (publish, draft, etc.)

Step 3: Default Values

Set fallback values for required fields that might be missing from your CSV:

• Table - Select the target table
• Field - Choose the field or meta key
• Default Value - Enter the value to use if CSV is empty

Special Tables:

• wp_term_relationships - Use to assign categories/tags to posts via term_taxonomy_id
  • Use the "Lookup Categories and Tags" button to find the correct term_taxonomy_id values
  • Set term_taxonomy_id as the field and enter the ID value
  • This will assign the specified category/tag to all imported posts

Examples

Importing Users

CSV Structure:

username,email,first_name,last_name,role,company
john_doe,john@example.com,John,Doe,editor,Acme Corp
jane_smith,jane@example.com,Jane,Smith,subscriber,XYZ Inc

Field Mapping:

• username → wp_users → user_login (Unique: ✓)
• email → wp_users → user_email
• first_name → wp_usermeta → first_name
• last_name → wp_usermeta → last_name
• role → wp_usermeta → wp_capabilities
• company → wp_usermeta → company

Assigning OX Content Blocker Tags to Users

To assign OX Content Blocker access tags to users during import, add a column to your CSV for the tags and map it to the wp_usermeta table with the meta key _oxcb_access_tags.

• The value should be a JSON-encoded array of tag slugs (e.g., ["premium","member"]).
• Alternatively, you can enter a single tag as ["premium"].
• The tag slugs must match those defined in OX Content Blocker (see Settings → OX Tag Management in your WordPress admin).

Example CSV:

username,email,first_name,last_name,role,oxcb_tags
john_doe,john@example.com,John,Doe,editor,"[\"premium\",\"member\"]"
jane_smith,jane@example.com,Jane,Smith,subscriber,"[\"basic\"]"

Field Mapping:

• oxcb_tags → wp_usermeta → _oxcb_access_tags

This will assign the specified OX Content Blocker tags to each user on import. The tags control access to restricted content as configured in the OX Content Blocker plugin.

Importing ACF User Fields

To import data into Advanced Custom Fields (ACF) user fields, map your CSV columns to the wp_usermeta table and use the ACF field name (slug) as the meta key. For example, if you have a field group called "User Extra Data" with fields wine-course and course-info, you can import values for these fields as follows:

Example CSV:

username,email,first_name,last_name,role,wine-course,course-info
john_doe,john@example.com,John,Doe,editor,Beginner,"Intro to Wine"
jane_smith,jane@example.com,Jane,Smith,subscriber,Advanced,"Sommelier Program"

Field Mapping: | CSV Column | Table | Meta Key | Effect | |--------------|--------------|--------------|-------------------------------| | wine-course | wp_usermeta | wine-course | Populates ACF “wine-course” | | course-info | wp_usermeta | course-info | Populates ACF “course-info” |

ACF will automatically recognize and display these values in the user profile and in your templates. No plugin code changes are required for this functionality.

Default Values:

• wp_users → user_pass → [generated password]
• wp_users → user_status → 0

Importing Posts

CSV Structure:

title,content,status,category_ids,tags,featured_image
My First Post,This is the content...,publish,1;2,tag1;tag2,image1.jpg
Another Post,More content here...,draft,3,,image2.jpg

Field Mapping:

• title → wp_posts → post_title (Unique: ✓)
• content → wp_posts → post_content
• status → wp_posts → post_status
• category_ids → wp_postmeta → _category_ids
• tags → wp_postmeta → _tags
• featured_image → wp_postmeta → _thumbnail_id

Advanced Features

Category and Tag Lookup

Use the "Lookup Categories and Tags" button to find the correct term_taxonomy_id values for your categories and tags. This tool displays all available terms with their IDs.

Deduplication Logic

Important: Only one field can be selected as unique per import. This field is used to identify existing records for deduplication.

When "Overwrite" is enabled:

• The plugin finds existing records using the unique field
• Updates the existing record with new data
• Preserves the original ID

When "Overwrite" is disabled:

• Skips records that already exist
• Only creates new records
• Reports skipped records in the results

Encoding Support

The plugin automatically detects and converts:

• UTF-8
• UTF-16 (LE/BE)
• ISO-8859-1
• Windows-1252

Custom Post Types

To import custom post types:

1. Map the post_type field to wp_posts → post_type
2. Set the appropriate post type value in your CSV or defaults
3. Ensure the custom post type is registered in WordPress

Troubleshooting

Common Issues

"Permission denied" error:

• Ensure you're logged in as an administrator
• Check that the plugin is properly activated

"No file uploaded" error:

• Verify the file is a valid CSV format
• Check file size limits in your WordPress configuration

"Failed to read header row" error:

• Check the field separator setting
• Ensure the first row contains column names
• Verify file encoding

Users not receiving emails:

• Check WordPress email configuration
• Verify SMTP settings if using an email plugin
• Check spam folders

Posts not appearing:

• Verify post status is set to "publish"
• Check if posts are assigned to the correct post type
• Ensure required fields are mapped

Deduplication not working:

• Ensure only one field is marked as unique
• Check that the unique field contains actual values in your CSV
• Verify the unique field mapping is correct

Debug Mode

To enable detailed logging:

1. Add define('WP_DEBUG', true); to your wp-config.php
2. Check the debug log for detailed import information
3. Look for specific error messages in the import results

Security

• Admin-only access - Plugin requires manage_options capability
• Nonce verification - All AJAX requests are protected
• Data sanitization - All input is properly sanitized
• SQL injection protection - Uses WordPress prepared statements
• File upload validation - Only CSV files are accepted

Performance

• Batch processing - Handles large files efficiently
• Memory optimization - Processes files in chunks
• Database transactions - Ensures data integrity
• Progress reporting - Real-time feedback during imports

Database Schema

The plugin works with standard WordPress tables:

• wp_users - User accounts
• wp_usermeta - User metadata
• wp_posts - Posts and pages
• wp_postmeta - Post metadata
• wp_terms - Taxonomy terms
• wp_term_taxonomy - Term taxonomy relationships
• wp_term_relationships - Post-term relationships

API Reference

Hooks and Filters

// Filter import results
add_filter('ox_csv_importer_user_created', function($user_id, $userdata) {
    // Custom logic after user creation
    return $user_id;
}, 10, 2);

// Filter post data before import
add_filter('ox_csv_importer_post_data', function($postdata, $row) {
    // Modify post data
    return $postdata;
}, 10, 2);

Custom Field Mapping

// Add custom meta fields to the field list
add_filter('ox_csv_importer_user_meta_fields', function($fields) {
    $fields[] = 'custom_field_name';
    return $fields;
});

Changelog

Version 2.0.0

• Added term_relationships support for taxonomy assignments
• Enhanced multisite compatibility with dynamic table prefix mapping
• Improved overwrite functionality for both users and posts
• Added comprehensive debug logging for troubleshooting
• Fixed missing posts import logic
• Enhanced error handling and validation
• Added support for default values in term_relationships

Version 0.1.0

• Initial release
• User import functionality
• Post import framework
• Flexible field mapping
• Default value support
• Category/tag lookup tool
• Deduplication logic
• Multi-format CSV support
• Encoding detection
• Admin-only interface

Development

Contributing

This plugin is open source and contributions are welcome!

GitHub Repository: https://github.com/macdudeuk2/ox-csv-importer

To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Local Development

Requirements:

• WordPress 5.0+
• PHP 7.4+
• MySQL 5.6+ or MariaDB 10.1+ (or SQLite)

Setup:

1. Clone the repository: git clone https://github.com/macdudeuk2/ox-csv-importer.git
2. Copy to your WordPress plugins directory: wp-content/plugins/ox-csv-importer/
3. Activate the plugin in WordPress admin
4. Start developing!

Building for Distribution

The plugin includes a build script for creating distribution packages:

./build_distribution.sh

This creates a zip file ready for distribution.

Support

For support, feature requests, or bug reports, please contact the plugin developer.

License

This plugin is licensed under the GPL v2 or later.

---

OX CSV Importer - Powerful, flexible CSV import for WordPress.