Skip to content
Odoo Upgrade

Managing Custom Report Dependencies During Odoo Version Upgrades

A practical guide for IT leaders and ERP consultants on how to assess, test, and migrate custom report dependencies when upgrading Odoo, ensuring data integrity and operational continuity.

10 min readSysGenPro Editorial
Managing Custom Report Dependencies During Odoo Version Upgrades

Direct Answer: How to Manage Custom Report Dependencies in Odoo Upgrades

Managing custom report dependencies during Odoo version upgrades requires a systematic approach to dependency mapping, code refactoring, and rigorous testing. The primary risk is that changes in the underlying data models, XML template structures, or Python APIs between versions can break custom reports, leading to inaccurate financial or operational data. To mitigate this, organizations must first identify all custom modules that generate reports, map their dependencies to specific database fields and API calls, and then validate these components in a staging environment that mirrors production. This process ensures that data integrity is maintained and that business users receive accurate reporting without operational downtime. The key is to treat report migration not as a simple copy-paste operation, but as a critical technical task that requires verification against the official documentation for the specific source and target versions.

Assessing Source and Target Version Compatibility

Before touching any code, the project team must establish the exact source and target Odoo versions. Compatibility is not guaranteed across all versions, and the upgrade path may require intermediate steps. For example, upgrading from Odoo 14 to Odoo 17 may involve different technical changes than upgrading from Odoo 15 to Odoo 16. It is crucial to review the official release notes and migration guides provided by the Odoo community or enterprise team for these specific versions. These documents detail changes to the ORM (Object-Relational Mapping), report rendering engines, and security frameworks. If the upgrade spans multiple major versions, the team should consider whether a direct upgrade is supported or if a phased approach is necessary. This assessment phase also involves checking the support status of any third-party add-ons that contribute to reporting functionality. If a third-party module is not yet compatible with the target version, the team must decide whether to wait for an update, replace the module, or develop a custom alternative.

Identifying Deprecated APIs and Features

A significant portion of report breakage stems from the use of deprecated Python APIs or XML tags. In older Odoo versions, certain methods for accessing data or rendering templates may have been removed or renamed in newer versions. The development team should conduct a static code analysis to identify any calls to deprecated functions. This includes checking for changes in how report actions are defined, how data is fetched for report templates, and how security rules are applied to report data. By proactively identifying these issues, the team can plan for refactoring efforts before the upgrade begins, reducing the risk of last-minute failures during the cutover window.

Mapping Report Dependencies and Data Lineage

Custom reports often rely on complex relationships between multiple database models. For instance, a sales report might depend on fields from the sales order, product, customer, and tax models. The team must create a dependency map that lists every custom report, the models it accesses, and the specific fields it uses. This map should also include any custom fields added to standard models, as these fields may be renamed or removed in the target version. Additionally, the team should document any custom SQL queries or ORM calls used within the report logic. This documentation serves as a baseline for testing and helps identify potential data lineage issues. If a report depends on a field that is no longer available in the target version, the team must determine an alternative data source or modify the report logic to calculate the value differently. This step is critical for ensuring that the business logic of the report remains intact after the upgrade.

Report NameDependent ModelsCustom Fields UsedAPI CallsRisk Level
Monthly Sales Summarysale.order, res.partnercustom_margin, tax_groupread_group, searchHigh
Inventory Valuationstock.move, product.productcost_method, valuation_layerbrowse, readMedium
Customer Agingaccount.move, res.partnerdue_date, payment_termsearch_readLow

Preparing the Staging Environment for Testing

A representative staging environment is essential for validating report dependencies. This environment should be a clone of the production database, upgraded to the target Odoo version. The team must ensure that the staging environment contains a sufficient volume of data to test performance and accuracy. This includes historical data, active records, and edge cases that might trigger specific report logic. The staging environment should also include all custom modules and third-party add-ons that are part of the reporting stack. By testing in a realistic environment, the team can identify issues that might not appear in a clean development environment. It is important to note that the staging environment should be isolated from production to prevent any accidental data modifications. The team should also configure the staging environment to match the production server specifications, including hardware resources and network latency, to ensure that performance testing is accurate.

Executing the Upgrade in Staging

Once the staging environment is prepared, the team should execute the upgrade process. This involves running the Odoo upgrade scripts, updating the database schema, and installing or updating custom modules. During this process, the team should monitor the logs for any errors or warnings related to report modules. If the upgrade fails, the team should analyze the error messages and make the necessary code adjustments. After the upgrade is complete, the team should run a full regression test suite to verify that all standard and custom reports are functioning correctly. This includes checking for data accuracy, formatting issues, and performance degradation. Any issues identified during this phase should be documented and resolved before proceeding to the next step.

Refactoring Custom Code and Templates

Based on the results of the staging tests, the development team will need to refactor custom code and XML templates to align with the target version's requirements. This may involve updating Python code to use new APIs, modifying XML templates to reflect changes in the report rendering engine, or adjusting security rules to ensure that users have the correct access to report data. The team should follow best practices for code refactoring, such as writing unit tests for new code, using version control to track changes, and documenting any significant modifications. It is also important to ensure that the refactored code is compatible with the target version's security model. For example, if the target version introduces stricter security rules, the team may need to adjust the report access rights to prevent unauthorized data access. This refactoring phase is where the bulk of the technical work is done, and it requires close collaboration between developers and business users to ensure that the reports meet the business requirements.

Validating Data Accuracy and Reconciliation

After refactoring, the team must validate the accuracy of the custom reports. This involves comparing the output of the reports in the staging environment with the expected values. The team should use a sample of historical data to generate reports and compare the results with the pre-upgrade reports. Any discrepancies should be investigated and resolved. This reconciliation process is critical for ensuring that the upgrade does not introduce data errors that could impact financial reporting or operational decision-making. The team should also test the reports with different user roles to ensure that security rules are working correctly and that users are only seeing the data they are authorized to see. This validation phase should be documented, with a clear record of the tests performed, the results obtained, and any issues that were identified and resolved.

Test CaseExpected ResultActual ResultStatusNotes
Sales Report - Q1 2023Total: $1,000,000Total: $1,000,000PassNo discrepancies
Inventory Report - Item AQty: 50Qty: 48FailCheck stock move logic
Aging Report - Customer BOverdue: $5,000Overdue: $5,000PassSecurity rules verified

Planning the Cutover and Deployment

Once the staging environment is validated, the team can plan the cutover to production. The cutover plan should include a detailed timeline, a list of tasks, and the responsible parties for each task. The team should also define go/no-go criteria, which are the conditions that must be met before the upgrade can proceed. These criteria might include the completion of all regression tests, the resolution of all critical bugs, and the approval of the business stakeholders. The cutover window should be scheduled during a period of low business activity to minimize the impact on operations. The team should also prepare a rollback plan in case the upgrade fails. This plan should include steps to restore the production database from a backup and to revert any code changes. The rollback plan should be tested in the staging environment to ensure that it is feasible and effective.

Executing the Production Upgrade

During the cutover window, the team should execute the production upgrade according to the plan. This involves taking a final backup of the production database, applying the upgrade scripts, and updating the custom modules. The team should monitor the upgrade process closely and be prepared to address any issues that arise. If the upgrade is successful, the team should perform a final validation of the custom reports in the production environment. This includes checking for data accuracy, formatting issues, and performance. The team should also communicate with the business users to inform them that the upgrade is complete and to provide any necessary training or documentation. If the upgrade fails, the team should execute the rollback plan and investigate the cause of the failure.

Post-Upgrade Stabilization and Monitoring

After the upgrade is complete, the team should enter a stabilization phase. During this phase, the team should monitor the system for any issues that may not have been identified during testing. This includes monitoring the logs for errors, tracking user feedback, and performing regular data reconciliation checks. The team should also be prepared to make any necessary adjustments to the custom reports based on user feedback. This stabilization phase is critical for ensuring that the upgrade is successful and that the business can continue to operate without disruption. The team should document any issues that are identified and resolved during this phase, and update the documentation to reflect any changes made to the custom reports. This documentation will be valuable for future upgrades and for maintaining the system over time.

Key Risks and Mitigation Strategies

  • Data Loss: Mitigated by verified backups and restore tests before cutover.
  • Broken Customizations: Mitigated by comprehensive dependency mapping and refactoring.
  • Reporting Discrepancies: Mitigated by rigorous data reconciliation and validation.
  • Performance Regressions: Mitigated by performance testing in a representative staging environment.
  • Security Misconfiguration: Mitigated by testing security rules with different user roles.

Conclusion

Managing custom report dependencies during Odoo version upgrades is a complex but manageable task. By following a systematic approach that includes dependency mapping, code refactoring, rigorous testing, and careful cutover planning, organizations can minimize the risks associated with the upgrade and ensure that their reporting capabilities remain accurate and reliable. The key is to treat the upgrade as a critical project that requires careful planning, execution, and validation. By investing time and resources in the preparation and testing phases, organizations can avoid costly errors and ensure a smooth transition to the new Odoo version. This approach not only protects the integrity of the business data but also enhances the long-term maintainability of the ERP system.

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.

01What are the most common causes of broken reports after an Odoo upgrade?

The most common causes are changes in database field names, deprecated Python APIs, and modifications to XML template structures. These changes can break the logic that custom reports rely on to fetch and display data.

02How do I identify which custom modules depend on specific report fields?

You can identify dependencies by reviewing the code of the custom modules, looking for references to specific model fields, and using static code analysis tools to map out the data lineage.

03Should I rebuild custom reports or migrate them during an Odoo upgrade?

It depends on the complexity of the report and the extent of the changes in the target version. If the changes are minor, migration is usually sufficient. If the changes are significant, rebuilding the report may be more efficient and maintainable.

04What is the recommended testing strategy for custom reports in Odoo?

The recommended strategy is to use a representative staging environment with historical data, run regression tests, and perform data reconciliation to ensure accuracy. This should be done before the production cutover.

05How do database schema changes affect custom report queries in Odoo?

Database schema changes can alter the structure of the tables that custom reports query. If a field is renamed or removed, the query will fail. The team must update the queries to reflect the new schema.

06Can I use the same report templates across different Odoo versions?

Not always. Report templates may need to be updated to reflect changes in the report rendering engine or the data models. It is best to test the templates in the target version before assuming compatibility.

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