Connected business operations. Flexible deployment.
Learn how to preserve custom field labels and UI preferences during Odoo migrations. This guide covers technical strategies, risk mitigation, and validation steps for seamless upgrades.
Preserving custom field labels and user interface preferences during an Odoo migration requires a structured approach that combines database schema analysis, view definition management, and rigorous testing. Unlike standard data fields, UI elements such as labels, view layouts, and user-specific preferences are often stored in system tables like ir.ui.view and ir.model.fields, which may undergo structural changes between versions. The primary risk is that automatic upgrade scripts may not fully preserve these customizations, leading to broken interfaces, missing labels, or inconsistent user experiences. To mitigate this, organizations must treat UI preservation as a distinct workstream within the migration project. This involves auditing all custom modules, mapping field dependencies, validating view inheritance chains, and executing comprehensive regression testing in a staging environment that mirrors production. Success depends on verifying compatibility against official Odoo documentation for the specific source and target versions, as upgrade paths are not always linear or fully automated.
Odoo stores user interface definitions primarily in the ir.ui.view table, which contains XML records defining how models are displayed. Custom field labels are often defined within these XML views or through the ir.model.fields table, which holds metadata about fields including their string labels. User preferences, such as default views or column visibility, may be stored in user-specific tables or session data. During a migration, the Odoo upgrade process attempts to update these records to match the new version's schema. However, if the base model changes, or if the XML structure is deprecated, the upgrade script may fail to preserve the custom label or may apply a default label instead. Understanding this architecture is critical for identifying where customizations reside and how they might be affected by version changes.
The ir.model.fields table stores field definitions, including the string attribute that defines the label. The ir.ui.view table stores the XML content for forms, trees, and other views. The ir.actions.act_window table defines window actions, which can include default view types. User preferences are often stored in the res.users table or in specific preference models depending on the module. When migrating, these tables are updated by the Odoo upgrade script. If a custom module modifies these tables directly or through XML inheritance, the upgrade process must correctly apply these changes to the new schema. Failure to do so can result in missing labels or broken views.
Before initiating the migration, conduct a comprehensive audit of all custom modules and third-party add-ons. Identify which modules modify field labels, view layouts, or user preferences. Document the specific XML files and Python code that define these customizations. Check for dependencies on deprecated APIs or models that may have changed in the target version. This audit helps identify potential conflicts and areas where manual intervention may be required. Use the Odoo module list and database queries to extract a complete inventory of custom views and fields. This inventory serves as the baseline for validation during and after the migration.
Analyze the dependencies of each custom module to ensure they are compatible with the target Odoo version. Check for deprecated functions, changed model fields, or removed APIs. Verify that third-party add-ons have been updated for the target version and that their documentation confirms compatibility. If a module is not compatible, plan for code refactoring or replacement. This step is crucial because incompatible modules can cause upgrade failures or silent data corruption. Use the Odoo official documentation and release notes for the specific source and target versions to verify compatibility claims.
Execute the migration in a staging environment that mirrors the production database. Use the Odoo upgrade script to move the database to the target version. Monitor the upgrade logs for errors related to view definitions or field labels. If errors occur, investigate the specific XML files or Python code causing the issue. In some cases, manual adjustments to the XML views may be required to align with the new version's syntax. After the upgrade, verify that the ir.ui.view and ir.model.fields tables contain the expected custom labels and view definitions. Use database queries to compare the pre-migration and post-migration states of these tables.
Odoo uses XML inheritance to extend base views. During migration, the inheritance chain must be correctly resolved. If a base view changes in the target version, the inherited views may break. Test each inherited view to ensure it renders correctly. If a view is broken, update the XML to match the new base view structure. This may involve changing node paths, attributes, or adding new nodes. Document all changes made to XML files for future reference and rollback planning.
Perform comprehensive testing of the user interface in the staging environment. Verify that all custom field labels are displayed correctly in forms, trees, and other views. Check that user preferences, such as default views and column visibility, are preserved. Test business processes end-to-end to ensure that UI changes do not impact functionality. Use user acceptance testing (UAT) to validate that the interface meets user expectations. Document any discrepancies and resolve them before proceeding to production. This phase is critical for catching issues that automated tests may miss.
Execute regression tests to ensure that existing functionality is not broken by the migration. Test all custom modules and integrations to verify they work correctly with the new version. Perform performance checks to ensure that UI rendering and data loading are not slower than in the previous version. If performance regressions are detected, investigate the cause and optimize the code or database queries. Use monitoring tools to track system performance during testing and production rollout.
Plan the cutover to minimize downtime and risk. Schedule the migration during a low-activity period to reduce the impact on users. Create a detailed runbook that outlines each step of the cutover process, including database backup, upgrade execution, validation checks, and go-live criteria. Define clear go/no-go criteria based on the results of the validation phase. If any critical issues are found, trigger the rollback plan. Communicate the cutover schedule and expected downtime to all stakeholders. Ensure that support teams are available to address any issues that arise during the cutover.
Develop a robust rollback plan that allows you to revert to the previous version if the migration fails. This plan should include steps for restoring the database from a backup, reverting code changes, and validating the system. Test the rollback plan in the staging environment to ensure it works as expected. Document the rollback procedures and train the support team on how to execute them. Having a tested rollback plan reduces the risk of prolonged downtime and data loss.
After the migration is complete, monitor the system closely for any issues that may not have been caught during testing. Track user feedback and error logs to identify any UI inconsistencies or functional problems. Address any issues promptly to maintain user confidence. Continue to monitor system performance and stability for several weeks after the migration. Use this period to fine-tune the system and optimize performance. Document any lessons learned and update the migration playbook for future upgrades.
Provide training and support to users to help them adapt to any UI changes. If the migration resulted in minor UI adjustments, communicate these changes clearly to users. Offer training sessions or documentation to help users navigate the new interface. Monitor user adoption metrics to identify any areas where additional support is needed. Ensuring user adoption is critical for the long-term success of the migration.
Identify and mitigate risks associated with the migration. Key risks include data loss, broken customizations, integration failures, and user adoption challenges. Mitigate these risks by conducting thorough testing, creating a detailed rollback plan, and providing user support. Use risk assessment tools to prioritize risks and allocate resources accordingly. Regularly review the risk register and update mitigation strategies as the project progresses. Effective risk management is essential for a successful migration.
Ensure data integrity by performing reconciliation checks before and after the migration. Compare key data points, such as record counts and field values, between the source and target databases. Investigate any discrepancies and resolve them before going live. Use automated scripts to perform reconciliation checks and generate reports. Data integrity is critical for maintaining trust in the system and ensuring accurate reporting.
Preserving custom field labels and UI preferences during an Odoo migration requires careful planning, thorough testing, and effective risk management. By treating UI preservation as a distinct workstream, organizations can minimize the risk of broken interfaces and ensure a smooth transition to the new version. Focus on auditing customizations, validating view definitions, and executing comprehensive testing. Use official Odoo documentation to verify compatibility and plan for manual interventions where necessary. With a structured approach, organizations can achieve a successful migration that maintains operational continuity and user satisfaction.
Common questions on this topic. Talk to our team for anything specific to your business.
Custom field labels are often stored in ir.model.fields and ir.ui.view tables. While the upgrade script attempts to preserve these, changes in the base model or XML structure can cause labels to be lost or altered. Manual verification and testing are required to ensure labels are preserved.
Use a staging environment that mirrors production. Execute the upgrade script and manually verify all custom views and field labels. Perform user acceptance testing to validate that the UI meets user expectations and that business processes function correctly.
If the base model changes, custom views that inherit from it may break. You must update the XML inheritance to match the new base model structure. Test each view to ensure it renders correctly and update the code as needed.
Yes, if you have a tested rollback plan. This involves restoring the database from a backup and reverting code changes. Ensure the rollback plan is tested in a staging environment before the production migration.
Third-party add-ons may modify field labels or views. If an add-on is not compatible with the target version, it may cause upgrade failures or label loss. Verify compatibility and update or replace incompatible add-ons before the migration.
ir.ui.view stores XML definitions for user interface views. During migration, these records are updated to match the new version's schema. If the XML structure changes, the upgrade script may fail to preserve custom views, requiring manual intervention.
Learn how professional services firms use ERP to standardize global delivery, unify financials, and scale operations without losing local flexibility.
Learn a practical framework for prioritizing ERP modules in phased migrations. Reduce risk, protect data integrity, and ensure operational continuity by assessing dependencies, business criticality, and technical complexity.
Discover how modernizing retail ERP systems enhances cross-functional decision support by unifying data, standardizing processes, and enabling real-time visibility across finance, supply chain, and operations.
Discuss your workflows, modules and deployment options with our team.
Back to resources