diff --git a/content/administration/maintain/odoo_online.rst b/content/administration/maintain/odoo_online.rst index 9d76cd480c..f3926e85c2 100644 --- a/content/administration/maintain/odoo_online.rst +++ b/content/administration/maintain/odoo_online.rst @@ -30,8 +30,8 @@ Upgrade Trigger a database upgrade. .. seealso:: - For more information about the upgrade process, check out the :doc:`Odoo Online upgrade - documentation <../upgrade/odoo_online>`. + For more information about the upgrade process, check out the :ref:`Odoo Online upgrade + documentation `. .. _odoo_online/duplicate: diff --git a/content/administration/odoo_sh/getting_started/branches.rst b/content/administration/odoo_sh/getting_started/branches.rst index 6e566acb5e..84152bca6b 100644 --- a/content/administration/odoo_sh/getting_started/branches.rst +++ b/content/administration/odoo_sh/getting_started/branches.rst @@ -295,7 +295,7 @@ Upgrade Available for production and staging branches for valid projects. .. seealso:: - :doc:`Upgrade - Odoo.sh <../../upgrade/odoo_sh>` + :doc:`Upgrade documentation <../../upgrade>` .. _odoosh-gettingstarted-branches-tabs-settings: diff --git a/content/administration/upgrade.rst b/content/administration/upgrade.rst index 3695b98e77..7e1d3c3ec4 100644 --- a/content/administration/upgrade.rst +++ b/content/administration/upgrade.rst @@ -1,5 +1,3 @@ -:show-content: - .. |assistance-contact| replace:: If you need Odoo assistance on this matter, please get in touch with your Odoo Account Manager or our `Sales department`_. @@ -9,218 +7,372 @@ Upgrade ======= -.. toctree:: - :titlesonly: +An upgrade is the process of moving your database from an older version to a newer :doc:`supported +version ` (e.g., Odoo 14.0 to Odoo 16.0). Frequently upgrading is +essential as each version comes with new and improved features, bug fixes, and security patches. + +.. _upgrade_faq/rolling_release: + +.. spoiler:: Automatic upgrades: Odoo Online's Rolling Release process + + The Rolling Release process allows Odoo Online customers to upgrade their database directly from + a message prompt sent to the database administrator as soon as a new version is released. The + invitation to upgrade is only sent if no issues are detected during the automatic tests. - upgrade/odoo_online - upgrade/odoo_sh - upgrade/on_premise - upgrade/faq + .. image:: upgrade/rr-upgrade-message.png + :alt: The upgrade message prompt on the top right of the database -An upgrade is switching to a newer version of Odoo (e.g., Odoo 14.0 to Odoo 15.0). + It is strongly recommended to manually :ref:`test the upgrade first `. + Clicking :guilabel:`I want to test first` redirects to `the database manager + `_, where it is possible to request an upgraded test database + and check it for any discrepancies. + + It is **not** recommended to click :guilabel:`Upgrade Now` without testing first, as it + immediately triggers the live production database upgrade. + + If the Rolling Release process detects an issue with the upgrade, it will be deactivated until + the issue is resolved. An upgrade does not cover: -* Changing :ref:`editions ` (i.e., Community to Enterprise edition) -* Switching :ref:`hosting type ` (i.e., On-Premise to Odoo Online - or Odoo.sh) -* Migration from another ERP to Odoo + - Downgrading to a previous version of Odoo + - :doc:`Changing editions ` (e.g., from Community to Enterprise) + - :doc:`Switching hosting type ` (e.g., from on-premise + to Odoo Online). + - Migrating from another ERP to Odoo -.. note:: |assistance-contact| +.. warning:: + If your database contains a **custom module**, you must :doc:`upgrade its source code first + ` to the new version of Odoo **before upgrading**. -.. seealso:: - - :ref:`upgrade/sla` - -.. _upgrade/process-workflow: - -Process workflow -================ - -The upgrade process in a nutshell: - -#. You create a test upgrade request. -#. Odoo processes the request automatically by running the database through an upgrade script, which - takes between 20 and 120 minutes. -#. Odoo delivers a test database. -#. You test your database for possible discrepancies (see :ref:`upgrade/test-guidance`). -#. If there are any discrepancies, you report them to the Upgrade support team via the help portal - (see :ref:`upgrade/test-assistance`). -#. We fix the issues and send you a new test database. -#. Once you have completed the testing and are happy with the result, you decide on a date and time - when you stop users from accessing Odoo, freeze all data entries, and create an upgrade request - for the production upgrade. -#. Odoo delivers the production database through the automated process. -#. You restore it in your Production environment a few short hours later and continue working on the - newly upgraded database (this is done automatically on Odoo Online). -.. seealso:: - - :doc:`Upgrade process for Odoo Online ` - - :doc:`Upgrade process for Odoo.sh ` - - :doc:`Upgrade process for On-Premise ` +Upgrading in a nutshell +----------------------- -.. _upgrade/testing-phase: +#. Request an upgraded test database (see :ref:`obtaining an upgraded test database + `). -Testing -======= +#. Thoroughly test the upgraded database (see :ref:`testing the new version of the database + `). -This phase allows you to review an upgraded version of your database without affecting your -production database in any way. We suggest that you run the test upgrade process at least once, but -you can do it as many times as you need (one at a time). +#. Report any issue encountered during the testing to Odoo via the `support page + `__. -Once you receive your upgraded test database, check that all data, processes, and functionality are -still correct and working as expected. +#. (If applicable) : upgrade the source code of your custom module to be compatible with the new + version of Odoo. -If you do find discrepancies, :ref:`report your issues ` and :ref:`request -a new test database ` when the reported issues are fixed in the upgrade -script. +#. Once all issues are resolved and you are confident that the upgraded database can be used as + your main database without any issue, plan the upgrade of your production database. -If you do not find any discrepancies, you can move on to the upgrade of your production database. +#. Request the upgraded for the production database, rendering it unavailable for the time it takes + to complete the process (see :ref:`upgrading the production database `). -.. important:: - A test database is only intended for testing and remains completely unrelated to your present or - future production database. Any data you add, or changes you make, will not be reflected in your - upgraded production database. +#. Report any issue encountered during the upgrade to Odoo via the `support page + `__. + +.. Once the page for developers is published, put this at 4) +.. (see :ref:`upgrading customizations `). + +.. _upgrade/request-test-database: + +Obtaining an upgraded test database +----------------------------------- + +The `Upgrade page `_ is the main platform for requesting an upgraded +database. However, depending on the hosting type, you can upgrade from the command line +(on-premise), the `Odoo Online database manager `_, or your `Odoo.sh +project `_. .. note:: - Test databases are neutered and features are disabled to prevent them from having an impact on - the production database: + The Upgrade platform follows the same `Privacy Policy `_ as the + other Odoo.com services. Visit the `General Data Protection Regulation page + `_ to learn more about how Odoo handles your data and privacy. + +.. tabs:: + + .. group-tab:: Odoo Online + + Odoo Online databases can be manually upgraded via the `database manager + `_. + + The database manager displays all databases associated with the user's account. Databases + not on the most recent version of Odoo display an arrow in a circle icon next to their name, + indicating that they can be upgraded. + + .. image:: upgrade/databases-page.png + :alt: The database manager with an upgrade button next to the name of a database. + + Click the **arrow in a circle** icon to start the upgrade process. In the popup, fill in: + + - The **version** of Odoo you want to upgrade to, usually the latest version + - The **email** address that should receive the link to the upgraded database + - The :guilabel:`Purpose` of the upgrade, which is automatically set to :guilabel:`Test` for + your first upgrade request + + .. image:: upgrade/upgrade-popup.png + :alt: The "Upgrade your database" popup. + + The :guilabel:`Upgrade in progress` tag is displayed next to the database name until + completion. Once the process succeeds, an email containing a link to the upgraded test + database is sent to the address provided. The database can also be accessed from the database + manager by clicking the dropdown arrow before the database name. + + .. image:: upgrade/access-upgraded-db.png + :alt: Clicking the menu arrow displays the upgraded test database. - #. The serial number of the database is modified (to prevent it from sending information as if it - was the production database). - #. The :ref:`base URL of the database ` is reset to - ``http://localhost:8069`` and the email domain to ``localhost``. - #. Scheduled actions are disabled (the calendar synchronization, the bank statement - synchronization, the planned automated actions, the fetching of incoming mail servers, etc.). - #. Outgoing mail servers are disabled by archiving the existing ones and adding a - fake/non-working one. - #. Payment providers and delivery carriers are reset to test environment. - #. Accounting localization Electronic Data Interchange (EDI) services are disabled. - #. A system parameter is set to tell the database has been neutered. + .. group-tab:: Odoo.sh -.. _upgrade/test-db-request: + Odoo.sh is integrated with the upgrade platform to simplify the upgrade process. -Request a test database -======================= + .. note:: + The :guilabel:`Upgrade` tab is available for projects with a valid subscription. -Follow the instructions available per hosting type on the `website form -`_ and select *Testing* purpose. + .. image:: upgrade/odoo-sh-staging.png + :alt: Odoo.sh project and tabs -.. image:: upgrade/test-purpose.png - :align: center - :alt: Selection of the "Testing" purpose in the upgrade form on Odoo + The **latest production daily automatic backup** is then sent to the `upgrade platform + `_. -.. _upgrade/test-guidance: + Once the upgrade platform is done upgrading the backup and uploading it on the branch, it is + put in a **special mode**: each time a **commit is pushed** on the branch, a **restore + operation** of the upgraded backup and an **update of all the custom modules** occur. This + allows you to test your custom modules on an pristine copy of the upgraded database. The log + file of the upgrade process can be found in your newly upgraded staging build by going to + :file:`~/logs/upgrade.log`. -Test guidance -============= + .. note:: + In databases where custom modules are installed, their source code + must be up-to-date with the target version of Odoo before the upgrade + can be performed. If there are none, the "update on commit" mode is + skipped, the upgraded database is build as soon as it is transfered from the upgrade + platform and the upgrade mode is exited. -Every business and organization has its own operational needs and has to test its specific Odoo -database individually. We recommend you look at `the test scenario -`_ for further -information. + Check out the :doc:`upgrade for developers' + documentation ` for more information. In + addition, if a module is not needed after an upgrade, :ref:`you can + remove customizations `. -.. todo:: change link "test scenario" once the related doc is published + .. group-tab:: On-premise -.. _upgrade/test-assistance: + The standard upgrade process can be initiated by entering the following command line on the + machine where the database is hosted: -Assistance ----------- + .. code-block:: console -If you encounter an issue in the **test database**, please get in touch with Odoo Upgrade Support -via the `Odoo Support page `_. + $ python <(curl -s https://upgrade.odoo.com/upgrade) test -d -t -Under the *Ticket Description* section, select *An issue related to my upgrade* ticket type. + The following command can be used to display the general help and the main commands: - .. image:: upgrade/test-assistance.png - :align: center - :alt: Selection of "An issue related to my upgrade" as Ticket Type in the support form on Odoo + .. code-block:: console - .. warning:: - If you choose another *Ticket Description* type, the request will be redirected to another - team. This will slow down the processing and response time. + $ python <(curl -s https://upgrade.odoo.com/upgrade) --help -Please provide as much detail as you can (i.e., videos and screenshots to illustrate your issue). -This will avoid clarifying questions and speed up the resolution process significantly. + An upgraded test database can also be requested via the `Upgrade page + `_. + + .. note:: + - For security reasons, only the person who submitted the upgrade request can download it. + - For storage reasons, the database's copy is submitted without a filestore to the upgrade + server. Therefore, the upgraded database does not contain the production filestore. + - Before restoring the upgraded database, its filestore must be merged with the production + filestore to be able to perform tests in the same conditions as it would be in the new + version. + - The upgraded database contains: + + - A `dump.sql` file containing the upgraded database + - A `filestore` folder containing files extracted from in-database records into + attachments (if there are any) and new standard Odoo files from the targeted Odoo + version (e.g., new images, icons, payment provider's logos, etc.). + This is the folder that should be merged with the production filestore + in order to get the full upgraded filestore. .. note:: - * The purpose of the test phase is not to correct existing data or configurations in your + You can request multiple test databases if you wish to test an upgrade more than once. + +.. _upgrade/upgrade_report: + +.. note:: + When an upgrade request is completed, an upgrade report is attached to the successful upgrade + email and it becomes available in the Discuss app for users who are part of the "Administration + / Settings" group. This report provides important information about the changes introduced by + the new version. + +.. _upgrade/test_your_db: + +Testing the new version of the database +--------------------------------------- + +It is essential to spend some time testing the upgraded test database to ensure that you are not +stuck in your day-to-day activities by a change in views, behavior, or an error message once the +upgrade goes live. + +.. note:: + Test databases are neutralized, and some features are disabled to prevent them from impacting the + production database: + + #. Scheduled actions are disabled. + #. Outgoing mail servers are disabled by archiving the existing ones and adding a fake one. + #. Payment providers and delivery carriers are reset to the test environment. + +Testing as many of your business flows as possible is strongly recommended to ensure they are +working correctly and to get more familiar with the new version. + +.. admonition:: Basic test checklist + + - Are there views that are deactivated in your test database but active in your production + database? + - Are your usual views still displayed correctly? + - Are your reports (invoice, sales order, etc.) correctly generated? + - Are your website pages working correctly? + - Are you able to create and modify records? (sales orders, invoices, purchases, users, contacts, + companies, etc.) + - Are there any issues with your mail templates? + - Are there any issues with saved translations? + - Are your search filters still present? + - Can you export your data? + +.. spoiler:: Example of end-to-end testing + + - Checking a random product in your product catalog and comparing its test and production data to + verify everything is the same (product category, selling price, cost price, vendor, accounts, + routes, etc.). + - Buying this product (Purchase app). + - Confirming the reception of this product (Inventory app). + - Checking if the route to receive this product is the same in your production database + (Inventory app). + - Selling this product (Sales app) to a random customer. + - Opening your customer database (Contacts app), selecting a customer (or company), and checking + its data. + - Shipping this product (Inventory app). + - Checking if the route to ship this product is the same as in your production database + (Inventory app). + - Validating a customer invoice (Invoicing or Accounting app). + - Crediting the invoice (issuing a credit note) and checking if it behaves as in your production database. - * |assistance-contact| + - Checking your reports' results (Accounting app). + - Randomly checking your taxes, currencies, bank accounts, and fiscal year (Accounting app). + - Making an online order (Website apps) from the product selection in your shop until the + checkout process and checking if everything behaves as in your production database. + + This list is **not** exhaustive. Extend the example to your other apps based on your use of Odoo. + +If you face an issue while testing your upgraded test database, you can request the assistance of +Odoo via the `support page `__ by selecting the option +related to testing the upgrade. In any case, it is essential to report any +problem encountered during the testing to fix it before upgrading your production database. -.. _upgrade/steps-production: +You might encounter significant differences with standard views, features, fields, and models during +testing. Those changes cannot be reverted on a case-by-case basis. However, if a change introduced +by a new version breaks a customization, it is the responsibility of the maintainer of your custom +module to make it compatible with the new version of Odoo. -The production launch -===================== +.. tip:: + Do not forget to test: -The production upgrade request is when you decide to upgrade your current database with all your -production data (invoices, VAT returns, inventories, current orders) to a new version of your -choice. + - Integrations with external software (EDI, APIs, etc.) + - Workflows between different apps (online sales with eCommerce, converting a lead all the way to + a sales order, delivery of products, etc.) + - Data exports + - Automated actions + - Server actions in the action menu on form views, as well as by selecting multiple records on + list views -After your :ref:`tests ` are completed to your satisfaction, submit the -request to upgrade your production database via our `website form `_. -Select *Production* purpose. +.. _upgrade/upgrade-prod: + +Upgrading the production database +--------------------------------- + +Once the :ref:`tests ` are completed and you are confident that the upgraded +database can be used as your main database without any issue, it is time to plan the go-live day. It +can be planned in coordination with Odoo's upgrade support analysts, reachable via the `support page +`__. + +Your production database will be unavailable during its upgrade. Therefore, we recommend to plan +the upgrade at a time when the use of the database is minimal. + +As the standard upgrade scripts and your database are constantly evolving, it is also recommended +to frequently request a new upgraded test database to ensure that the upgrade process is +still successful, especially if it takes a long time to finish. Fully rehearsing the upgrade +process the day before upgrading the production database is also recommended. .. important:: - Going into production without first testing may lead to: + - Going into production without first testing may lead to: - - business interruptions (e.g., no longer having the possibility to validate an action) - - poor customer experiences (e.g., an eCommerce website that does not work correctly) + - Users failing to adjust to the changes and new features + - Business interruptions (e.g., no longer having the possibility to validate an action) + - Poor customer experience (e.g., an eCommerce website that does not work correctly) -.. _upgrade/production-assistance: +The process of upgrading a production database is similar to upgrading a test database with a few +exceptions. -Assistance ----------- +.. tabs:: -If you encounter issues or problems in the **production database**, please get in touch with **Odoo -Support**: + .. group-tab:: Odoo Online -#. Connect to our `Odoo Support page `_. -#. Under the *Ticket Description* section, select the appropriate type related to your issue but - **do not select** the option *An issue related to my upgrade*. + The process is similar to :ref:`obtaining an upgraded test database + `, except for the purpose option, which must be set to + :guilabel:`Production` instead of :guilabel:`Test`. - .. note:: - After upgrading to production, the support will be provided by the Support team instead of the - Upgrade team. + .. warning:: + Once the upgrade is requested, the database will be unavailable until the upgrade is + finished. Once the process is completed, it is impossible to revert to the previous + version. -#. Please provide as much detail as you can (i.e., videos and screenshots to illustrate your issue). - This will avoid clarifying questions and speed up the resolution process significantly. + .. group-tab:: Odoo.sh - .. warning:: - If you choose *An issue related to my upgrade* as ticket type, the request will be redirected - to another team than the support one and will slow down the processing and response time. + The process is similar to :ref:`obtaining an upgraded test database + ` on the :guilabel:`Production` branch. -.. _upgrade/assistance: + .. image:: upgrade/odoo-sh-prod.png + :alt: View from the upgrade tab -Help -==== + The process is **triggered as soon as a new commit is made** on the branch. This + allows the upgrade process to be synchronized with the deployment of the custom modules' + upgraded source code. + If there are no custom modules, the upgrade process is triggered immediately. -.. _upgrade/contact: + .. important:: + The database is unavailable throughout the process. If anything goes wrong, the platform + automatically reverts the upgrade, as it would be for a regular update. In case of success, + a backup of the database before the upgrade is created. -Contact our upgrade service support ------------------------------------ + The update of your custom modules must be successful to complete the entire upgrade process. + Make sure the status of your staging upgrade is :guilabel:`successful` before trying it in + production. + .. TODOUPG : once the page for developers is published, uncomment + .. More information on how to upgrade your custom modules can be found in the :ref:`upgrading customizations documentation `. -Should you have any more questions about the upgrade, do not hesitate to send a message to `Odoo -Upgrade Team `_. We will be happy to answer it as soon as possible. + .. group-tab:: On-premise -.. _upgrade/supported-versions: + The command to upgrade a database to production is similar to the one of upgrading a test + database except for the argument `test`, which must be replaced by `production`: -Supported versions ------------------- + .. code-block:: console -Please note that Odoo provides support and bug fixing only for the three last major versions of -Odoo. + $ python <(curl -s https://upgrade.odoo.com/upgrade) production -d -t -This is a factor to take into consideration before upgrading. If you are on an older version, we -suggest you to prefer the most recent version to benefit from longer support (before having to -upgrade again). + An upgraded production database can also be requested via the `Upgrade page + `_. + + + Once the database is uploaded, any modification to your production database will **not** be + present on your upgraded database. This is why we recommend not using it during the upgrade + process. + + .. important:: + When requesting an upgraded database for production purposes, the copy is submitted without + a filestore. Therefore, the upgraded database filestore must be merged with the production + filestore before deploying the new version. + +In case of an issue with your production database, you can request the assistance of Odoo via the +`support page `__ by selecting the option related to +the upgrade in production. -.. seealso:: - :doc:`maintain/supported_versions` .. _upgrade/sla: Service-level agreement (SLA) -============================= +----------------------------- With Odoo Enterprise, upgrading a database to the most recent version of Odoo is **free**, including any support required to rectify potential discrepancies in the upgraded database. @@ -230,7 +382,7 @@ Information about the upgrade services included in the Enterprise Licence is ava upgrade services you can expect. Upgrade services covered by the SLA ------------------------------------ +=================================== Databases hosted on Odoo's cloud platforms (Odoo Online and Odoo.sh) or self-hosted (On-Premise) can benefit from upgrade services at all times for: @@ -245,7 +397,7 @@ Upgrade services are limited to the technical conversion and adaptation of a dat modules and data) to make it compatible with the version targeted by the upgrade. Upgrade services not covered by the SLA ---------------------------------------- +======================================= The following upgrade-related services are **not** included: @@ -259,6 +411,5 @@ The following upgrade-related services are **not** included: .. note:: |assistance-contact| .. seealso:: - - :doc:`Upgrade FAQ ` - :doc:`Odoo.sh documentation ` - :doc:`Supported Odoo versions ` diff --git a/content/administration/upgrade/access-upgraded-db.png b/content/administration/upgrade/access-upgraded-db.png new file mode 100644 index 0000000000..a6dfcc5184 Binary files /dev/null and b/content/administration/upgrade/access-upgraded-db.png differ diff --git a/content/administration/upgrade/databases-page.png b/content/administration/upgrade/databases-page.png new file mode 100644 index 0000000000..1105fd1d3e Binary files /dev/null and b/content/administration/upgrade/databases-page.png differ diff --git a/content/administration/upgrade/faq.rst b/content/administration/upgrade/faq.rst deleted file mode 100644 index f4fba7a735..0000000000 --- a/content/administration/upgrade/faq.rst +++ /dev/null @@ -1,228 +0,0 @@ -.. |assistance-contact| replace:: - If you need Odoo assistance on this matter, please get in touch with your Odoo Account Manager or - our `Sales department`_. -.. _Sales department: mailto:sales@odoo.com - -=== -FAQ -=== - -.. _upgrade-faq/why: - -Why upgrade -=========== - -* You benefit from the latest features of the :ref:`new major version - ` released by Odoo. -* If you are in an :ref:`unsupported version `, you get a new version - with support. - -.. _upgrade-faq/when: - -When to upgrade -=============== - -Whenever you want. You can make your upgrade request as soon as a new version is released or when -your version turns unsupported, and you still wish to enjoy support. - -.. _upgrade-faq/availability: - -Availability of the new version -=============================== - -As soon as Odoo announces the release of a new major version, you can create a test upgrade request -to try the latest version. Please note that at this point, the upgrade scripts will only have been -tested with demo data. Please report any issue you might encounter while testing via the `Odoo -Support page `_ and make sure to be happy with your test version before -requesting the upgrade of your database in production. - -.. _upgrade-faq/duration: - -Duration of the upgrade -======================= - -It is impossible to give time estimates for every upgrade request. - -In general, the "smaller" the database, the quickest the upgrade request is completed. A single-user -database that uses only CRM will be processed faster than a multi-company, multi-user database that -uses Accounting, Sales, Purchase, and Manufacturing. - -You can expect the time it takes for the platform to upgrade the test database to be similar to the -production upgrade. - -.. _upgrade-faq/project: - -Duration of the upgrade project -------------------------------- - -It depends on the user involvement (the time spent on testing, reporting problems, etc.) and the -issues encountered that might need to be addressed by our technical team. - -So, in a nutshell, what can impact your upgrade lead time? - -* Source & targeted versions -* Installed apps -* Volume of data -* Amount of customization (models, fields, methods, workflows, reports, website, etc.) -* Installation of new apps or configuration changes after the start of the test phase -* User commitment - -.. _upgrade-faq/custom-modules: - -Upgrade of the custom modules -============================= - -As stated in our :doc:`/legal/terms/enterprise`, section :ref:`charges_standard`, this optional -service is subject to additional fees. - -Depending on your situation, the custom code could be upgraded by our services, by one of our -partners, or you can do it yourself. - -.. note:: |assistance-contact| - -.. _upgrade-faq/upgrade-or-migration: - -Upgrade or Migration -==================== - -An upgrade is switching to a newer version of Odoo, while a migration reflects the change of -:ref:`editions ` or change of :ref:`hosting type -`. - -.. note:: |assistance-contact| - -.. _upgrade-faq/editions-change: - -Editions change (from Community to Enterprise) -============================================== - -The upgrade always returns an Enterprise edition of Odoo, whether the database you sent was a -community or enterprise edition. It is required to have an enterprise subscription to upgrade. - - .. note:: - If you need assistance on this matter, please contact us via the `Odoo Support page - `_. - -.. seealso:: - - `Editions `_ - -.. _upgrade-faq/hosting-types-switch: - -Switching the hosting types (On-premise vs. Odoo Online vs. Odoo.sh) -==================================================================== - -An upgrade does not cover a change of `Hosting types `_. - -Open the following link to get :doc:`more information about how to change your hosting type -<../maintain/hosting_changes>`. - -.. note:: |assistance-contact| - -.. _upgrade-faq/upgrade-report: - -The Upgrade Report -================== - -When an upgrade request completes successfully (test or production), you receive an email -notification about it that includes an 'Upgrade Report'. This report is also sent to you via the -Discuss app. It contains valuable information regarding changes that occurred during the upgrade. -While it serves as a guide to possible issues to look out for, it is not an exhaustive list. It -remains imperative that you test the upgraded database thoroughly and report any discrepancies you -might find, before you decide to upgrade your production database. - -.. _upgrade-faq/custom-views: - -Custom views -============ - -During the upgrade, some custom views might get disabled for technical reasons. Therefore they might -have to be fixed after the upgrade. The :ref:`Upgrade Report ` that is -generated after the upgrade is available in the Discuss app, and lists all the custom views that -might be impacted by this. - -.. _upgrade-faq/release-notes: - -Release Notes by version -======================== - -Open our `Release Note `_ page to get a summary of the new -features and improvements made in each version. - -How long is my test available for -================================= - -An Odoo Online test database is available for one month by default. We can extend this trial period -upon request. For Odoo.sh or on-premise, there is no restriction. - -How many tests to perform before upgrading to production? -========================================================= - -As many as needed. When you are comfortable with the database, run a last test upgrade 48 hours -before requesting your production upgrade and test your workflows one last time. - -How to/Where to report upgrade issues? -====================================== - -If you encounter issues during the upgrade process, please contact the Odoo Support through the -`Odoo Support page `_. - -- To report an issue discovered during the testing phase, please select **An issue related to my - upgrade (test phase)**. -- To report an issue discovered post-upgrade, please select **An issue related to my upgrade - (production)**. - -Upgrading to production -======================= - -Once you have completed testing and are happy with the result, you decide on a date and time when -you stop users from accessing Odoo, freeze all data entries, and create an upgrade request for the -production upgrade. - -How is my data handled in the Upgrade Platform? -=============================================== - -The Odoo Upgrade platform uses the same Privacy Policy as the rest of Odoo.com services. - -Your data is hosted on servers that follow our security guidelines, namely: - -- SSL - All web connections to client instances are protected with 256-bit SSL encryption - (HTTPS with a 2048-bit modulus SSL certificate), and running behind Grade A SSL stacks. All our - certificate chains are using SHA-2 already. -- Safe System - Our servers are running recent Linux distribution with up-to-date security patches, - with firewall and intrusion countermeasures (not disclosed for obvious reasons). - -Servers are located at the same locations as our Cloud providers with the following services: - -- Restricted perimeter, physically accessed by authorized data center employees only -- Physical access control with security badges or biometrical security -- Security cameras monitoring the data center locations 24/7 -- Security personnel on-site 24/7 - -The uploaded and migrated databases uploaded to the Upgrade platform are kept for up to 3 months and -are permanently deleted following that period. - -You can learn more about privacy and data handling at Odoo by visiting our `General Data Protection -Regulation page `_. - -Rolling Release (applicable to Odoo Online databases) -===================================================== - -This feature allows customers to upgrade their database directly from a message prompt sent to the -database administrator as soon as the new version is released. Odoo first tests the upgrade to the -next version. The rolling release upgrade option is displayed if the automated tests are successful. -The message offers two options: - -#. To 'Upgrade Now', which immediately triggers the upgrade of your live production database. - -#. To take you to your `database manager `_ where you can - `request an upgraded test database `_ and check the upgraded - test database for any discrepancies. - -When you choose to proceed with the production upgrade directly, make sure all users have saved -their work and are logged out. The upgrade takes approximately 15 minutes. During this time your -database is unreachable. If you notice any problem after the upgrade, please report it via the `Odoo -Support page `_. - -.. note:: - If you are using the Website or Studio app, we recommend you always do a test upgrade before - upgrading your production instance. diff --git a/content/administration/upgrade/odoo-sh-prod.png b/content/administration/upgrade/odoo-sh-prod.png new file mode 100644 index 0000000000..1ce8eb1baa Binary files /dev/null and b/content/administration/upgrade/odoo-sh-prod.png differ diff --git a/content/administration/upgrade/odoo-sh-staging.png b/content/administration/upgrade/odoo-sh-staging.png new file mode 100644 index 0000000000..4dbe83d876 Binary files /dev/null and b/content/administration/upgrade/odoo-sh-staging.png differ diff --git a/content/administration/upgrade/odoo_online.rst b/content/administration/upgrade/odoo_online.rst deleted file mode 100644 index 383c4175d9..0000000000 --- a/content/administration/upgrade/odoo_online.rst +++ /dev/null @@ -1,92 +0,0 @@ -=========== -Odoo Online -=========== - -Odoo databases can be manually upgraded directly from the main Odoo website. To upgrade an Odoo -database, navigate to the `database manager `_ page and sign in. - -The database manager page displays all of the Odoo databases associated with the user's account. Any -databases that are not already on the most recent version of Odoo display an **arrow in a circle** -icon next to the database name, indicating that the database can be upgraded. - -.. image:: odoo_online/databases-page.png - :align: center - :alt: The database manager page with an upgrade button next to the name of a database. - -.. important:: - - If the database's version is **lower** than the latest major release: the database must be - upgraded within two months. After these two months, an automatic upgrade is initiated. - - If the database's version is **equal** to or **higher** than the latest major release: - you can disregard the invitation to upgrade, as the database probably would not benefit from - new features every two months. - -If a database is *not* on the latest online version, its administrator should receive an invitation -to upgrade on the database's dashboard, displayed as an **arrow in a circle**. - -.. image:: odoo_online/database-notification.png - :alt: Invitation to upgrade on the database dashboard. - -.. note:: - Versions that are not supported anymore become deprecated and must be updated to avoid - security issues. It is recommended to initiate the upgrade yourself and not wait for the - automatic upgrade, as the former method allows you to request a test upgrade of the database to - check for any discrepancies. - -Test database -============= - -Click on the **arrow in a circle** icon to start the upgrade process. On the :guilabel:`Upgrade your -database` pop-up, select the version of Odoo that the platform will be upgraded to. In the -:guilabel:`Email to notify` field, enter an email address that will receive email notifications -about the database upgrade. - -There is also a :guilabel:`Purpose` section on the pop-up that is used to specify the reason for the -upgrade. However, at this stage of the process, the only selectable option is :guilabel:`Test`, as -Odoo requires users to create a test copy of the upgraded database before converting the actual -database. - -.. image:: odoo_online/upgrade-pop-up.png - :align: center - :alt: The "Upgrade your database" pop-up. - -After filling out the form, click the :guilabel:`Upgrade` button. The pop-up disappears and the -database being upgraded shows a red :guilabel:`Upgrade in progress` tag next to its name. An email -confirming that the upgrade is in progress is also sent to the email address specified on the -pop-up. - -.. image:: odoo_online/upgrade-in-progress.png - :align: center - :alt: The "Upgrade in progress" tag next to the database name. - -Once the upgrade is complete, a new test database appears on the `database manager -`_ page. To access the test database, click the drop-down arrow -(:guilabel:`⯆`) to the left of the main database's name. Doing so makes the test version appear -below it. Finally, click the green :guilabel:`Connect` button on the right side of the test -version's row to go to the database. - -.. image:: odoo_online/test-database.png - :align: center - :alt: A test database on the database manager page. - -Except for being on the newer version of Odoo, the test database is an exact copy of the one being -upgraded. It is important to do extensive testing in this database to ensure that the upgrade has -not altered or corrupted any data, and that all workflows still proceed as expected. - -Production database -=================== - -After confirming the integrity of the new version, return to the `database manager -`_ page. Once again, click on the **arrow in a circle** icon next -to the database being upgraded. The :guilabel:`Upgrade your database` pop-up appears as before, -except that there is now a :guilabel:`Production` option under the :guilabel:`Purpose` section. - -Select the :guilabel:`Production` option and then click :guilabel:`Upgrade` to begin the upgrade -process. As before, a notification email is sent to the email address provided and a red -:guilabel:`Upgrade in progress` tag appears next to the name of the database. - -The production database is then taken offline and will be upgraded automatically. The time it takes -to upgrade the production database should be similar to the time that was necessary to upgrade the -test database. Make sure to inform database users of the scheduled downtime. - -After the upgrade is finished, the :guilabel:`Upgrade in progress` tag disappears and the database -is upgraded to the version specified. diff --git a/content/administration/upgrade/odoo_online/database-notification.png b/content/administration/upgrade/odoo_online/database-notification.png deleted file mode 100644 index ab63c66133..0000000000 Binary files a/content/administration/upgrade/odoo_online/database-notification.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_online/databases-page.png b/content/administration/upgrade/odoo_online/databases-page.png deleted file mode 100644 index 590e8c57d0..0000000000 Binary files a/content/administration/upgrade/odoo_online/databases-page.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_online/test-database.png b/content/administration/upgrade/odoo_online/test-database.png deleted file mode 100644 index a9ce2bf83e..0000000000 Binary files a/content/administration/upgrade/odoo_online/test-database.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_online/upgrade-in-progress.png b/content/administration/upgrade/odoo_online/upgrade-in-progress.png deleted file mode 100644 index 6835d15e05..0000000000 Binary files a/content/administration/upgrade/odoo_online/upgrade-in-progress.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_online/upgrade-pop-up.png b/content/administration/upgrade/odoo_online/upgrade-pop-up.png deleted file mode 100644 index 5ce6544224..0000000000 Binary files a/content/administration/upgrade/odoo_online/upgrade-pop-up.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_sh.rst b/content/administration/upgrade/odoo_sh.rst deleted file mode 100644 index b1d63c3dd0..0000000000 --- a/content/administration/upgrade/odoo_sh.rst +++ /dev/null @@ -1,132 +0,0 @@ -======= -Odoo.sh -======= - -.. _upgrade/odoo_sh/overview: - -Overview -======== - -Odoo.sh is integrated with the upgrade platform to make the upgrade process easier. - -.. note:: - The :guilabel:`Upgrade` tab is available in the branches view. It is only available for valid - projects with a valid production build. - -.. image:: odoo_sh/odoo-sh-menu.png - :align: center - :alt: Click on the upgrade menu - -The suggested upgrade steps on Odoo.sh are: - -#. On a :guilabel:`Development` branch, upgrade your custom modules to keep them compatible with the - new version and thoroughly **test them**. -#. Switch that branch to the :guilabel:`Staging` branch, **upgrade** the last daily production - backup and **test it**. Write upgrade scripts if necessary. -#. Trigger the production upgrade from your :guilabel:`Production` branch and sit tight. - -.. seealso:: - - :doc:`../../administration/upgrade` - - :doc:`Upgrade FAQ <../upgrade/faq>` - - :doc:`Introduction to Odoo.sh <../odoo_sh/overview/introduction>` - -.. _upgrade/odoo_sh/custom-modules: - -Upgrade your custom modules -=========================== - -The first step is to upgrade your custom modules to keep them compatible with the new version. Fork -your :guilabel:`Production` branch in the :guilabel:`Development` stage, then go to the settings of -your :guilabel:`Development` branch and select the Odoo version you target. If needed, modify your -code to be compatible with the new version. Make sure to **test** your features are still working -correctly. - -.. note:: - Depending on your contract, the upgrade of your custom modules can be done by yourself, by your - Partner or by Odoo (if you hold a subscription including maintenance of customizations). - -.. _upgrade/odoo_sh/testing-phase: - -Upgrade your database on a staging branch -========================================= - -Take the upgraded development branch and drag & drop it to :guilabel:`Staging`. - -Go to the :guilabel:`Upgrade` tab and select the :guilabel:`target version`. Then, click on -:guilabel:`Test Upgrade`. - -.. image:: odoo_sh/odoo-sh-staging.png - :align: center - :alt: Odoo.sh project and tabs - -The **latest production daily automatic backup** is sent to the -`upgrade platform `_ to start the upgrade test process. - -.. note:: - You can follow the upgrade process by going to the :guilabel:`Upgrade` menu of your - :guilabel:`Production` branch. - -When the upgraded backup is ready on the `upgrade platform `_, it is -automatically downloaded back to your project. - -The branch is now in a **special mode**: each time a **commit is pushed** on the branch, a -**restore operation** of the upgraded backup occurs, and an **update of all the custom modules** -happens. This allows you to quickly iterate on your custom modules upgrade scripts. The log file of -the upgrade process can be found at :file:`~/logs/upgrade.log` in your newly upgraded staging build. - -.. note:: - - The **special upgrade mode** is automatically closed after 30 days. - - It may happen that custom modules are no longer needed after an upgrade. Custom modules in the - upgraded database are set to be updated. If the modules are missing in the code, the update - fails, thus failing the whole process. An empty module with a manifest and possibly some custom - upgrade script are necessary to clean up the database. The complete removal of the module has - to be handled afterwards. - -Functionally test your upgraded database -======================================== - -Now that the test upgraded database is available on your staging branch, **thoroughly test it** and -make sure everything runs as it's supposed to. Once you are satisfied with the result, you are ready -to upgrade your production database. - -Production upgrade -================== - -Once you are happy with your testing, you can start the process on the :guilabel:`Production` -branch. - -On your :guilabel:`Production` branch, go to the :guilabel:`Upgrade` tab, select the -:guilabel:`targeted version` and click on the :guilabel:`start Upgrade` button. - -.. image:: odoo_sh/odoo-sh-prod.png - :align: center - :alt: View from the upgrade tab - -The actual process is **triggered as soon as you push a new commit** in your branch. Make sure you -are pushing code that is compatible with the new version. For example by merging the code from your -upgraded staging branch. - -.. note:: - You can see the progress of the upgrade by going to the :guilabel:`Upgrade` tab of the main - branch. - -.. image:: odoo_sh/odoo-sh-progress.png - :align: center - :alt: View showing the progress of the upgrade - -.. important:: - Your database is unavailable throughout the process. - -.. note:: - If anything goes wrong, the platform automatically reverts the upgrade, the same as it would be - for a regular update. In case of success, a backup is always made. - -The update of your custom modules must be successful to complete the entire upgrade process. Make -sure the status of your staging upgrade is :guilabel:`successful` before trying it in production. - -.. note:: - It may happen that custom modules are no longer needed after an upgrade. Custom modules in the - upgraded database are set to be updated. If the modules are missing in the code, the update - fails, thus failing the whole process. An empty module with a manifest and possibly some custom - upgrade script are necessary to clean up the database. The complete removal of the module has to - be handled afterwards. diff --git a/content/administration/upgrade/odoo_sh/odoo-sh-menu.png b/content/administration/upgrade/odoo_sh/odoo-sh-menu.png deleted file mode 100644 index 85d5a1c406..0000000000 Binary files a/content/administration/upgrade/odoo_sh/odoo-sh-menu.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_sh/odoo-sh-prod.png b/content/administration/upgrade/odoo_sh/odoo-sh-prod.png deleted file mode 100644 index b7379fb5a5..0000000000 Binary files a/content/administration/upgrade/odoo_sh/odoo-sh-prod.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_sh/odoo-sh-progress.png b/content/administration/upgrade/odoo_sh/odoo-sh-progress.png deleted file mode 100644 index 97bcc65b2b..0000000000 Binary files a/content/administration/upgrade/odoo_sh/odoo-sh-progress.png and /dev/null differ diff --git a/content/administration/upgrade/odoo_sh/odoo-sh-staging.png b/content/administration/upgrade/odoo_sh/odoo-sh-staging.png deleted file mode 100644 index d84c8b4703..0000000000 Binary files a/content/administration/upgrade/odoo_sh/odoo-sh-staging.png and /dev/null differ diff --git a/content/administration/upgrade/on_premise.rst b/content/administration/upgrade/on_premise.rst deleted file mode 100644 index 65d1487a28..0000000000 --- a/content/administration/upgrade/on_premise.rst +++ /dev/null @@ -1,76 +0,0 @@ -========== -On-Premise -========== - -Test upgrade request -==================== - -There are two ways to create your upgrade request. - -Upgrade request via command line --------------------------------- - -For technically-advanced users and partners, the upgrade process can be initiated via the following -command line on the server where the database is hosted: - -:command:`python <(curl -s https://upgrade.odoo.com/upgrade) test -d -t -` - -The above command creates the database dump, sends it to the upgrade platform, and initiates the -automated upgrade process. During the upgrade, you can follow the live logs on your screen. -Once the upgrade process is completed successfully, the upgraded database is restored onto the -server (as a duplicate test database). - -Upgrade request via the Odoo Upgrade Portal -------------------------------------------- - -#. Download a recent copy of your database and select the option :guilabel:`pg_dump custom format - (without filestore)`. -#. Upload this dump file at https://upgrade.odoo.com and select *Testing* as the aim. - Odoo performs the automated upgrade process. Once it is completed, you receive an email with a - link to download the upgrade database dump file. -#. Import the upgraded database into your on-premise environment and manually test all processes and - workflows. - -.. note:: - - For security reasons, only the person who submitted the upgrade request is able to download it. - - Any problem found during testing should be reported via the `helpdesk - `_. - - For storage reasons, the copy of your database is submitted without a filestore to the upgrade - server. Therefore, the upgraded database does not contain the production filestore. - - Before restoring the upgraded database, its filestore must be merged with the production - filestore to be able to perform tests in the same conditions as it would be in the new version. - - The upgraded database contains: - - - A `dump.sql` file containing the upgraded database. - - A `filestore` folder containing files that were extracted from in-database records into - attachments (if there are any) and new standard Odoo files from the targeted Odoo version - (like new images, icons, payment provider's logos, etc.). This is the folder that should be - merged with the production filestore in order to get the full upgraded filestore. - -Upgrade your production database -================================ - -Once you have completed the testing successfully, you can proceed to upgrade your live database in -production. Download your upgraded database from the link in the email and import it onto your live -environment. - -.. important:: - - Same as in the test phase, when requesting an upgrade for production purposes, the copy of your - database is submitted without a filestore. - - Therefore, the upgraded database filestore must be merged with the production filestore before - deploying the new version. - -Custom modules (if applicable) -============================== - -The upgrade of a database that contains custom modules is a two-step process. - -#. The standard upgrade is done when your upgrade request is completed. -#. Your custom modules also need to be upgraded to keep them compatible with the new version. - -Depending on your contract, the upgrade of your custom modules can be done - -#. by yourself. -#. by your Partner. -#. by Odoo (if you hold a subscription to 'Maintenance of Customizations'). diff --git a/content/administration/upgrade/rr-upgrade-message.png b/content/administration/upgrade/rr-upgrade-message.png new file mode 100644 index 0000000000..7ac2facc49 Binary files /dev/null and b/content/administration/upgrade/rr-upgrade-message.png differ diff --git a/content/administration/upgrade/test-assistance.png b/content/administration/upgrade/test-assistance.png deleted file mode 100644 index 2fac7cf86e..0000000000 Binary files a/content/administration/upgrade/test-assistance.png and /dev/null differ diff --git a/content/administration/upgrade/test-purpose.png b/content/administration/upgrade/test-purpose.png deleted file mode 100644 index 4a8f9fd46b..0000000000 Binary files a/content/administration/upgrade/test-purpose.png and /dev/null differ diff --git a/content/administration/upgrade/upgrade-popup.png b/content/administration/upgrade/upgrade-popup.png new file mode 100644 index 0000000000..8be275bef6 Binary files /dev/null and b/content/administration/upgrade/upgrade-popup.png differ diff --git a/content/applications/general/users/manage_users.rst b/content/applications/general/users/manage_users.rst index b4a702fcca..f387921e57 100644 --- a/content/applications/general/users/manage_users.rst +++ b/content/applications/general/users/manage_users.rst @@ -34,6 +34,10 @@ Go to :menuselection:`Settings --> Manage Users` and click on *Create*. When you are done editing the page and have *Saved* it, an invitation email is automatically sent to the user. The user must click on it to accept the invitation and create a login. +.. important:: + Modifying the main user with `id=2` (*administrator*) is discouraged. Instead, leave all the + access rights on the administrator user and create another one. + .. image:: manage_users/invitation-email.png :align: center :alt: View of a user’s form with a notification that the invitation email has been sent in Odoo diff --git a/content/developer/reference.rst b/content/developer/reference.rst index 96ab9eb529..4e53b3cce7 100644 --- a/content/developer/reference.rst +++ b/content/developer/reference.rst @@ -14,3 +14,4 @@ Reference reference/cli reference/external_api reference/extract_api + reference/upgrade diff --git a/content/developer/reference/cli.rst b/content/developer/reference/cli.rst index 214f879e24..33c0ed98ba 100644 --- a/content/developer/reference/cli.rst +++ b/content/developer/reference/cli.rst @@ -651,9 +651,8 @@ Here is a sample file: Shell ===== -Odoo command-line also allows to launch odoo as a python console environment. -This enables direct interaction with the :ref:`orm ` and its functionalities. - +The Odoo command line also allows launching Odoo as a Python console environment, enabling direct +interaction with the :ref:`orm ` and its functionalities. .. code-block:: console @@ -661,8 +660,32 @@ This enables direct interaction with the :ref:`orm ` and its func .. option:: --shell-interface (ipython|ptpython|bpython|python) - Specify a preferred REPL to use in shell mode. + Specify a preferred REPL to use in shell mode. This shell is started with the `env` variable + already initialized to be able to access the ORM and other Odoo modules. + +.. example:: Example of shell usage + + Adding an exclamation mark to all contacts' names: + + .. code-block:: python + + In [1]: records = env["res.partner"].search([]) + In [2]: records + Out[2]: res.partner(14, 26, 33, 21, 10) + + In [3]: for partner in records: + ...: partner.name = "%s !" % partner.name + ...: + + In [4]: env.cr.commit() + + .. important:: + By default, the shell is running in transaction mode. This means that any change made to the + database is rolled back when exiting the shell. To commit changes, use `env.cr.commit()`. + +.. seealso:: + :ref:`Environment documentation ` .. _reference/cmdline/scaffold: diff --git a/content/developer/reference/upgrade.rst b/content/developer/reference/upgrade.rst new file mode 100644 index 0000000000..d581d20ce6 --- /dev/null +++ b/content/developer/reference/upgrade.rst @@ -0,0 +1,427 @@ +====================== +Upgrade for developers +====================== + +The upgrade process +=================== + +TODOUPG re-analyze to see if necessary + +#. Exporting the database to a file +#. Uploading the file to the upgrade server +#. Running a series of :ref:`standard migration scripts ` to + upgrade standard modules +#. Downloading the upgraded database +#. Importing the file into a database +#. (*If applicable*) :ref:`Custom migration scripts ` + developed by the maintainer of your custom modules are ran to upgrade them. + +.. _reference/upgrade/migration-scripts: + +Migration scripts +================= + +A migration script is a Python file containing a function called `migrate`, which the upgrade +process invokes at the appropriate time. Typically, this function executes one or multiple SQL +queries and can also access Odoo's ORM, as well as the `upgrade-util package +`__. + +.. example:: + Between Odoo 15 and Odoo 16, the `sale.subscription` model was merged into the `sale.order` model + in the standard code of Odoo. This change required the development of standard migration scripts + to transfer rows from the `sale_subscription` PSQL table to the `sale_order` table, ensuring no + data is lost. Then, once the standard data has been migrated, the table `sale_subscription` gets + removed by another standard migration script. + +.. seealso:: + `DjangoProject.com documentation: Migrations + `_ + +.. spoiler:: Two migration scripts: adding "!" at the end of partners' names + + .. code-block:: python + + import logging + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + cr.execute( + """ + UPDATE res_partner + SET name = name || '!' + """ + ) + _logger.info("Updated %s partners", cr.rowcount) + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + env = util.env(cr) + + partners = env["res.partner"].search([]) + for partner in partners: + partner.name += "!" + + _logger.info("Updated %s partners", len(partners)) + +.. spoiler:: Migration script: fixing a Studio view + + .. code-block:: python + + import logging + from odoo.upgrade import util + + _logger = logging.getLogger(__name__) + + + def migrate(cr, version): + with util.edit_view(cr, "studio_customization.odoo_studio_project__e2f15f1a-2bdb-4003-a36e-ed731a1b9fae") as arch: + node = arch.xpath("""//xpath[@expr="//group[field[@name='activity_summary']]"]""")[0] + node.attrib["expr"] = "//field[@name='activity_summary']" + +.. note:: + Only Odoo's employees can modify migration scripts in the standard upgrade process on the upgrade + server. Third-party developers can develop custom migration scripts for their custom modules. + +Positioning a migration script +------------------------------ + +Migration scripts are executed depending on their module, the version of Odoo, the version of the +module, the phase of the migration script, and its name. The path of the file should follow this +template: :file:`/migrations/./{pre|post|end}-*.py` + +- :file:`` corresponds to the folder name of a module. For example, :file:`account` for + the Accounting module, or :file:`sale_subscription` for the Subscriptions module. +- :file:`` corresponds to the major version of Odoo (e.g., :file:`16.0` for Odoo 16). +- :file:`` corresponds to the minor version of the module (e.g., :file:`1.2` for the + `Accounting module in Odoo 16 `_). +- :file:`` corresponds to :ref:`the phase of the migration script + `. +- :file:`*.py` corresponds to the name of the migration script. Its name will determine the order in + which it is executed for that module, version, and phase. + +.. _upgrade/migration-scripts-phases: + +Phases of migration scripts +--------------------------- + +The upgrade process consists of three phases for each version of each module: + + #. The pre-phase, before the module and its dependencies are loaded. The ORM is not available at + that time. + #. The post-phase, after the module and its dependencies are loaded and upgraded. + #. The end-phase, after all modules have been upgraded for that version. + +.. note:: + If you are unsure which phase to use, use the end-phase. + +Migration scripts are grouped according to the first part of their filenames into the corresponding +phase. So, for example, a file named :file:`pre-upgrade_data.py` will execute before +:file:`post-do_upgrade_data.py` regardless of their lexical order. In each phase, files are then +executed according to their lexical order. + +.. spoiler:: Execution order of example scripts for one module in one version + + - :file:`pre-zzz.py` + - :file:`pre-~do_something.py` + - :file:`post--testing.py` + - :file:`post-01-zzz.py` + - :file:`post-migrate.py` + - :file:`post-other_module.py` + - :file:`post-~migrate.py` + - :file:`end--migrate.py` + - :file:`end-01-migrate.py` + - :file:`end-aaa.py` + - :file:`end-~migrate.py` + +.. _upgrade/upgrading_customizations: + +Upgrading customizations +======================== + +The source code of custom modules maintained by third parties must be upgraded to be compatible with +each new version of Odoo. This usually requires a static analysis of the code to find all the +references of deprecated elements. However, it can also be done by installing the module and fixing +the errors that occur during the installation. + +Information on the changes between versions can be found in the `release notes +`_ and the :ref:`upgrade report `. + +.. seealso:: + - :ref:`reference/views` + - :ref:`reference/fields` + - :ref:`reference/orm/models` + +.. _upgrade/comparing_customizations: + +Comparing customizations to the new version +------------------------------------------- + +As many new features are added with each new version, some customizations may become obsolete when +equivalent features become part of the standard version of Odoo. + +Therefore, exploring the new features and comparing them with your customizations is recommended. +Removing unnecessary customizations reduces the work needed to maintain and upgrade your database. + +.. _upgrade/remove_customizations: + +Removing customizations +----------------------- + +Customizations that have become redundant with the release of a new version of Odoo can be removed +from your database with a :ref:`migration script ` using the +`uninstall_module` method from the `upgrade-util package `__. +This method renames the field and the column in the database but does not impact views, reports, +filters, mail templates, automated and server actions, etc., that refer to those fields. Those +references must be found and removed from the database, as well as in the same migration script. + +.. important:: + :ref:`Testing your database ` is crucial, especially when uninstalling a + custom module. Any customized view, report, filter, mail template, automated and server actions, + etc., referring to an uninstall field will prevent them from working correctly and might block + your processes in certain situations. + +.. seealso:: + :ref:`upgrade/comparing_customizations` + +Upgrading custom fields and their data +-------------------------------------- + +Any custom field that has a reference to a modified standard field must be adapted to the new +version of Odoo. To find the corresponding field in the new version, we recommend looking at its +properties and finding a field with matching properties. You can also use the :ref:`upgrade report +` and the `release notes `_ to support +your search. + +.. example:: + In Odoo 12 and before, the `account.invoice` model had a field named `refund_invoice_id` (`source + code `_), + which is absent on the `account.move` model after Odoo 13. This field was renamed to + `reversed_entry_id` during the upgrade process. It is possible to find this information by + searching for another Many2one field in `account.move` related to `account.move`, for example, + `in Odoo 16 `_. + +.. note:: + Renaming fields can be done with the `rename_field` method from `the upgrade-util package `_. + However, this only renames the field and column names. Therefore, custom views, reports, field + relations, automated actions, etc., might still refer to the old field name and need to be + updated in the migration script as well. + +Upgrading models and methods definitions +---------------------------------------- + +Upgrading custom models consists mainly of ensuring that the module name and its inheritances +are correct. The :ref:`upgrade report ` and the `release notes +`_ can contain helpful information concerning various standard +models being changed or renamed. + +.. example:: + The `sale.subscription` model has a `_prepare_invoice_data` method `in Odoo 15 `_ + that has been moved and renamed to `_prepare_invoice` in the `sale.order` model `of Odoo 16 `_. + +If a custom model overrides standard methods, you must ensure that their name still matches the +name of the method they are overriding. In case of changes, you can search the method's source code +in the new version to find its new name. If the method has been refactored, the source code might +not exactly match, and a manual search is then required. + +Upgrading views definitions +--------------------------- + +Views defined in Odoo have an external identifier corresponding to the `id` attribute of a view's +`` tag, which can happen during a module update or when rendering it. + +Most of the time, the incompatibility of a custom view is expressed via an error when parsing the +view, which can happen during the update of a module or when rendering it. + +Custom views for custom models only require upgrading if the custom model has been changed. In +contrast, custom views inheriting from standard views can be impacted by changes in the standard +views. In this case, the custom views' source code requires an upgrade to be compatible with the new +version of its parent view. This can be done by retargetting the various Xpath expressions to match +an equivalent element that might have been moved or renamed. + +Upgrading data +============== + +Errors during upgrade +--------------------- + +Suppose some critical data is removed during the standard upgrade process or an exception is raised, +stopping the upgrade process. In that case, a migration script must be injected during the process +to fix the issue. It can only be done by Odoo employees, as only trusted code can be executed on the +Upgrade server, and custom migration scripts are only executed after the standard process succeeds. + +Errors can be due to two things: + + - An inconsistency in the data of the original database, in which case the underlying issue can be + fixed in production **after testing on a duplicated database** + - An error during the generation of data during the upgrade, in which case the `intervention of a + developer of the Upgrade team `_ is required to fix the issue and + restart the upgrade process + +.. spoiler:: Access error + + Access errors are raised when a user tries to access a record without the proper access rights. + During upgrades, the administrator user (`ID=2`) is used to perform all operations and, + therefore, should be able to access all records. + + .. example:: + `odoo.exceptions.AccessError: You are not allowed to access 'Applicant' (hr.applicant) + records.` + + This message means the administrator (`ID=2`) does not have the access rights to read a + record of the model `hr.applicant` (Recruitment app). The same error message can appear when + trying to access a record from the web interface without the access rights to do so. + + The error can be solved by giving back all administrator access rights to the administrator, + even for custom groups or record rules. + +.. spoiler:: Validation error + + Validation errors are raised by various safeguards implemented in the source code of Odoo, + ensuring data is consistent. The message is usually accompanied by the traceback, which might + display which record is causing the error. + + .. example:: + `odoo.exceptions.ValidationError: the tax group must have the same country_id as the tax + using it.` + + This error is raised in `this part of the code `_. + It is possible to conclude that this error appears if there is a record of the `account.tax` + model for which the country set on the tax group differs from the country set on the tax + itself. + + Therefore, fixing the error requires searching for faulty taxes and fixing them by setting + their country to the country of their tax group (or vice versa), either manually via the web + page of the database, with PSQL queries, or with the :ref:`Odoo shell + `, depending on the hosting type. + +.. seealso:: + - :ref:`reference/exceptions` + - :doc:`Data access restriction <../tutorials/restrict_data_access>` + - :doc:`Access rights <../../applications/general/users/access_rights>` + - :doc:`User management <../../applications/general/users/manage_users>` + +Upgrading server, scheduled, and automated actions +-------------------------------------------------- + +References to fields in server, scheduled, and automated actions might be broken due to changes in +the fields' definitions. This is usually the case for the actions *Execute Python Code*, *Create a +new Record*, or *Update the Record*. + +Those actions are susceptible to being removed by the standard upgrade process, requiring +`intervention from an Odoo developer `_. Otherwise, it can be fixed +with a custom `migration script `_. + +.. note:: + To prevent actions from being removed, it is possible to preemptively change the reference(s) to + a field before upgrading and restoring them after the upgrade process. + +.. seealso:: + :ref:`Server actions ` + +Upgrading studio customizations +=============================== + +.. _reference/upgrade/studio_views: + +Studio views +------------ + +The upgrade process archives Odoo Studio view customizations if an issue is detected with their +definition. The logs will display a warning, but the upgrade process will not halt. + +Unarchiving the view after the upgrade will trigger any error detected in Xpath targets (the `expr` +attribute) and show the complete error message, allowing you to find the broken Xpath expression. It +is recommended to open Odoo Studio on the unarchived view to ensure the view is working properly. + +Views can also be deleted from the database during the upgrade if their corresponding model becomes +invalid, which can happen when models are deleted or changed. Deleted views cannot be restored after +the standard upgrade process, but their deletion can be prevented by `requesting assistance from a +developer of the Upgrade team `_. + +.. note:: + Custom views generated by Studio do not always contain immutable targets in their Xpath + definition. When developing custom views with Studio, changing the generated Xpath to improve + their robustness is a good practice. + +.. spoiler:: The custom view caused validation issues + + This warning is raised when a custom view created with Studio is not valid anymore due to Xpath + targets that cannot be found in the parent view. + + .. example:: + + .. code-block:: console + + 2023-09-04 15:04:33,686 28 INFO database odoo.addons.base.models.ir_ui_view: Element '' cannot be located in parent view + + View name: Odoo Studio: crm.lead.tree.opportunity customization + Error context: + view: ir.ui.view(1137,) + xmlid: studio_customization.odoo_studio_crm_lead_378fc723-a146-2f5b-b6a7-a2f7e15922f8 + view.model: crm.lead + view.parent: ir.ui.view(902,) + + 2023-09-04 15:04:34,315 28 WARNING db_1146520 odoo.addons.base.maintenance.migrations.base.pre-models-ir_ui_view: The custom view `Odoo Studio: crm.lead.tree.opportunity customization` (ID: 1137, Inherit: 902, Model: crm.lead) caused validation issues. + Disabling it for the migration ... + + This issue can be fixed by changing the Xpath target (the `expr` attribute) with a + :ref:`migration script ` using the `edit_view` method from + the `upgrade-util package `_ to match the same element in + the new version of the view. + +.. seealso:: + - :ref:`reference/exceptions` + - :ref:`reference/views` + - :ref:`reference/views/inheritance` + +Studio fields +------------- + +In case of invalid references on a field created by Studio, such as the `model`, `related`, or +`relation`, the field will be deleted by the standard upgrade process. It will, therefore, not be +accessible for the custom migration scripts or on the upgraded database. + +This is why it is necessary to thoroughly test an upgraded database since lost data will **not** be +recoverable once the upgrade of the production database is completed. + +.. example:: + In the upgrade from Odoo 12 to Odoo 13, the `account.invoice` model was merged with + `account.move` and was then subsequently removed. The standard migration scripts took care of + moving the standard data from the PSQL table `account_invoice` to `account_move` (such as the + columns `partner_id`, `name`, `amount_residual`, etc.). Custom field created by users were not + automatically moved. Once the data migration to `account_move` was completed, the + `account_invoice` table was dropped, with all the custom data still in it. + +In those situations, you can `request assistance from Odoo `_ to upgrade +your custom fields during the standard upgrade process by specifying the following: + +- The name of the field(s) removed from your database +- The name of the model(s) they were on +- The reason why they were removed (model removed, relation removed, related field removed, etc.) +- Which new model, relation, or related field they should be on +- Any additional information that could help retrieve the fields + +Studio reports +-------------- + +The mechanism behind reports customization generated by Studio is the same as the one used for +:ref:`reference/upgrade/studio_views`. + +For custom reports duplicated from a standard one, the upgrade process will not upgrade the copy, +meaning that it might be incompatible with the new version of Odoo. This can be fixed by re-copying +the content of the upgraded report and writing it over the content of the duplicated report. Note +that this might lead to issues with the Studio customizations made on the duplicate, such as +invalid Xpath targets. + +.. important:: + The code of a duplicated report should not be modified to ensure it is upgradable. If you need + to modify the code of a report, it is recommended to customize it with Studio.