diff --git a/content/applications/essentials/export_import_data.rst b/content/applications/essentials/export_import_data.rst index 1ff3a2e5d..f2e5db54a 100644 --- a/content/applications/essentials/export_import_data.rst +++ b/content/applications/essentials/export_import_data.rst @@ -2,166 +2,245 @@ Export and import data ====================== +In Odoo, it is sometimes necessary to export or import data for running reports, or for data +modification. This document covers the export and import of data into and out of Odoo. + +.. important:: + Sometimes, users run into a 'time out' error, or a record does not process, due to its size. This + can occur with large exports, or in cases where the import file is too large. To circumvent this + limitation surrounding the size of the records, process exports or imports in smaller batches. + .. _export-data: Export data from Odoo ===================== -When working with a database, it sometimes is necessary to export your data in a distinct file. -Doing so can help to do reporting over your activities (even if Odoo offers a precise and easy -reporting tool with each available application). +When working with a database, it is sometimes necessary to export data in a distinct file. Doing so +can aid in reporting on activities, although, Odoo provides a precise and easy reporting tool with +each available application. -With Odoo, you can export the values from any field in any record. To do so, -activate the list view on the items that need to be exported, click on *Action*, and, then, -on *Export*. +With Odoo, the values can be exported from any field in any record. To do so, activate the list view +(:guilabel:`☰ (three horizontal lines)` icon), on the items that need to be exported, and then +select the records that should be exported. To select a record, tick the checkbox next to the +corresponding record. Finally, click on :guilabel:`⚙️ Action`, and then :guilabel:`Export`. .. image:: export_import_data/list-view-export.png :align: center - :alt: view of the different things to enable/click to export data + :alt: View of the different things to enable/click to export data. -Pretty simple, this action still comes with some specificities. In fact, -when clicking on *Export*, a pop-up window appears with several -options for the data to export: +When clicking on :guilabel:`Export`, an :guilabel:`Export Data` pop-over window appears, with +several options for the data to export: .. image:: export_import_data/export-data-overview.png :align: center - :alt: overview of all the options to take into account when exporting data in Odoo + :alt: Overview of options to consider when exporting data in Odoo.. -#. With the *I want to update data* option ticked, the system only - shows the fields which can be imported. This is very helpful in - case you want to update existing records. Basically, this works - like a filter. Leaving the box unticked gives way more field - options because it shows all the fields, not just the ones which - can be imported. -#. When exporting, you can choose between two formats: .csv and .xls. - With .csv, items are separated with a comma, while .xls holds information about all the - worksheets in a file, including both content and formatting. -#. Those are the items you may want to export. Use the arrows to display - more sub-field options. Of course, you can use the search bar to - find specific fields more easily. To use the search option more - efficiently, display all the fields by clicking on all the - arrows! -#. The + button is there to add fields to the "to export" list. -#. The "handles" next to the selected fields allow you to move the fields up and down to - change the order in which they must be displayed in the exported - file. -#. The trashcan is there if you need to remove fields. -#. For recurring reports, it might be interesting to save export presets. - Select all the needed ones and click on the template bar. - There, click on *New template* and give a name to yours. The - next time you need to export the same list, simply select the - related template. +#. With the :guilabel:`I want to update data (import-compatable export)` option ticked, the system + only shows the fields that can be imported. This is helpful in the case where the existing + records need to be updated. This works like a filter. Leaving the box unticked, gives many more + field options because it shows all the fields, not just the ones that can be imported. +#. When exporting, there is the option to export in two formats: `.csv` and `.xls`. With `.csv`, + items are separated by a comma, while `.xls` holds information about all the worksheets in a + file, including both content and formatting. +#. These are the items that can be exported. Use the :guilabel:`> (right arrow)` icon to display + more sub-field options. Use the :guilabel:`Search` bar to find specific fields. To use the + :guilabel:`Search` option more efficiently, click on all the :guilabel:`> (right arrows)` to + display all fields. +#. The :guilabel:`+ (plus sign)` icon button is present to add fields to the :guilabel:`Fields to + export` list. +#. The :guilabel:`↕️ (up-down arrow)` to the left of the selected fields can be used to move the + fields up and down, to change the order in which they are displayed in the exported file. + Drag-and-drop using the :guilabel:`↕️ (up-down arrow)` icon. +#. The :guilabel:`🗑️ (trash can)` icon is used to remove fields. Click on the :guilabel:`🗑️ (trash + can)` icon to remove the field. +#. For recurring reports, it is helpful to save export presets. Select all the needed fields, and + click on the template drop-down menu. Once there, click on :guilabel:`New template`, and give a + unique name to the export just created. The next time the same list needs to be exported, select + the related template that was previously saved from the drop-down menu. .. tip:: - It’s good to keep the field’s external identifier in mind. For example, - *Related Company* is equal to *parent_id*. Doing so helps export - only what you would like to import next. + It is helpful to know the field's external identifier. For example, :guilabel:`Related Company` + in the export user interface is equal to *parent_id* (external identifier). This is helpful + because then, the only data exported is what should be modified and re-imported. .. _import-data: Import data into Odoo ===================== -How to start ------------- +Importing data into Odoo is extremely helpful during implementation, or in times where data needs to +be updated in bulk. The following documentation covers how to import data into an Odoo database. -You can import data on any Odoo's business object using either Excel -(.xlsx) or CSV (.csv) formats: -contacts, products, bank statements, journal entries and even orders! +.. warning:: + Imports are permanent and **cannot** be undone. However, it is possible to use filters (`created + on` or `last modified`) to identify records changed or created by the import. -Open the view of the object you want to populate and click on :menuselection:`Favorites --> Import -records`. +.. tip:: + Activating :ref:`developer mode ` changes the visible import settings in the left + menu. Doing so reveals an :menuselection:`Advanced` menu. Included in this advanced menu are two + options: :guilabel:`Track history during import` and :guilabel:`Allow matching with subfields`. -.. image:: export_import_data/import_button.png + .. image:: export_import_data/advanced-import.png + :align: center + :alt: Advanced import options when developer mode is activated. + + If the model uses openchatter, the :guilabel:`Track history during import` option sets up + subscriptions and sends notifications during the import, but leads to a slower import. + + Should the :guilabel:`Allow matching with subfields` option be selected, then all subfields + within a field are used to match under the :guilabel:`Odoo Field` while importing. + +Get started +----------- + +Data can be imported on any Odoo business object using either Excel (`.xlsx`) or :abbr:`CSV +(Comma-separated Values)` (`.csv`) formats. This includes: contacts, products, bank statements, +journal entries, and orders. + +Open the view of the object to which the data should be imported/populated, and click on +:menuselection:`⭐ Favorites --> Import records`. + +.. image:: export_import_data/import-button.png :align: center + :alt: Favorites menu revealed with the import records option highlighted. -There you are provided with templates you can easily populate -with your own data. Such templates can be imported in one click; -The data mapping is already done. +After clicking :guilabel:`Import records`, Odoo reveals a separate page with templates that can be +downloaded and populated with the company's own data. Such templates can be imported in one click, +since the data mapping is already done. To download a template click :guilabel:`Import Template for +Customers` at the center of the page. -How to adapt the template -------------------------- +.. important:: + When importing a :abbr:`CSV (Comma-separated Values)` file, Odoo provides :guilabel:`Formatting` + options. These options do **not** appear when importing the proprietary Excel file type (`.xls`, + `.xlsx`). -* Add, remove and sort columns to fit at best your data structure. -* We advise to not remove the **ID** one (see why in the next section). -* Set a unique ID to every single record by dragging down the ID sequencing. + .. image:: export_import_data/formatting.png + :align: center + :alt: Formatting options presented when a CVS file is imported in Odoo. + +Make necessary adjustments to the *Formatting* options, and ensure all columns in the +:guilabel:`Odoo field` and :guilabel:`File Column` are free of errors. Finally, click +:guilabel:`Import` to import the data. + +Adapt a template +---------------- + +Import templates are provided in the import tool of the most common data to import (contacts, +products, bank statements, etc.). Open them with any spreadsheet software (*Microsoft Office*, +*OpenOffice*, *Google Drive*, etc.). + +Once the template is downloaded, proceed to follow these steps: + +- Add, remove, and sort columns to best fit the data structure. +- It is strongly advised to **not** remove the :guilabel:`External ID` (ID) column (see why in the + next section). +- Set a unique ID to every record by dragging down the ID sequencing in the :guilabel:`External ID` + (ID) column. .. image:: export_import_data/dragdown.gif :align: center + :alt: An animation of the mouse dragging down the ID column, so each record has a unique ID. -* When you add a new column, Odoo might not be able to map it automatically if its - label doesn't fit any field in Odoo. Don't worry! You can map - new columns manually when you test the import. Search the list for the - corresponding field. +.. note:: + When a new column is added, Odoo may not be able to map it automatically, if its label does not + fit any field within Odoo. However, new columns can be mapped manually when the import is tested. + Search the drop-down menu for the corresponding field. - .. image:: export_import_data/field_list.png - :align: center + .. image:: export_import_data/field_list.png + :align: center + :alt: Drop-down menu expanded in the initial import screen on Odoo. - Then, use this field's label in your file in order to make it work - straight on the very next time. + Then, use this field's label in the import file to ensure future imports are successful. -How to import from another application --------------------------------------- +.. tip:: + Another useful way to find out the proper column names to import is to export a sample file + using the fields that should be imported. This way, if there is not a sample import template, + the names are accurate. -In order to re-create relationships between different records, -you should use the unique identifier from the original application -and map it to the **ID** (External ID) column in Odoo. -When you import another record that links to the first one, -use **XXX/ID** (XXX/External ID) to the original unique identifier. -You can also find this record using its name but you will be stuck -if at least 2 records have the same name. +Import from another application +------------------------------- -The **ID** will also be used to update the original import -if you need to re-import modified data later, -it's thus good practice to specify it whenever possible. +The :guilabel:`External ID` (ID) is a unique identifier for the line item. Feel free to use one +from previous software to facilitate the transition to Odoo. +Setting an ID is not mandatory when importing, but it helps in many cases: -I cannot find the field I want to map my column to --------------------------------------------------- +- Update imports: import the same file several times without creating duplicates. +- :ref:`Import relation fields `. -Odoo tries to find with some heuristic, based on the first ten lines of -the files, the type of field for each column inside your file. -For example if you have a column only containing numbers, -only the fields that are of type *Integer* will be displayed for you -to choose from. -While this behavior might be good and easy for most cases, -it is also possible that it goes wrong or that you want to -map your column to a field that is not proposed by default. +To recreate relationships between different records, the unique identifier from the original +application should be used to map it to the :guilabel:`External ID` (ID) column in Odoo. -If that happens, you just have to check the -** Show fields of relation fields (advanced)** option, -you will then be able to choose from the complete list of fields for each column. +When another record is imported that links to the first one, use **XXX/ID** (XXX/External ID) for +the original unique identifier. This record can also be found using its name. + +.. warning:: + It should be noted that there will be a conflict if two or more records have the same name. + +The :guilabel:`External ID` (ID) can also be used to update the original import, if modified data +needs to be re-imported later, therefore, it is a good practice to specify it whenever possible. + +Field missing to map column +--------------------------- + +Odoo heuristically tries to find the type of field for each column inside the imported file, based +on the first ten lines of the files. + +For example, if there is a column only containing numbers, only the fields with the *integer* type +are presented as options. + +While this behavior might be beneficial in most cases, it is also possible that it could fail, or +the column may be mapped to a field that is not proposed by default. + +If this happens, check the :guilabel:`Show fields of relation fields (advanced) option`, then a +complete list of fields becomes available for each column. .. image:: export_import_data/field_list.png :align: center + :alt: Searching for the field to match the tax column. -Where can I change the date import format? ------------------------------------------- - -Odoo can automatically detect if a column is a date, and it will try to guess the date format from a -set of most commonly used date formats. While this process can work for many date formats, some date -formats will not be recognized. This can cause confusion due to day-month inversions; it is -difficult to guess which part of a date format is the day and which part is the month in a date such -as '01-03-2016'. - -To view which date format Odoo has found from your file you can check the **Date Format** that is -shown when clicking on **Options** under the file selector. If this format is incorrect you can -change it to your liking using the *ISO 8601* to define the format. +Change data import format +------------------------- .. note:: - If you are importing an excel (.xls, .xlsx) file, you can use date cells to store dates as the - display of dates in excel is different from the way it is stored. That way you will be sure that - the date format is correct in Odoo whatever your locale date format is. + Odoo can automatically detect if a column is a date, and tries to guess the date format from a + set of most commonly used date formats. While this process can work for many date formats, some + date formats are not recognizable. This can cause confusion, due to day-month inversions; it is + difficult to guess which part of a date format is the day, and which part is the month, in a + date, such as `01-03-2016`. -Can I import numbers with currency sign (e.g.: $32.00)? -------------------------------------------------------- +When importing a :abbr:`CSV (Comma-separated Values)` file, Odoo provides :guilabel:`Formatting` +options. -Yes, we fully support numbers with parenthesis to represent negative sign as well as numbers with -currency sign attached to them. Odoo also automatically detect which thousand/decimal separator you -use (you can change those under **options**). If you use a currency symbol that is not known to -Odoo, it might not be recognized as a number though and it will crash. +To view which date format Odoo has found from the file, check the :guilabel:`Date Format` that is +shown when clicking on options under the file selector. If this format is incorrect, change it to +the preferred format using *ISO 8601* to define the format. -Examples of supported numbers (using thirty-two thousands as an example): +.. important:: + *ISO 8601* is an international standard, covering the worldwide exchange, along with the + communication of date and time-related data. For example, the date format should be `YYYY-MM-DD`. + So, in the case of July 24th 1981, it should be written as `1981-07-24`. + +.. tip:: + When importing Excel files (`.xls`, `.xlsx`), consider using *date cells* to store dates. This + maintains locale date formats for display, regardless of how the date is formatted in Odoo. When + importing a :abbr:`CSV (Comma-separated Values)` file, use Odoo's :guilabel:`Formatting` section + to select the date format columns to import. + +Import numbers with currency signs +---------------------------------- + +Odoo fully supports numbers with parenthesis to represent negative signs, as well as numbers with +currency signs attached to them. Odoo also automatically detects which thousand/decimal separator is +used. If a currency symbol unknown to Odoo is used, it might not be recognized as a number, and the +import crashes. + +.. note:: + When importing a :abbr:`CSV (Comma-separated Values)` file, the :guilabel:`Formatting` menu + appears on the left-hand column. Under these options, the :guilabel:`Thousands Separator` can be + changed. + +Examples of supported numbers (using 'thirty-two thousand' as the figure): - 32.000,00 - 32000,00 @@ -176,156 +255,191 @@ Example that will not work: - ABC 32.000,00 - $ (32.000,00) -What can I do when the Import preview table isn't displayed correctly? ----------------------------------------------------------------------- +.. important:: + A :guilabel:`() (parenthesis)` around the number indicates that the number is a negative value. + The currency symbol **must** be placed within the parenthesis for Odoo to recognize it as a + negative currency value. -By default the Import preview is set on commas as field separators and quotation marks as text -delimiters. If your csv file does not have these settings, you can modify the File Format Options -(displayed under the Browse CSV file bar after you select your file). +Import preview table not displayed correctly +-------------------------------------------- -Note that if your CSV file has a tabulation as separator, Odoo will not detect the separations. You -will need to change the file format options in your spreadsheet application. See the following -question. +By default, the import preview is set on commas as field separators, and quotation marks as text +delimiters. If the :abbr:`CSV (Comma-separated Values)` file does not have these settings, modify +the :guilabel:`Formatting` options (displayed under the :guilabel:`Import` :abbr:`CSV +(Comma-separated Values)` file bar after selecting the :abbr:`CSV (Comma-separated Values)` file). -How can I change the CSV file format options when saving in my spreadsheet application? ---------------------------------------------------------------------------------------- +.. important:: + If the :abbr:`CSV (Comma-separated Values)` file has a tabulation as a separator, Odoo does + **not** detect the separations. The file format options need to be modified in the spreadsheet + application. See the following :ref:`Change CSV file format ` + section. -If you edit and save CSV files in spreadsheet applications, your computer's regional settings will -be applied for the separator and delimiter. We suggest you use OpenOffice or LibreOffice Calc as -they will allow you to modify all three options (in :menuselection:`'Save As' dialog box --> Check the -box 'Edit filter settings' --> Save`). +.. _export_import_data/change-csv: -Microsoft Excel will allow you to modify only the encoding when saving (in :menuselection:`'Save As' -dialog box --> click 'Tools' dropdown list --> Encoding tab`). +Change CSV file format in spreadsheet application +------------------------------------------------- -What's the difference between Database ID and External ID? ----------------------------------------------------------- +When editing and saving :abbr:`CSV (Comma-separated Values)` files in spreadsheet applications, the +computer's regional settings are applied for the separator and delimiter. Odoo suggests using +*OpenOffice* or *LibreOffice*, as both applications allow modifications of all three options (from +*LibreOffice* application, go to :menuselection:`'Save As' dialog box --> Check the box 'Edit filter +settings' --> Save`). + +Microsoft Excel can modify the encoding when saving (:menuselection:`'Save As' dialog box --> +'Tools' drop-down menu --> Encoding tab`). + +Difference between Database ID and External ID +---------------------------------------------- Some fields define a relationship with another object. For example, the country of a contact is a -link to a record of the 'Country' object. When you want to import such fields, Odoo will have to -recreate links between the different records. To help you import such fields, Odoo provides three -mechanisms. You must use one and only one mechanism per field you want to import. +link to a record of the 'Country' object. When such fields are imported, Odoo has to recreate links +between the different records. To help import such fields, Odoo provides three mechanisms. -For example, to reference the country of a contact, Odoo proposes you 3 different fields to import: +.. important:: + **Only one** mechanism should be used per field that is imported. -- Country: the name or code of the country -- Country/Database ID: the unique Odoo ID for a record, defined by the ID postgresql column -- Country/External ID: the ID of this record referenced in another application (or the .XML file - that imported it) +For example, to reference the country of a contact, Odoo proposes three different fields to import: -For the country Belgium, you can use one of these 3 ways to import: +- :guilabel:`Country`: the name or code of the country +- :guilabel:`Country/Database ID`: the unique Odoo ID for a record, defined by the ID PostgreSQL + column +- :guilabel:`Country/External ID`: the ID of this record referenced in another application (or the + `.XML` file that imported it) -- Country: Belgium -- Country/Database ID: 21 -- Country/External ID: base.be +For the country of Belgium, for example, use one of these three ways to import: -According to your need, you should use one of these 3 ways to reference records in relations. Here -is when you should use one or the other, according to your need: +- :guilabel:`Country`: `Belgium` +- :guilabel:`Country/Database ID`: `21` +- :guilabel:`Country/External ID`: `base.be` -- Use Country: This is the easiest way when your data come from CSV files that have been created - manually. -- Use Country/Database ID: You should rarely use this notation. It's mostly used by developers as - it's main advantage is to never have conflicts (you may have several records with the same name, +According to the company's need, use one of these three ways to reference records in relations. Here +is an example when one or the other should be used, according to the need: + +- Use :guilabel:`Country`: this is the easiest way when data comes from :abbr:`CSV (Comma-separated + Values)` files that have been created manually. +- Use :guilabel:`Country/Database ID`: this should rarely be used. It is mostly used by developers + as the main advantage is to never have conflicts (there may be several records with the same name, but they always have a unique Database ID) -- Use Country/External ID: Use External ID when you import data from a third party application. +- Use :guilabel:`Country/External ID`: use *External ID* when importing data from a third-party + application. -When you use External IDs, you can import CSV files with the "External ID" column to define the -External ID of each record you import. Then, you will be able to make a reference to that record -with columns like "Field/External ID". The following two CSV files give you an example for Products -and their Categories. +When *External IDs* are used, import :abbr:`CSV (Comma-separated Values)` files with the +:guilabel:`External ID` (ID) column defining the *External ID* of each record that is imported. +Then, a reference can be made to that record with columns, like `Field/External ID`. The following +two :abbr:`CSV (Comma-separated Values)` files provide an example for products and their categories. -:download:`CSV file for categories -`. +- :download:`CSV file for categories + ` +- :download:`CSV file for Products + ` -:download:`CSV file for Products -`. +.. _export_import_data/relation-fields: -What can I do if I have multiple matches for a field? ------------------------------------------------------ +Import relation fields +---------------------- -If for example you have two product categories with the child name "Sellable" (ie. "Misc. -Products/Sellable" & "Other Products/Sellable"), your validation is halted but you may still import -your data. However, we recommend you do not import the data because they will all be linked to the -first 'Sellable' category found in the Product Category list ("Misc. Products/Sellable"). We -recommend you modify one of the duplicates' values or your product category hierarchy. +An Odoo object is always related to many other objects (e.g. a product is linked to product +categories, attributes, vendors, etc.). To import those relations, the records of the related object +need to be imported first, from their own list menu. -However if you do not wish to change your configuration of product categories, we recommend you use -make use of the external ID for this field 'Category'. +This can be achieved by using either the name of the related record, or its ID, depending on the +circumstances. The ID is expected when two records have the same name. In such a case add `/ ID` +at the end of the column title (e.g. for product attributes: `Product Attributes / Attribute / ID`). -How can I import a many2many relationship field (e.g. a customer that has multiple tags)? ------------------------------------------------------------------------------------------ +Options for multiple matches on fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The tags should be separated by a comma without any spacing. For example, if you want your customer -to be linked to both tags 'Manufacturer' and 'Retailer' then you will encode "Manufacturer,Retailer" -in the same column of your CSV file. +If, for example, there are two product categories with the child name `Sellable` (e.g. `Misc. +Products/Sellable` & `Other Products/Sellable`), the validation is halted, but the data may still be +imported. However, Odoo recommends that the data is not imported because it will all be linked to +the first `Sellable` category found in the *Product Category* list (`Misc. Products/Sellable`). +Odoo, instead, recommends modifying one of the duplicate's values, or the product category +hierarchy. -:download:`CSV file for Manufacturer, Retailer ` +However, if the company does not wish to change the configuration of product categories, Odoo +recommends making use of the *External ID* for this field, 'Category'. +Import many2many relationship fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -How can I import a one2many relationship (e.g. several Order Lines of a Sales Order)? -------------------------------------------------------------------------------------- +The tags should be separated by a comma, without any spacing. For example, if a customer needs to be +linked to both tags: `Manufacturer` and `Retailer` then 'Manufacturer,Retailer' needs to be encoded +in the same column of the :abbr:`CSV (Comma-separated Values)` file. -If you want to import sales order having several order lines; for each order line, you need to -reserve a specific row in the CSV file. The first order line will be imported on the same row as the -information relative to order. Any additional lines will need an additional row that does not have -any information in the fields relative to the order. As an example, here is -``purchase.order_functional_error_line_cant_adpat.CSV`` file of some quotations you can import, -based on demo data. +- :download:`CSV file for Manufacturer, Retailer ` -:download:`File for some Quotations `. +Import one2many relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following CSV file shows how to import purchase orders with their respective purchase order -lines: +If a company wants to import a sales order with several order lines, a specific row **must** be +reserved in the :abbr:`CSV (Comma-separated Values)` file for each order line. The first order line +is imported on the same row as the information relative to order. Any additional lines need an +additional row that does not have any information in the fields relative to the order. -:download:`Purchase orders with their respective purchase order lines `. +As an example, here is a :abbr:`CSV (Comma-separated Values)` file of some quotations that can be +imported, based on demo data: -The following CSV file shows how to import customers and their respective contacts: +- :download:`File for some Quotations + ` -:download:`Customers and their respective contacts `. +The following :abbr:`CSV (Comma-separated Values)` file shows how to import purchase orders with +their respective purchase order lines: -Can I import several times the same record? -------------------------------------------- +- :download:`Purchase orders with their respective purchase order lines + ` -If you import a file that contains one of the column "External ID" or "Database ID", records that -have already been imported will be modified instead of being created. This is very useful as it -allows you to import several times the same CSV file while having made some changes in between two -imports. Odoo will take care of creating or modifying each record depending if it's new or not. +The following :abbr:`CSV (Comma-separated Values)` file shows how to import customers and their +respective contacts: -This feature allows you to use the Import/Export tool of Odoo to modify a batch of records in your -favorite spreadsheet application. +- :download:`Customers and their respective contacts + ` -What happens if I do not provide a value for a specific field? +Import records several times +---------------------------- + +If an imported file contains one of the columns: :guilabel:`External ID` or :guilabel:`Database ID`, +records that have already been imported are modified, instead of being created. This is extremely +useful as it allows users to import the same :abbr:`CSV (Comma-separated Values)` file several +times, while having made some changes in between two imports. + +Odoo takes care of creating or modifying each record, depending if it is new or not. + +This feature allows a company to use the *Import/Export tool* in Odoo to modify a batch of records +in a spreadsheet application. + +Value not provided for a specific field +--------------------------------------- + +If all fields are not set in the CSV file, Odoo assigns the default value for every non-defined +field. But, if fields are set with empty values in the :abbr:`CSV (Comma-separated Values)` file, +Odoo sets the empty value in the field, instead of assigning the default value. + +Export/import different tables from an SQL application to Odoo -------------------------------------------------------------- -If you do not set all fields in your CSV file, Odoo will assign the default value for every non -defined fields. But if you set fields with empty values in your CSV file, Odoo will set the EMPTY -value in the field, instead of assigning the default value. +If data needs to be imported from different tables, relations need to be recreated between records +belonging to different tables. For instance, if companies and people are imported, the link between +each person and the company they work for needs to be recreated. -How to export/import different tables from an SQL application to Odoo? ----------------------------------------------------------------------- +To manage relations between tables, use the `External ID` facilities of Odoo. The `External ID` of a +record is the unique identifier of this record in another application. The `External ID` must be +unique across all records of all objects. It is a good practice to prefix this `External ID` with +the name of the application or table. (like, 'company_1', 'person_1' - instead of '1') -If you need to import data from different tables, you will have to recreate relations between -records belonging to different tables. (e.g. if you import companies and persons, you will have to -recreate the link between each person and the company they work for). +As an example, suppose there is an SQL database with two tables that are to be imported: companies +and people. Each person belongs to one company, so the link between a person and the company they +work for must be recreated. -To manage relations between tables, you can use the "External ID" facilities of Odoo. The "External -ID" of a record is the unique identifier of this record in another application. This "External ID" -must be unique across all the records of all objects, so it's a good practice to prefix this -"External ID" with the name of the application or table. (like 'company_1', 'person_1' instead of -'1') +Test this example, with a :download:`sample of a PostgreSQL database +`. -As an example, suppose you have a SQL database with two tables you want to import: companies and -persons. Each person belong to one company, so you will have to recreate the link between a person -and the company he work for. (If you want to test this example, here is a :download:`dump of such a -PostgreSQL database `) - -We will first export all companies and their "External ID". In PSQL, write the following command: +First, export all companies and their *External ID*. In PSQL, write the following command: .. code-block:: sh > copy (select 'company_'||id as "External ID",company_name as "Name",'True' as "Is a Company" from companies) TO '/tmp/company.csv' with CSV HEADER; -This SQL command will create the following CSV file: +This SQL command creates the following :abbr:`CSV (Comma-separated Values)` file: .. code-block:: text @@ -334,13 +448,14 @@ This SQL command will create the following CSV file: company_2,Organi,True company_3,Boum,True -To create the CSV file for persons, linked to companies, we will use the following SQL command in PSQL: +To create the :abbr:`CSV (Comma-separated Values)` file for people linked to companies, use the +following SQL command in PSQL: .. code-block:: sh > copy (select 'person_'||id as "External ID",person_name as "Name",'False' as "Is a Company",'company_'||company_id as "Related Company/External ID" from persons) TO '/tmp/person.csv' with CSV -It will produce the following CSV file: +It produces the following :abbr:`CSV (Comma-separated Values)` file: .. code-block:: text @@ -350,62 +465,13 @@ It will produce the following CSV file: person_3,Eric,False,company_2 person_4,Ramsy,False,company_3 -As you can see in this file, Fabien and Laurence are working for the Bigees company (company_1) and -Eric is working for the Organi company. The relation between persons and companies is done using the -External ID of the companies. We had to prefix the "External ID" by the name of the table to avoid a -conflict of ID between persons and companies (person_1 and company_1 who shared the same ID 1 in the -original database). +In this file, Fabien and Laurence are working for the Bigees company (`company_1`), and Eric is +working for the Organi company. The relation between people and companies is done using the +*External ID* of the companies. The *External ID* is prefixed by the name of the table to avoid a +conflict of ID between people and companies (`person_1` and `company_1`, who shared the same ID 1 in +the original database). The two files produced are ready to be imported in Odoo without any modifications. After having -imported these two CSV files, you will have 4 contacts and 3 companies. (the firsts two contacts are -linked to the first company). You must first import the companies and then the persons. - -How to adapt an import template -=============================== - -Import templates are provided in the import tool of the most common data to -import (contacts, products, bank statements, etc.). -You can open them with any spreadsheets software (Microsoft Office, -OpenOffice, Google Drive, etc.). - -How to customize the file -========================= - -* Remove columns you don't need. We advise to not remove the *ID* one (see - why here below). -* Set a unique ID to every single record by dragging down the ID sequencing. - - .. image:: export_import_data/dragdown.gif - :align: center - -* When you add a new column, Odoo might not be able to map it automatically if its - label doesn't fit any field of the system. - If so, find the corresponding field using the search. - - .. image:: export_import_data/field_list.png - :align: center - - Then, use the label you found in your import template in order to make it work - straight away the very next time you try to import. - -Why an “ID” column -================== - -The **ID** (External ID) is an unique identifier for the line item. -Feel free to use the one of your previous software to ease the transition to Odoo. - -Setting an ID is not mandatory when importing but it helps in many cases: - -* Update imports: you can import the same file several times without creating duplicates; -* Import relation fields (see here below). - -How to import relation fields -============================= - -An Odoo object is always related to many other objects (e.g. a product is linked -to product categories, attributes, vendors, etc.). To import those relations you need to -import the records of the related object first from their own list menu. - -You can do it using either the name of the related record or its ID. The ID is expected when -two records have the same name. In such a case add " / ID" at the end of the column title -(e.g. for product attributes: Product Attributes / Attribute / ID). +imported these two :abbr:`CSV (Comma-separated Values)` files, there are four contacts and three +companies (the first two contacts are linked to the first company). Keep in mind to first import +the companies, and then the people. diff --git a/content/applications/essentials/export_import_data/advanced-import.png b/content/applications/essentials/export_import_data/advanced-import.png new file mode 100644 index 000000000..763e5659b Binary files /dev/null and b/content/applications/essentials/export_import_data/advanced-import.png differ diff --git a/content/applications/essentials/export_import_data/export-data-overview.png b/content/applications/essentials/export_import_data/export-data-overview.png index 62bcb72f1..faac491ee 100644 Binary files a/content/applications/essentials/export_import_data/export-data-overview.png and b/content/applications/essentials/export_import_data/export-data-overview.png differ diff --git a/content/applications/essentials/export_import_data/formatting.png b/content/applications/essentials/export_import_data/formatting.png new file mode 100644 index 000000000..ccd554a6a Binary files /dev/null and b/content/applications/essentials/export_import_data/formatting.png differ diff --git a/content/applications/essentials/export_import_data/import-button.png b/content/applications/essentials/export_import_data/import-button.png new file mode 100644 index 000000000..6ec031e79 Binary files /dev/null and b/content/applications/essentials/export_import_data/import-button.png differ diff --git a/content/applications/essentials/export_import_data/import_button.png b/content/applications/essentials/export_import_data/import_button.png deleted file mode 100644 index 8e37f897b..000000000 Binary files a/content/applications/essentials/export_import_data/import_button.png and /dev/null differ diff --git a/content/applications/essentials/export_import_data/list-view-export.png b/content/applications/essentials/export_import_data/list-view-export.png index e4debf016..a1b8588a1 100644 Binary files a/content/applications/essentials/export_import_data/list-view-export.png and b/content/applications/essentials/export_import_data/list-view-export.png differ