Get Started

MigrateK2 Pro is a professional Joomla 3.x component that migrates your entire K2 content library into native Joomla articles — fully automated, with real-time progress tracking and complete rollback support.

Key Features:

• One-Click Migration: Migrate items, categories, tags, extra fields, images, and URL redirects in a single run
• Live Progress Bar: AJAX-powered batch processing with real-time status updates — handles 10,000+ articles without timeouts
• K2 Data Export: Download raw K2 data as CSV, JSON, or SQL without running any migration
• 301 URL Redirects: Automatically creates redirect entries so old K2 URLs continue to work
• Image Migration: Copies K2 images with path rewriting, caption and credit preservation
• Full Rollback: Reset button removes all migrated content cleanly, with detailed deletion counts
• Migration Log: Persistent activity log with color-coded severity levels for troubleshooting
• Idempotent: Re-running after a failure picks up where it left off — no duplicates
• Configurable: Custom image path, skip trashed content, fallback author settings

Who is this for?

MigrateK2 Pro is designed for Joomla administrators who need to move away from the K2 component and use Joomla's native content system. Whether you have 50 articles or 50,000, the component handles the migration safely and efficiently — preserving your content, SEO, and site structure.

Installing the Component

MigrateK2 Pro is distributed as a single installable ZIP file. To install:

1. Log in to your Joomla administrator panel
2. Navigate to Extensions > Manage > Install
3. Click the Upload Package File tab
4. Drag and drop or browse for com_migratek2pro_vX.x.zip
5. Click Upload & Install

On successful installation you will see: "Installing component was successful."

What Gets Installed

The installer automatically sets up:

• Admin component: Controllers, models, views, helpers, and templates
• Site stub: A front-end file that redirects visitors to the homepage (this is an admin-only component)
• Language files: English (en-GB) translation strings for all UI text
• Database tables: Three custom tables are created:
  • #__migratek2_progress — tracks migration state and resume position
  • #__migratek2_mapping — maps K2 IDs to Joomla IDs for rollback and deduplication
  • #__migratek2_log — stores migration activity log entries
• Admin menu entry: "MigrateK2 Pro" appears under Components in the admin menu

System Requirements

• Joomla 3.10 or higher
• PHP 7.2 or higher
• MySQL 5.6+ or MariaDB 10.1+
• K2 component installed with data in its tables
• PHP ZipArchive extension (for CSV export as ZIP)
• Writable images/ directory (for image migration)

Verifying Installation

1. Go to Extensions > Manage > Manage
2. Search for "migratek2" — you should see com_migratek2pro listed as a Component
3. Click Components > MigrateK2 Pro to open the dashboard
4. The dashboard will automatically detect whether K2 is installed and display content counts

Updating

To update to a newer version, simply install the new ZIP over the existing installation. The component uses method="upgrade" so your settings, progress, and log data are preserved.

Uninstalling

To remove the component:

1. Go to Extensions > Manage > Manage
2. Find MigrateK2 Pro and select it
3. Click Uninstall

This drops all three MigrateK2 tables and removes all component files. Important: Migrated Joomla content (articles, categories, tags, fields) is NOT removed during uninstall — only the component's own tables are dropped. Run a Reset before uninstalling if you want to remove migrated content.

Accessing Component Options

To configure MigrateK2 Pro:

1. Go to Components > MigrateK2 Pro
2. Click the Options button in the top-right toolbar
3. Configure the settings below
4. Click Save & Close

Image Base Path

• Setting: Image Base Path
• Default: images/k2-migrated
• Description: The folder where migrated K2 images will be copied to. This path is relative to your Joomla root directory.
• Notes:
  • The folder will be created automatically if it does not exist
  • The folder must be writable by the web server
  • During pre-flight checks, the system verifies this folder is accessible
  • All K2 image paths in article content are rewritten to point to this new location
• Examples:
  • images/k2-migrated — default, clean separation from other images
  • images/articles — if you want migrated images alongside existing Joomla images
  • images/content/k2 — nested folder structure

Skip Trashed Content

• Setting: Skip Trashed
• Default: Yes
• Description: When enabled, K2 items and categories that are in the trash (trash = 1) are excluded from migration. Only published and unpublished content is migrated.
• Recommendation: Leave this enabled unless you specifically need to recover trashed K2 content.

Fallback User

• Setting: Fallback User
• Default: Empty (uses current admin user)
• Description: When a K2 item's author (created_by) does not exist as a Joomla user, this fallback user ID is used instead. If left empty, the currently logged-in administrator's ID is used.
• When to set this: If you have K2 items authored by users that have been deleted from Joomla, set this to a valid user ID (e.g., the Super Admin) to prevent orphaned articles.

Recommended Pre-Migration Settings

1. Set Image Base Path to your preferred location
2. Leave Skip Trashed enabled (unless you need trashed content)
3. Set Fallback User if your K2 has items from deleted users
4. Click Save & Close
5. Return to the dashboard and verify the system checks pass

Dashboard Overview

The Dashboard is the landing page when you open MigrateK2 Pro. It provides a complete overview of your K2 data and migration status.

Status Banner

A colored banner at the top shows the current state:

• Green — Migration complete: All K2 data has been imported into Joomla
• Yellow — In progress: Migration was started but not yet finished. Click Continue to resume.
• Blue — Ready: K2 data detected, ready to migrate
• Red — Error: K2 is not installed or not detected

System Checks Panel

The left panel runs automatic pre-flight checks:

• K2 component installed — verifies K2 exists in the extensions table
• K2 items found — shows the count of K2 items (excluding trashed if configured)
• K2 categories found — shows the count of K2 categories
• Media folder — checks that media/k2/items exists
• Source images folder — checks that media/k2/items/src exists

Content Preview Counters

Below the system checks, counter badges show exactly what will be migrated:

• Items — total K2 items
• Categories — total K2 categories
• Tags — total published K2 tags
• Fields — total published K2 extra fields
• Comments — total K2 comments (available for export)
• Attachments — total K2 attachments (available for export)

Quick Export Panel

The right panel provides one-click export buttons:

• CSV — downloads a ZIP file containing one CSV per K2 table
• JSON — downloads a single JSON file with all K2 data
• SQL — downloads INSERT statements ready to import elsewhere

These export all K2 tables at once. For selective table export, use the Download section on the Migration page.

Action Buttons

Below both panels, context-aware action buttons appear:

• Start Migration — appears when no migration has been run yet
• Continue Migration — appears when a migration was interrupted
• View Migration Details — appears after migration is complete
• Reset & Remove Migrated Data — appears after migration (or partial migration)
• View Log — opens the migration activity log

Before You Start

⚠ Create a full backup of your website before migrating.

Use Akeeba Backup, your hosting panel's backup tool, or a manual database dump. Migration adds content to your Joomla database — having a backup allows you to restore if anything goes wrong.

Step-by-Step Migration

1. Open the Migration page: Go to Components > MigrateK2 Pro, then click Start Migration or View Migration Details
2. Review what will be migrated: The left panel lists everything that will be copied: items, categories, tags, extra fields, images, and URL redirects
3. Click Start Migration: A confirmation dialog asks if you have created a backup. Click OK to proceed.
4. Watch the progress: The live progress bar shows the current phase and item count
5. Wait for completion: The bar turns green and shows "100%" when finished

Migration Phases

The migration runs in four sequential phases:

1. Categories — K2 categories are created as Joomla categories, preserving the parent-child hierarchy. Existing categories with matching aliases are reused.
2. Custom Fields — K2 extra field groups and fields are created as Joomla custom field groups and fields. Types are mapped automatically.
3. Tags — K2 tags are migrated to Joomla's native tag system.
4. Items — K2 items are migrated as Joomla articles in batches. Each batch processes a configurable number of items. For each item:
   • Article content (intro text, full text) is created with proper readmore splitting
   • Images are copied and paths are rewritten
   • Tags are associated
   • Custom field values are assigned
   • A 301 redirect is created from the old K2 URL to the new article URL

Progress Bar Details

During the items phase, the progress bar shows:

• Counter: e.g. "4,521 / 10,000 (45%)" — processed vs. total items
• Phase indicator: Numbered steps with color-coded states (pending, active, done)
• Elapsed timer: Shows how long the migration has been running
• Status message: Describes the current action

Handling Errors

If a batch fails (network timeout, server error):

• The system automatically retries up to 3 times with a short delay
• If all retries fail, an error message is displayed with a Retry button
• Click Retry to resume from exactly where it stopped
• Click Stop to pause the migration — you can resume later

Resuming a Migration

If you close the browser or navigate away during migration:

1. Return to Components > MigrateK2 Pro
2. The dashboard will show "Migration in progress"
3. Click Continue Migration
4. The migration resumes from the exact item where it left off — no duplication

After Migration Completes

When the progress bar reaches 100%:

• A green "All done!" status badge appears
• A summary shows the total count of migrated articles
• You can View Log for detailed activity records
• You can Reset to remove everything and start over
• Check your Joomla articles (Content > Articles) to verify the migrated content

Export Overview

MigrateK2 Pro lets you download raw K2 data directly from your database — no migration required. This is useful for archiving, importing into other systems, or analyzing your K2 content externally.

Quick Export (Dashboard)

The dashboard provides one-click export buttons for all K2 tables at once:

• CSV — downloads a ZIP file containing one CSV file per K2 table
• JSON — downloads a single structured JSON file
• SQL — downloads a file with INSERT statements

Selective Export (Migration Page)

For more control, use the "Download K2 Data" panel on the Migration page:

1. Go to Components > MigrateK2 Pro > View Migration Details
2. In the right panel, check the tables you want to export:
   • K2 items — articles with full content, metadata, and settings
   • K2 categories — category hierarchy with descriptions
   • K2 tags — all K2 tags
   • K2 extra fields — custom field definitions and values
   • K2 comments — user comments on K2 items
   • K2 attachments — file attachments linked to K2 items
3. Use Select All to check/uncheck everything
4. Choose your format: CSV, JSON, or SQL
5. Click Download

Format Details

CSV Format:

• Downloads as a ZIP file named k2_export_csv_YYYY-MM-DD.zip
• Contains one CSV file per selected table (e.g., k2_items.csv, k2_categories.csv)
• UTF-8 encoded with BOM for proper Excel compatibility
• First row contains column headers

JSON Format:

• Downloads as k2_export_YYYY-MM-DD.json
• Single file with a structured object: {"items": [...], "categories": [...], ...}
• UTF-8 encoded with pretty-printed formatting
• Ideal for programmatic processing or API import

SQL Format:

• Downloads as k2_export_YYYY-MM-DD.sql
• Contains INSERT INTO statements for each selected table
• Table names use the Joomla prefix placeholder #__
• Can be imported directly into another Joomla database using phpMyAdmin or CLI

Use Cases

• Archiving: Download a complete backup of all K2 content before removing K2
• WordPress migration: Export as CSV or JSON and use a WordPress importer
• Data analysis: Open CSV files in Excel or Google Sheets for content audits
• External backup: Keep an off-site copy of your K2 content independent of your Joomla database

What Reset Does

The Reset function completely reverses a migration by removing all content that was created during the migration process. It returns your Joomla site to its pre-migration state.

What Gets Removed

A reset deletes the following from Joomla:

• Articles — all Joomla articles that were created from K2 items
• Categories — all Joomla categories that were created from K2 categories
• Tags — all Joomla tags that were created from K2 tags, plus tag associations
• Custom fields — all Joomla custom fields created from K2 extra fields, including field values and field groups
• URL redirects — all 301 redirect entries created by MigrateK2 Pro in com_redirect
• Migration progress — the progress counter is reset to zero
• Migration log — all log entries are cleared

What Is NOT Removed

• K2 data — your original K2 tables are never modified or deleted
• Other Joomla content — articles, categories, and tags that existed before the migration are untouched
• Copied image files — images copied to the target folder remain on disk (delete manually if needed)
• Component settings — your MigrateK2 Pro configuration is preserved

How to Reset

1. Go to the Dashboard or Migration page
2. Click Reset & Remove Migrated Data
3. A confirmation dialog warns that this action is permanent
4. Click OK to proceed
5. A detailed summary shows exactly what was removed: e.g., "Removed: 16 articles, 4 categories, 7 tags, 6 custom fields, 32 redirects"

Orphan Detection

The rollback engine goes beyond just the mapping table. It also detects and removes:

• Orphan custom fields: Fields with names starting with k2_ that may have been created by older or partial migrations and are not tracked in the mapping table
• Empty field groups: Field groups that have no remaining fields after cleanup — these are removed to prevent clutter

This ensures a truly clean slate even if previous migration attempts left behind untracked data.

After Reset

Once the reset is complete:

• The dashboard returns to the "Ready to migrate" state
• You can run a fresh migration immediately
• All K2 data is still intact and available for re-migration
• The backup warning reappears as a reminder

Accessing the Log

To view the migration log:

• Click View Log from the Dashboard or Migration page, or
• Go to Components > MigrateK2 Pro > Migration Log from the submenu

Log Entry Format

Each log entry contains:

• Time — timestamp of when the action occurred
• Level — severity badge: INFO (blue), SUCCESS (green), WARNING (yellow), or ERROR (red)
• Phase — which migration step generated the entry (preflight, categories, fields, tags, items, complete)
• Message — a human-readable description of what happened

Log Levels

• INFO — normal activity: "Migration started", "Pre-flight passed", "Batch complete: migrated 50 items"
• SUCCESS — phase completions: "Migrated 4 categories", "Migrated 7 tags", "Migration complete"
• WARNING — non-critical issues: "K2 item author not found, using fallback user", "Image file not found"
• ERROR — failures: "Failed to save article", "Database error during category creation"

What Gets Logged

The following events are recorded:

• Migration start and end
• Pre-flight check results
• Each phase start and completion with counts
• Category creation and reuse (when existing alias is detected)
• Field group and field creation
• Tag migration counts
• Item batch progress (every batch reports processed count)
• Any errors or warnings during the process

Managing the Log

• Clear Log — click the "Clear Log" button to remove all entries. A confirmation dialog prevents accidental clearing.
• Automatic clearing — the log is automatically cleared when you run a Reset/Rollback
• Storage — the log is stored in the #__migratek2_log database table. It shows the most recent 500 entries by default.

Using the Log for Troubleshooting

1. Run your migration
2. If something seems wrong, open the log
3. Look for ERROR or WARNING entries
4. The phase and message will tell you exactly what failed and at which point
5. Fix the underlying issue (e.g., folder permissions, missing user) and re-run

K2 Items → Joomla Articles

The following K2 item fields are mapped to Joomla article fields:

• title → article title
• alias → article alias (URL slug)
• introtext → article introtext
• fulltext → article fulltext (if K2 fulltext is empty, introtext is intelligently split at the <hr id="system-readmore"> tag)
• catid → mapped to the corresponding migrated Joomla category
• published → article state (published, unpublished, trashed)
• featured → featured flag
• created / created_by → article created date and author
• modified / modified_by → article modified date and editor
• publish_up / publish_down → scheduled publishing dates
• metadesc / metakey → meta description and keywords
• ordering → article ordering
• hits → article hit count
• access → access level
• language → language assignment

K2 Categories → Joomla Categories

• Full parent-child hierarchy preserved
• name → category title
• alias → category alias
• description → category description
• published → category state
• access → access level
• language → language assignment
• Idempotent: existing categories with matching alias + parent are reused, not duplicated

K2 Tags → Joomla Tags

• Tag names and aliases are migrated
• Tag-to-article associations are preserved via #__contentitem_tag_map
• Only published tags are migrated

K2 Extra Fields → Joomla Custom Fields

• Field groups → Joomla custom field groups (scoped to com_content)
• Individual fields → Joomla custom fields with mapped types
• Field values → per-article field value assignments
• Media URLs inside field values are rewritten to the new image path

K2 Images → Joomla Images

• Item images are copied from media/k2/items/ to the configured image base path
• All media/k2/ paths in article content and field values are rewritten
• image_caption → mapped to Joomla's intro/fulltext image caption fields
• image_credits → mapped to Joomla's intro/fulltext image alt text fields

K2 URLs → 301 Redirects

• For each migrated item, two redirect entries are created in com_redirect:
• ID-based URL: /component/k2/item/123 → new Joomla article URL
• Alias-based URL: /component/k2/item/my-article-title → new Joomla article URL
• Redirects use 301 status (permanent redirect) for SEO preservation
• All redirects are tagged with "MigrateK2 Pro" comment for clean rollback

K2 Not Detected

• Check K2 is installed: Go to Extensions > Manage and search for "K2". It must be listed as a component.
• Check K2 tables exist: MigrateK2 Pro looks for #__k2_items and #__k2_categories. If K2 was partially uninstalled, the tables may be missing.
• Database prefix: The component uses Joomla's configured database prefix. If your prefix is non-standard, this is handled automatically.

Migration Stuck or Frozen

• Check your browser console: Press F12 and look for JavaScript errors or failed network requests
• PHP timeout: If your server has a very low max_execution_time, individual batches may time out. Increase it to at least 60 seconds.
• Memory limit: Large articles with many images may require more memory. Set memory_limit to at least 128M.
• Close and resume: Close the browser, return to the dashboard, and click Continue Migration. The system resumes from the last successful batch.

Duplicate Content After Re-Run

• By design, this should not happen. Categories are checked by alias before creation, and articles are tracked in the mapping table.
• If duplicates appear, run a Reset to clean everything, then run the migration again from scratch.

Images Not Migrated

• Check media folder: Ensure media/k2/items/ exists and contains images
• Check permissions: The target image folder (e.g., images/k2-migrated/) must be writable by the web server
• Check the log: The migration log records warnings for each image that could not be copied

Custom Fields Missing

• Check K2 extra fields: Only published extra fields (published = 1) are migrated
• Verify in Joomla: Go to Content > Fields and Content > Field Groups to see migrated fields
• Field values: Check individual articles in the editor — custom field values appear in the Fields tab

301 Redirects Not Working

• Check com_redirect: Go to Components > Redirects and verify entries exist with "MigrateK2 Pro" in the comment column
• Enable the redirect plugin: Go to Extensions > Plugins, search for "System - Redirect" and make sure it is enabled
• URL format: Redirects are created for /component/k2/item/{id} and /component/k2/item/{alias} patterns. If your K2 used different URL routing, you may need to add custom redirects.

Export Downloads Empty File

• Select at least one table: Ensure you have checked at least one table checkbox before clicking Download
• K2 tables must have data: If a K2 table is empty, that section of the export will be empty
• PHP output buffering: If the download file is corrupted, another extension or plugin may be outputting content before the download headers. Try disabling debug mode temporarily.

White Screen or PHP Errors

• Enable Joomla's Error Reporting in System > Global Configuration > Server — set to "Maximum" temporarily
• Check your PHP error log (usually in /logs/ or configured in php.ini)
• Common causes: insufficient memory, missing PHP extensions, or database connection issues

• Does the migration modify or delete my K2 data?

  • No. MigrateK2 Pro only reads from K2 tables — it never modifies, updates, or deletes any K2 data. Your original K2 content remains completely intact.

• How long does a migration take?

  • It depends on the amount of content. Small sites (under 500 items) typically complete in under a minute. Sites with 10,000+ items may take 5–15 minutes. The live progress bar keeps you informed throughout.

• Can I migrate only specific K2 items or categories?

  • Currently, the migration runs on all K2 content (respecting the "Skip Trashed" setting). If you need to migrate only specific items, you can trash unwanted K2 items before migrating, or remove unwanted Joomla articles after migration.

• What happens if I close the browser during migration?

  • Nothing is lost. The migration progress is saved to the database after each batch. When you return and click Continue Migration, it resumes from exactly where it stopped.

• Can I run the migration multiple times?

  • Yes. If you run a Reset first, you can re-run the migration from scratch. The system is idempotent — categories with matching aliases are reused, not duplicated.

• Will my K2 URLs still work after migration?

  • Yes. MigrateK2 Pro creates 301 redirect entries for every migrated item, mapping old K2 URLs to the new Joomla article URLs. Make sure the "System - Redirect" plugin is enabled.

• Are K2 comments migrated?

  • K2 comments are available for export (CSV, JSON, SQL) but are not migrated into Joomla's native comment system, as Joomla 3 does not have a built-in article comment feature. You can import the exported comments into a third-party comment extension.

• Are K2 attachments migrated?

  • K2 attachments are available for export but are not automatically attached to Joomla articles, as Joomla handles attachments differently. The exported data includes file paths and metadata for manual or scripted import.

• What K2 field types are supported?

  • All K2 extra field types are migrated. Field types are mapped to Joomla custom field types (text, textarea, select, radio, etc.). Field values containing K2 media paths are automatically rewritten.

• Does the component work with Joomla 4 or 5?

  • MigrateK2 Pro vX.x is built for Joomla 3.10+. Since K2 itself is a Joomla 3 component, the migration is designed to run on the same Joomla 3 installation where K2 is installed.

• Can I uninstall K2 after migration?

  • Yes. Once you have verified that all content has been migrated correctly, you can safely uninstall K2. We recommend keeping a backup of your K2 data (use the Export feature) before removing K2.

• What happens when I uninstall MigrateK2 Pro?

  • Uninstalling removes the component files and its three custom database tables (progress, mapping, log). Your migrated Joomla content (articles, categories, tags, fields, redirects) is NOT removed. If you want to remove migrated content, run a Reset before uninstalling.

• Can I use this to migrate K2 to a different Joomla site?

  • The migration runs on the same Joomla installation where K2 is installed. To move content to a different site, use the Export feature to download K2 data, then import it into the target site using Joomla's built-in import or a database tool.

• Is there a limit on how many items can be migrated?

  • No hard limit. The AJAX batch system processes items in small groups to avoid timeouts and memory issues. Sites with 50,000+ items have been tested successfully. The batch size and retry logic ensure reliable completion regardless of volume.

• How do I check if the migration was successful?

  • After migration: (1) Check Content > Articles for your migrated articles, (2) Check Content > Categories for the category tree, (3) Check Content > Fields for custom fields, (4) Check Components > Tags for migrated tags, (5) Check Components > Redirects for 301 entries, and (6) Review the Migration Log for any warnings or errors.