Skip to content
Odoo Migration

Technical Checklist for Migrating Custom Code Between Odoo Versions

A practical, step-by-step technical checklist for migrating custom Odoo modules between versions. Covers dependency analysis, API changes, testing, and risk mitigation for CIOs and IT leaders.

10 min readSysGenPro Editorial
Technical Checklist for Migrating Custom Code Between Odoo Versions

Technical Checklist for Migrating Custom Code Between Odoo Versions

Migrating custom code between Odoo versions is a high-risk technical process that requires a structured, phased approach to ensure business continuity and data integrity. The primary risk lies in the incompatibility of custom modules with the new version's API, ORM changes, and database schema modifications. A successful migration depends on a comprehensive dependency analysis, rigorous testing in a representative staging environment, and a clearly defined rollback strategy. This checklist provides a practical framework for CIOs, CTOs, and ERP consultants to manage the technical execution of custom code migration, focusing on preparation, execution, validation, and stabilization. By systematically addressing deprecated APIs, view changes, and security rules, organizations can minimize downtime and prevent operational disruptions during the upgrade.

Phase 1: Preparation and Dependency Analysis

Before touching any code, the foundation of the migration must be established through thorough analysis. This phase involves identifying all custom modules, their dependencies on core Odoo modules, and their reliance on third-party add-ons. It is critical to map out the exact source and target versions, as compatibility is not guaranteed across all version jumps. For instance, moving from Odoo 14 to Odoo 16 involves significant changes in the ORM and API that differ from a minor version upgrade. The team must verify the support status of all third-party modules against the target version using the vendor's official documentation. If a third-party module is not supported, a decision must be made to replace it, wait for an update, or rewrite the functionality in-house.

Inventory and Dependency Mapping

Create a complete inventory of all custom modules, including their version, author, and last modification date. Use dependency analysis tools to map out the relationships between custom modules and core Odoo modules. Identify any circular dependencies or modules that depend on deprecated core features. This inventory serves as the baseline for the migration plan and helps in estimating the effort required for refactoring. Modules with high dependency on core internals are higher risk and should be prioritized for early testing.

Environment Setup and Version Verification

Set up a staging environment that mirrors the production environment as closely as possible, including the database size, user count, and integration endpoints. Install the target Odoo version in this environment. Verify that the Python version, PostgreSQL version, and other system dependencies meet the requirements for the target Odoo version. It is essential to confirm that the target version is supported by the vendor and that all necessary security patches are applied. This environment will be used for all subsequent testing and validation activities.

Phase 2: Code Refactoring and API Adaptation

The core of the migration involves adapting the custom code to the new Odoo version's API and ORM. This phase requires a detailed review of the codebase to identify deprecated methods, changed field types, and modified view structures. The Odoo ORM has evolved significantly over the years, with changes in how records are accessed, how queries are constructed, and how security is enforced. Developers must refactor the code to use the new API patterns, ensuring that the logic remains intact while conforming to the new standards. This is not a simple find-and-replace operation; it requires a deep understanding of the changes in the target version.

Handling Deprecated APIs and ORM Changes

Review the official Odoo release notes for the target version to identify all deprecated APIs and ORM changes. Common changes include the removal of certain methods, changes in the behavior of `search()` and `browse()` methods, and modifications to the inheritance mechanism. Refactor the code to replace deprecated methods with their new equivalents. Pay special attention to changes in the `fields` module, as field types and behaviors may have changed. Ensure that all custom fields are correctly defined and that their relationships with other models are maintained.

View and Security Rule Migration

XML views and security rules are often the most fragile parts of custom modules. View inheritance may break if the parent view structure has changed in the new version. Review all XML files to ensure that the inherited views are still valid and that the anchors used for inheritance exist in the new version. Security rules must be updated to reflect any changes in the model structure or field names. Test the security rules thoroughly to ensure that users have the correct access rights and that no data is exposed unintentionally. This step is critical for maintaining data integrity and compliance.

Phase 3: Testing and Validation

Testing is the most critical phase of the migration, as it is where defects are identified and resolved before they impact production. A comprehensive testing strategy should include unit tests, integration tests, and end-to-end business process tests. Unit tests should cover the core logic of the custom modules, ensuring that the refactored code behaves as expected. Integration tests should verify that the custom modules work correctly with the core Odoo modules and other third-party add-ons. End-to-end tests should simulate real-world business scenarios to ensure that the entire workflow functions correctly.

Automated and Manual Testing Strategies

Implement automated testing frameworks to run unit and integration tests repeatedly, ensuring that the code remains stable as changes are made. Use tools like Odoo's built-in testing framework or external libraries to automate the execution of tests. In addition to automated tests, perform manual testing to cover scenarios that are difficult to automate, such as complex user interactions or edge cases. Document all test cases and their results, and track defects in a bug tracking system. Prioritize defects based on their impact on business operations and their severity.

Performance and Security Validation

Performance testing is essential to ensure that the new version does not introduce performance regressions. Run load tests to simulate peak usage and measure the response time and throughput of the system. Compare the results with the baseline performance of the old version to identify any significant changes. Security validation should include a review of the security rules, a scan for vulnerabilities, and a test of the authentication and authorization mechanisms. Ensure that the system is protected against common attacks and that data is encrypted in transit and at rest. This step is crucial for maintaining the security posture of the ERP system.

Phase 4: Deployment and Cutover

The deployment phase involves moving the migrated custom code and the upgraded database to the production environment. This is a high-risk activity that requires careful planning and execution. A detailed cutover plan should be developed, outlining the steps, responsibilities, and timelines for the migration. The plan should include a freeze window during which no changes are made to the production environment, a final data load, and a go/no-go decision point. The cutover should be performed during a period of low business activity to minimize the impact on operations.

Cutover Plan and Rollback Strategy

Develop a detailed cutover plan that includes a step-by-step runbook, clear ownership of each task, and communication protocols. Define the go/no-go criteria, which should be based on the results of the testing phase and the status of any remaining defects. Establish a rollback strategy that allows the system to be reverted to the old version if the migration fails. The rollback plan should include a backup of the production database and the old custom code, and it should be tested in the staging environment before the cutover. Ensure that the rollback process is well-documented and that the team is trained on how to execute it.

Execution and Monitoring

Execute the cutover plan according to the runbook, monitoring the system closely for any errors or anomalies. Use monitoring tools to track the performance and health of the system during and after the cutover. Communicate the status of the migration to stakeholders in real-time, and be prepared to make quick decisions if issues arise. If the go/no-go criteria are not met, execute the rollback plan and investigate the root cause of the failure. If the migration is successful, begin the post-migration stabilization phase.

Phase 5: Post-Migration Stabilization

The post-migration stabilization phase is critical for ensuring that the system operates smoothly in the production environment. This phase involves monitoring the system for any issues that may not have been detected during testing, providing support to users, and making any necessary adjustments. It is also an opportunity to gather feedback from users and identify areas for improvement. The stabilization phase should continue for a defined period, typically several weeks, to ensure that the system is stable and that all issues have been resolved.

Monitoring and Support

Implement a robust monitoring system to track the performance, availability, and health of the ERP system. Set up alerts for any anomalies, such as increased error rates, slow response times, or database issues. Provide dedicated support to users during the stabilization phase, addressing any questions or issues they may have. Document all issues and their resolutions, and use this information to improve the system and the migration process for future upgrades. Regularly review the monitoring data to identify trends and potential problems.

Documentation and Knowledge Transfer

Update the documentation to reflect the changes made during the migration, including any new features, deprecated features, and changes in the API. Provide training to the development team on the new version's API and best practices, ensuring that they are equipped to maintain and extend the system in the future. Conduct a post-mortem review of the migration process, identifying what went well and what could be improved. Use the lessons learned to refine the migration checklist and improve the process for future upgrades. This step is essential for building organizational knowledge and reducing the risk of future migrations.

Risk Management and Decision Criteria

Effective risk management is essential for a successful Odoo migration. The primary risks include data loss, downtime, broken customizations, unsupported dependencies, and integration failures. To mitigate these risks, organizations must implement a comprehensive risk management plan that includes risk identification, assessment, and mitigation. Decision criteria should be established for each phase of the migration, ensuring that the project can proceed only if the risks are within acceptable limits. For example, the go/no-go decision for the cutover should be based on the results of the testing phase and the status of any remaining defects.

Risk CategoryDescriptionMitigation StrategyResponsible Role
Data LossLoss of data during the migration processPerform full backups before migration, test restore procedures, and validate data integrity after migrationDatabase Administrator
DowntimeExtended downtime during the cutoverPlan the cutover during low-activity periods, optimize the migration script, and have a rollback plan readyProject Manager
Broken CustomizationsCustom modules fail to work correctly in the new versionPerform thorough testing in a staging environment, refactor code to use new APIs, and validate security rulesLead Developer
Unsupported DependenciesThird-party modules are not compatible with the new versionVerify compatibility with vendors, replace unsupported modules, or rewrite functionality in-houseERP Consultant
Integration FailuresIntegrations with external systems fail after the upgradeTest integrations in the staging environment, update API endpoints and authentication, and monitor integration healthIntegration Specialist

Conclusion

Migrating custom code between Odoo versions is a complex but manageable process when approached with a structured, phased methodology. By following this technical checklist, organizations can minimize the risks associated with the migration and ensure a smooth transition to the new version. The key to success lies in thorough preparation, rigorous testing, and effective risk management. It is essential to verify all compatibility claims against the vendor's official documentation for the exact source and target versions, as compatibility is not guaranteed. By investing in a well-planned migration, organizations can unlock the benefits of the new Odoo version, including improved performance, new features, and enhanced security, while maintaining operational continuity and data integrity.

Written by
SysGenPro Editorial

SysGenPro Editorial

Platform & solutions team

Practical guidance on ERP, AI automation, cloud deployment and enterprise transformation from the SysGenPro team.

Share this article

Frequently asked questions

Common questions on this topic. Talk to our team for anything specific to your business.

01Can I upgrade Odoo without migrating custom code?

No, custom code must be migrated and adapted to the new version's API and ORM. Failing to do so will result in broken modules and potential system instability.

02What are the most common errors in Odoo custom code migration?

Common errors include using deprecated API methods, incorrect view inheritance, and security rule mismatches. These can lead to runtime errors and data access issues.

03How long does it take to migrate custom Odoo modules?

The duration depends on the complexity and number of custom modules. Simple modules may take a few days, while complex ones can take several weeks. A thorough dependency analysis and testing phase are essential.

04Do I need to rewrite all custom code for a new Odoo version?

Not necessarily, but significant refactoring is often required to adapt to API and ORM changes. The extent of rewriting depends on how closely the custom code relies on deprecated features.

05How do I test custom modules before the final upgrade?

Use a representative staging environment to run unit, integration, and end-to-end tests. Simulate real-world business scenarios and validate security rules and performance.

06What is the rollback plan if the custom code fails after upgrade?

The rollback plan should include a backup of the production database and the old custom code. Test the rollback procedure in the staging environment before the cutover to ensure it works.

Continue learning
View all articles
Explore the platform

Where to go next

Browse the knowledge hub

See how SysGenPro fits your business

Discuss your workflows, modules and deployment options with our team.

Back to resources