Migrate from Classic Grid to Grid Custom Field
Release Date: Jul 6, 2026
Applies to: Table Grid Next Generation App version 4.24.0 and later on Jira Cloud
This document provides an overview of the new Migrate to Grid Custom Field feature, including its purpose, workflow, and behavior.
It helps Jira administrators move existing Classic Grids to Grid Custom Fields directly within Table Grid - preserving all supported configurations and data, with no manual export, import, or reconfiguration required. By pairing this high-level overview with step-by-step usage instructions, the document supports a smooth transition to the Grid Custom Field for teams already using Classic Grids.
Overview
Table Grid Next Generation offers two approaches to use Grids on Jira Cloud:
Classic Grid: The original panel-based add-on field used by most existing customers today.
Grid Custom Field: A native, Forge-based Jira custom field.
Both ways remain fully supported, making migration entirely optional. However, the Grid Custom Field integrates more deeply with Jira's native field management. We recommend it for new deployments and for teams seeking tighter alignment with standard Jira administration workflows.
This guide walks Jira administrators through migrating existing Classic Grids to Grid Custom Fields using the built-in migration wizard. It also covers how to convert a Grid Custom Field back to a Classic Grid if you ever need to reverse the process.
Why migrate?
Grid Custom Fields embed Table Grid data directly into Jira as native custom fields while preserving all structured data capabilities. Compared to the Classic Grid, the Grid Custom Field behaves as a first-class Jira citizen:
Feature Category | Classic Grid | Grid Custom Field |
|---|---|---|
Field Management | Managed entirely within the Table Grid app administration panel only. | Native Field Management: Managed directly from Jira's standard Fields page (Create, Edit, Delete, Restore, and visibility controls). |
Field Contexts | Does not support multiple contexts; requires duplicating fields if different projects and issue types need different configurations. | Multiple Contexts per Field: Use a single field with distinct configurations and default values across different project types. |
Screen Placement | Rendered inside a custom add-on panel on the issue view. The display position is fixed and cannot be changed on the issue view. | Flexible Screen Placement: Added directly to Jira issue screens in both company-managed and team-managed projects - managed by Jira. You can change the position of the Grid Custom Field in each Work item layout. |
JQL Searching | Requires complex JQL queries and using in a separate panel. | Simpler JQL: Search grid data directly using native Jira JQL: |
For details about Grid Custom Field, refer to this documentation: Grid Custom Field
Data safety
Zero Data Loss Guaranteed
The Classic Grid and its corresponding Grid Custom Field share the same data source.
If the migration fails at any stage, all changes are automatically rolled back. If you decide to reverse the migration later, you can convert the Grid Custom Field back to a Classic Grid with all data fully preserved.
Before you begin
Ensure you meet the following prerequisites before starting the migration:
You must be a Jira Administrator with permissions to manage apps.
Table Grid Next Generation (version 4.24.0 or later) must be installed and active on your Jira Cloud site
Migrate a Classic Grid
The migration wizard processes your data in 4 steps. You can safely close the wizard popup at any time - the process will continue running in the background. You can also migrate multiple grids concurrently as independent background processes.
Step 1 - Select Grid
Navigate to Table Grid > Grids.
Locate the grid you want to migrate, go to the Action column, and click Migrate (Hovering over it displays the tooltip "Migrate to Grid Custom Field").
The migration popup opens, showing:
Grid name: The Classic Grid being migrated.
Projects: The Jira projects currently associated with the grid.
Issue types: The issue types associated with the grid.
Note: Any configurations not supported by the Grid Custom Field will be ignored during this process (see full list in the Architectural Differences & Considerations section below).
Review the details and click Next to proceed.
Step 2 - Review
The Review screen displays your migration mapping and highlights key architectural changes before execution:
Field | Description |
|---|---|
Classic Grid (Source) | The original classic grid being migrated |
Issues Affected | Total number of issues associated with this classic grid. |
Grid Custom Field (Destination) | The name of the new native custom field that will be created. |
Important Migration Warnings
Global Context Migration: The field configuration will be migrated to the Global context.
After migration, you must manually add the Grid Custom Field to your Field Schemes to make it available in your projects, and to Screens to display it on issue views.Team-Managed Projects: If the grid is associated with team-managed projects, the Grid Custom Field will be available for them, but you must manually enable it within each project's individual Project settings.
Review the details carefully, then click Run to initiate the migration.
Step 3 - Migration Progress
The migration runs automatically across three sequential sub-steps:
Create Grid Custom Field
Migrate grid configuration
Mapping issue data
A progress bar tracks overall completion.
Important: Grid Restrictions During Migration
Actions Disabled: Once the migration process starts, administrative operations for the selected Classic Grid (Edit and Delete) will be completely disabled within the Table Grid administration panel to prevent configuration conflicts.
Restrict Data Modifications: We strongly recommend that end users avoid modifying any grid data within Jira issues for the specific grid currently undergoing migration. To ensure data consistency, consider planning the migration during off-peak hours or a scheduled maintenance window.
What you can do during migration:
To run in the background: Click the Close button. To reopen the tracker, click the View migration link that appears below the grid's name in your Grids list.
To Cancel: Click Cancel and confirm. The process stops immediately and all partially migrated data is rolled back.
You will automatically move to the Final step to view Result https://tablegrid.atlassian.net/wiki/spaces/ATM/pages/1213792261/Migrate+from+Classic+Grid+to+Grid+Custom+Field#%E2%8F%B9%EF%B8%8F-Migration-Canceled
Performance Note & Planning
Estimated Benchmark: In standard testing environments, processing times typically average around 8–12 minutes per 10,000 issues.
Variable Factors: Please note that actual migration speeds may vary depending on current Atlassian Cloud API rate limits, network conditions, and the overall complexity of your grid configurations.
Best Practice: For grids with large production datasets, we highly recommend running the migration during off-peak hours or scheduling a routine maintenance window to prevent any operational impact. Remember, you can safely close the popup window; the process will continue running seamlessly in the background.
At the end of the migration, the popup will display the migration status:
Migration Completed
Migration Failed
Once completed, click View Result.
Step 4 - Result
The final step displays one of three outcomes:
✅ Migration Successful
The new Grid Custom Field is now available in the Grid Custom Fields list. The Classic Grid is removed from the Grids list.
A Next steps banner guides you to add the field to Field Schemes and Screens. Refer to this section https://tablegrid.atlassian.net/wiki/spaces/ATM/pages/edit-v2/1213792261#After-migration%3A-required-steps for detailed guidance.
From here you can:
Click Contact to reach the Table Grid support portal.
Click Finish to close the popup and complete this migration.
❌ Migration Failed
No changes were made to your production data. The Classic Grid remains in the Grids list. From here you can:
Click Retry to restart the migration from the very beginning.
This action automatically cleans up (deletes) any partially created Grid Custom Field from the failed attempt, then generates a fresh one for the new run.Click Download to get a detailed error log (JSON format).
Click Contact to reach the Table Grid support portal.
Click Finish to close the popup and complete this migration.
⏹️ Migration Canceled
No changes were made. The Classic Grid remains active with all actions re-enabled.
From here you can:
Click Retry to start a new migration run from the beginning.
This action clears any temporary or partially created Grid Custom Field from the canceled attempt, then creates a fresh one for the new run.Click Finish to close the popup and complete this migration.
Required Post-Migration Steps
Crucial Note
After a successful migration, the Grid Custom Field exists in Jira but will remain hidden on issue views until you complete the following steps.
1. Add to Field Schemes
Add the Grid Custom Field to the Field Schemes for each project where it should be available.
On the success screen, click Add to Field Schemes ↗ to go directly to the field's scheme settings.
Then, click “Add to n field schemes” button
2. Add to Screens
Add the field to the issue Screens where it should appear.
On the success screen, click Add to Screens ↗ to go directly to the screen association settings.
Check the boxes next to the appropriate project screens.
Click Update button.
3. Configure team-managed projects (if applicable)
If your grid belongs to team-managed projects, it won't show up automatically. Go to each team-managed project's Project settings individually to add the field manually.
For details, refer to How to apply Grid Custom Field to work item screens — team-managed projects.
Convert back to Classic Grid
If you need to revert, you can safely convert a migrated Grid Custom Field back to a Classic Grid at any time.
Reversion Context
This option is only available for Grid Custom Fields created via migration; it cannot be used for manually created ones.
No data will be lost during this process.
Any column or settings changes made after the initial migration are preserved when converting back
Step 1 - Start the conversion
Go to Grid Custom Fields.
In the Action column for the field, click the Convert back to Classic Grid icon (only visible on migrated fields)
Step 2 - Review the conversion warnings
A confirmation popup will display your conversion details along with critical scope warnings:
Scope Restoration: The Classic Grid will be restored strictly to its original pre-migration scopes.
Any projects or issue types added to the Grid Custom Field after migration will not be automatically included. You must re-add those scopes manually after conversion to continue using their grid data.Context Deletion: If you added additional custom contexts to the Grid Custom Field after migration, converting back will permanently delete those extra contexts and their associated data.
Click Convert back to confirm and execute.
Step 3 - Conversion progress
The conversion runs two sub-steps:
Remove Grid Custom Field
Restore Classic Grid
Do Not Close the Window
This popup cannot be closed while the conversion is running. This action is extremely fast and typically completes within 1–2 seconds.
Step 4 - Conversion result
On Success: The Grid Custom Field is deleted, and the Classic Grid reappears in your Grids list. Remember to re-configure any post-migration scopes if necessary.
From here you can:
Click Contact to reach the Table Grid support portal.
Click Finish to close the popup and finish this conversion.
On Failure: No changes are made to your grid custom field. It remains active on the Grid Custom Fields page. No Classic Grid was created.
From here you can:
Click Retry to run the conversion again.
Click Download to get a detailed error log (JSON format).
Click Contact to reach the Table Grid support portal.
Click Finish to close the popup and finish this conversion.
Result
Classic Grid displays on issue before migration:
After successful migration, the migrated Grid Custom Field appears on the issue once added to the relevant Field Schemes and Screens.
Architectural differences and Considerations
Limitation | Details | |
|---|---|---|
| 1 | Unsupported Configurations of Grid Custom Field | The Grid Custom Field does not support the following Classic Grid configuration. These settings are silently ignored during migration:
All other standard configurations and grid data migrate normally. These values will be restored exactly as they were at the time of migration and will remain unaffected by any changes users make to the Grid Custom Field afterward. |
| 2 | Field configuration migrates to Global context only | The Classic Grid's per-project scope is not replicated automatically - you must configure Field Schemes and Screens manually after migration to view Grid Custom Field on Issues. |
| 3 | Team-managed projects require manual setup | The field is available in team-managed projects after migration, but must be added in each project's Project settings individually. |
| 4 | Convert back restores migration-time scopes | Projects or issue types added to the Grid Custom Field after migration are excluded when using the Convert Back feature. You must add them manually to the restored Classic Grid. |
| 5 | Additional contexts are permanently deleted on convert back. | Extra custom contexts added to the Grid Custom Field post-migration are permanently deleted along with their data upon converting back to a Classic Grid. |
Need help?
If you encounter any issues or unexpected behaviors during the migration process, please visit the Table Grid Support Portal. Our team is happy to assist you!
Conclusion
Migrating from the Classic Grid to the Grid Custom Field is optional, as both remain fully supported. The built-in wizard ensures a safe transition with zero data loss and supports automatic rollbacks if the process fails or is canceled.
To ensure a seamless rollout, remember these key points:
System Locks: During migration, administrative actions (Edit, Delete, Migrate) are disabled. Users must avoid modifying grid data within Jira issues to maintain data consistency.
Post-Migration Setup: The new field remains hidden until you manually add it to the relevant Field Schemes and Screens, and configure team-managed projects individually.
Review Architectural differences and Considerations: Check the Architectural differences and Considerations section - such as the lack of support for customer portal editing or automatic project mapping - before deploying broadly.