Connected business operations. Flexible deployment.
A technical guide for CIOs and IT directors on managing the transition from XML-RPC to JSON-RPC during Odoo migrations, covering compatibility, testing, and risk mitigation.
When migrating Odoo to a newer version, the transition from XML-RPC to JSON-RPC is a critical technical hurdle that requires careful planning. While older Odoo versions relied heavily on XML-RPC for remote procedure calls, modern versions have standardized on JSON-RPC for better performance, readability, and security. The recommended approach is to audit all existing integrations, custom modules, and third-party add-ons to identify dependencies on XML-RPC. You must then refactor these components to use JSON-RPC endpoints, ensuring that authentication methods, payload structures, and error handling are updated accordingly. This transition is essential because XML-RPC support may be deprecated or removed in future releases, posing a significant risk to system stability. The main risks to control include broken integrations, data synchronization failures, and security vulnerabilities if authentication tokens are not properly migrated. By proactively testing these changes in a staging environment and validating data integrity, you can minimize downtime and ensure a smooth migration.
To effectively manage the transition, it is crucial to understand the fundamental differences between the two protocols. XML-RPC uses XML for encoding method calls and parameters, which can be verbose and slower to parse. JSON-RPC, on the other hand, uses JSON, which is lighter and more efficient for modern web applications. In Odoo, the shift to JSON-RPC also involves changes in how requests are structured and how responses are returned. For example, JSON-RPC typically includes a unique request ID for tracking, which is not always present in XML-RPC. Additionally, the authentication mechanism may differ, with JSON-RPC often using session-based authentication or API keys, whereas XML-RPC might rely on database credentials directly. Understanding these differences helps in identifying where custom code or third-party integrations may break during the migration.
The serialization format is a key area of change. XML-RPC encodes data in a nested XML structure, which can be complex to generate and parse. JSON-RPC uses a flat JSON structure, which is easier to work with in most programming languages. When migrating, you must ensure that your integration scripts correctly map the data fields from the XML format to the JSON format. This includes handling data types, such as dates, booleans, and arrays, which may be represented differently in the two formats. For instance, dates in XML-RPC might be encoded as strings in a specific format, while JSON-RPC may use ISO 8601 standard. Failing to account for these differences can lead to data corruption or parsing errors during the migration.
Authentication is another critical aspect of the API transition. In older Odoo versions, XML-RPC often used direct database credentials for authentication, which is less secure. Modern JSON-RPC implementations typically use session-based authentication or API keys, which provide better security and flexibility. During the migration, you must update your integration scripts to use the new authentication method. This involves generating new API keys or session tokens and updating the configuration files of your integrations. Additionally, you should review the security settings of your Odoo instance to ensure that the new API endpoints are properly secured and that only authorized users or systems can access them. This step is crucial to prevent unauthorized access and data breaches during and after the migration.
The first step in managing the API transition is to conduct a comprehensive audit of all existing integrations and custom modules. This involves identifying all components that use XML-RPC to communicate with the Odoo system. You should create an inventory of these components, including their purpose, frequency of use, and criticality to business operations. For each component, you should document the specific XML-RPC methods being called, the data being exchanged, and the authentication method used. This inventory will serve as the basis for your migration plan, helping you prioritize which components to migrate first and which can be deferred. It is also important to identify any third-party add-ons that rely on XML-RPC, as these may require updates from the vendor or custom modifications to support JSON-RPC.
During the audit, you should also identify any deprecated APIs or endpoints that are no longer supported in the target Odoo version. Odoo regularly updates its API, and some older endpoints may be removed or changed in newer versions. You should consult the official Odoo documentation for the target version to verify which APIs are supported and which are deprecated. For any deprecated APIs, you must plan to replace them with their modern equivalents. This may involve rewriting parts of your integration scripts or using new endpoints that provide the same functionality. It is important to test these changes thoroughly in a staging environment to ensure that they work as expected and do not introduce new issues.
Third-party add-ons are a common source of compatibility issues during Odoo migrations. Many add-ons are developed for specific Odoo versions and may not support the latest API changes. You should contact the vendors of your third-party add-ons to inquire about their support for the target Odoo version and the JSON-RPC API. Some vendors may provide updated versions of their add-ons that support the new API, while others may require custom modifications. If a vendor does not support the new API, you may need to consider alternative add-ons or develop custom solutions to replace the functionality. This assessment is crucial to avoid unexpected issues during the migration and to ensure that all business processes remain functional.
Once you have identified the components that need to be migrated, the next step is to refactor the code to use JSON-RPC. This involves updating the integration scripts to use the new endpoints, authentication methods, and payload structures. You should start with the most critical integrations and work your way down to less critical ones. For each integration, you should update the code to use the JSON-RPC library or client that is compatible with the target Odoo version. This may involve changing the way requests are made, how responses are parsed, and how errors are handled. It is important to test each refactored integration in a staging environment before deploying it to production. This ensures that the changes work as expected and do not introduce new issues.
A key part of the refactoring process is updating the authentication and session management. In JSON-RPC, authentication is typically handled through session tokens or API keys, which must be managed securely. You should update your integration scripts to generate and store these tokens securely, and to refresh them as needed. Additionally, you should implement proper error handling for authentication failures, such as expired tokens or invalid keys. This ensures that your integrations can recover from authentication issues without causing data loss or downtime. It is also important to review the security settings of your Odoo instance to ensure that the new authentication method is properly configured and that only authorized users or systems can access the API.
Another critical aspect of the refactoring process is handling data type mappings and transformations. As mentioned earlier, XML-RPC and JSON-RPC may represent data types differently. You must ensure that your integration scripts correctly map the data types from the XML format to the JSON format. This includes handling dates, booleans, arrays, and other complex data types. You should also implement validation checks to ensure that the data being sent and received is in the correct format. This helps to prevent data corruption and parsing errors during the migration. Additionally, you should test these mappings thoroughly in a staging environment to ensure that they work as expected and do not introduce new issues.
Before deploying the changes to production, you must test the API transition in a staging environment that mirrors your production setup. This involves setting up a test Odoo instance with the target version and migrating a representative subset of your data to it. You should then run your refactored integrations against this test instance and verify that they work as expected. This includes testing data synchronization, error handling, and authentication. You should also test edge cases, such as large data volumes, concurrent requests, and network failures, to ensure that your integrations are robust and can handle real-world scenarios. The results of these tests should be documented and reviewed by the project team to identify any issues that need to be addressed before deployment.
A key part of the testing process is validating data integrity and consistency. You should compare the data being sent and received by your integrations to ensure that it is accurate and complete. This includes checking for missing fields, incorrect data types, and formatting errors. You should also verify that the data is being stored correctly in the Odoo database and that it can be retrieved and used by other systems. This validation is crucial to ensure that the migration does not introduce data corruption or loss, which can have serious business implications. You should use automated testing tools to perform these checks and to generate reports that can be reviewed by the project team.
In addition to functional testing, you should perform performance benchmarking and load testing to ensure that your integrations can handle the expected volume of traffic. This involves simulating real-world usage patterns and measuring the response times, throughput, and resource utilization of your integrations. You should compare the performance of the new JSON-RPC integrations to the old XML-RPC integrations to ensure that there is no significant degradation. If you identify any performance issues, you should optimize your code or infrastructure to address them. This may involve caching data, optimizing database queries, or scaling your infrastructure. Performance testing is crucial to ensure that your integrations can handle peak loads and that they do not become a bottleneck for your business operations.
Once you have completed the testing and validation, you can plan the cutover and deployment of the new API. This involves scheduling a maintenance window during which you will switch from XML-RPC to JSON-RPC. You should communicate this window to all stakeholders and ensure that all necessary backups are taken before the cutover. During the cutover, you should deploy the refactored integrations to production and monitor them closely for any issues. You should have a rollback plan in place in case the new integrations fail or cause unexpected issues. This plan should include steps to revert to the old XML-RPC integrations and to restore any data that may have been affected. The cutover should be executed by a team of experienced engineers who are familiar with the Odoo system and the integration scripts.
Before the cutover, you should define clear go/no-go criteria that must be met before proceeding with the deployment. These criteria should include the results of the testing and validation, the availability of backups, and the readiness of the support team. If any of the criteria are not met, you should postpone the cutover and address the issues. This helps to minimize the risk of a failed deployment and ensures that the migration is executed smoothly. The go/no-go decision should be made by a senior member of the project team who has the authority to make the call. This ensures that the decision is based on a thorough review of the risks and benefits.
If the new integrations fail during the cutover, you should execute the rollback plan immediately. This involves reverting to the old XML-RPC integrations and restoring any data that may have been affected. You should monitor the system closely after the rollback to ensure that it is stable and that no further issues arise. You should also document the cause of the failure and the steps taken to resolve it. This documentation will be useful for future migrations and for improving the robustness of your integrations. The rollback plan should be tested in a staging environment before the cutover to ensure that it works as expected and that the team is familiar with the steps involved.
After the cutover, you should monitor the new integrations closely to ensure that they are working as expected. This involves checking the logs for any errors or warnings, monitoring the performance metrics, and verifying that data is being synchronized correctly. You should also gather feedback from users and stakeholders to identify any issues that may not have been caught during testing. This feedback should be used to make any necessary adjustments to the integrations or the Odoo configuration. The stabilization period should last for at least a few weeks, during which you should continue to monitor the system and address any issues that arise. This helps to ensure that the migration is successful and that the new API is stable and reliable.
To ensure the long-term stability of the new API, you should implement continuous monitoring and alerting. This involves setting up dashboards that display key performance indicators, such as response times, error rates, and data synchronization status. You should also configure alerts that notify the support team when any of these metrics exceed predefined thresholds. This helps to detect and address issues before they impact business operations. Additionally, you should regularly review the logs and metrics to identify any trends or patterns that may indicate potential issues. This proactive approach helps to maintain the stability and reliability of your integrations over time.
Finally, you should document the changes made during the migration and transfer the knowledge to the support team. This includes updating the technical documentation, creating runbooks for common issues, and training the support team on the new API. This ensures that the team is equipped to handle any issues that may arise in the future and that the knowledge is not lost when team members change. Documentation is crucial for maintaining the long-term stability and maintainability of your Odoo system and its integrations. It also helps to reduce the risk of errors and downtime by providing clear guidance on how to manage and troubleshoot the system.
Common questions on this topic. Talk to our team for anything specific to your business.
Support for XML-RPC varies by version. While it may still be available in some recent releases, it is generally deprecated in favor of JSON-RPC. You must verify the specific support status in the official documentation for your target version.
Set up a staging environment with the target Odoo version. Use API testing tools like Postman or cURL to send sample requests to the JSON-RPC endpoints. Validate the responses, error handling, and authentication to ensure compatibility.
The main differences include the serialization format (XML vs. JSON), payload structure, authentication methods, and performance. JSON-RPC is generally lighter, faster, and more secure than XML-RPC.
In some cases, you can run both protocols simultaneously if the Odoo version supports it. This allows for a phased migration where you can switch integrations one by one. However, you must verify this capability in the official documentation.
Custom modules that use XML-RPC will need to be refactored to use JSON-RPC. This involves updating the code to use the new endpoints, authentication methods, and payload structures. You must test these changes thoroughly in a staging environment.
Contact the vendors of your third-party integrations to inquire about their support for the target Odoo version and JSON-RPC. If they provide updated versions, use them. If not, you may need to develop custom solutions or find alternative integrations.
Learn how professional services firms can modernize ERP systems to enforce standardized approvals, tighten billing controls, and improve revenue forecasting through process-driven architecture.
A practical guide for CIOs and ERP consultants on migrating project and timesheet data, covering profiling, mapping, validation, and cutover strategies to ensure financial accuracy and operational continuity.
Learn how to architect a construction ERP that links procurement controls directly to project delivery, ensuring cost visibility, compliance, and operational efficiency without fragmented data.
Discuss your workflows, modules and deployment options with our team.
Back to resources