From 0ff269649378de5918247df478a374ad5e265865 Mon Sep 17 00:00:00 2001 From: Cedric Snauwaert Date: Mon, 4 Apr 2016 17:21:48 +0200 Subject: [PATCH] [ADD] base_import FAQ --- ...d_party_application_product_categories.csv | 6 + ...rnal_id_3rd_party_application_products.csv | 6 + .../example_files/database_import_test.sql | 155 ++++++++++ _static/example_files/m2m_customers_tags.csv | 6 + .../example_files/o2m_customers_contacts.csv | 9 + .../o2m_purchase_order_lines.csv | 10 + ...order_functional_error_line_cant_adpat.csv | 6 + applications.rst | 1 + conf.py | 2 +- general.rst | 8 + general/base_import.rst | 8 + general/base_import/import_faq.rst | 281 ++++++++++++++++++ 12 files changed, 497 insertions(+), 1 deletion(-) create mode 100644 _static/example_files/External_id_3rd_party_application_product_categories.csv create mode 100644 _static/example_files/External_id_3rd_party_application_products.csv create mode 100644 _static/example_files/database_import_test.sql create mode 100644 _static/example_files/m2m_customers_tags.csv create mode 100644 _static/example_files/o2m_customers_contacts.csv create mode 100644 _static/example_files/o2m_purchase_order_lines.csv create mode 100644 _static/example_files/purchase.order_functional_error_line_cant_adpat.csv create mode 100644 general.rst create mode 100644 general/base_import.rst create mode 100644 general/base_import/import_faq.rst diff --git a/_static/example_files/External_id_3rd_party_application_product_categories.csv b/_static/example_files/External_id_3rd_party_application_product_categories.csv new file mode 100644 index 000000000..5b77f269d --- /dev/null +++ b/_static/example_files/External_id_3rd_party_application_product_categories.csv @@ -0,0 +1,6 @@ +External ID,Name,Parent Category/External ID +a1,Expenses,product.product_category_all +a2,Other Products,product.product_category_all +a3,Sellable Products,product.product_category_all +a4,Tables,a1 +a5,Seating furniture,a2 diff --git a/_static/example_files/External_id_3rd_party_application_products.csv b/_static/example_files/External_id_3rd_party_application_products.csv new file mode 100644 index 000000000..bf2a52386 --- /dev/null +++ b/_static/example_files/External_id_3rd_party_application_products.csv @@ -0,0 +1,6 @@ +External ID,Name,Internal Reference,Category/External ID,Can be Expensed,Can be Purchased,Can be Sold,Sale Price,Cost,Supply Method,Product Type,Procurement Method +a6,Aluminum Stool,ALS,a5,False,True,True,49.00,25.00,Buy,Stockable Product,Make to Stock +a7,Chair,CHR,a5,False,True,True,89.00,40.00,Buy,Stockable Product,Make to Stock +a8,Table,TBL,a4,False,True,True,169.00,100.00,Buy,Stockable Product,Make to Stock +a9,Software Book Tutorial,SBT,a2,False,True,False,19.00,8.00,Buy,Consumable,Make to Stock +a10,Fuel,FL,a1,True,False,False,0.30,0.25,Buy,Service,Make to Stock diff --git a/_static/example_files/database_import_test.sql b/_static/example_files/database_import_test.sql new file mode 100644 index 000000000..1f7917914 --- /dev/null +++ b/_static/example_files/database_import_test.sql @@ -0,0 +1,155 @@ +-- +-- PostgreSQL database dump +-- + +SET statement_timeout = 0; +SET client_encoding = 'UTF8'; +SET standard_conforming_strings = off; +SET check_function_bodies = false; +SET client_min_messages = warning; +SET escape_string_warning = off; + +SET search_path = public, pg_catalog; + +SET default_tablespace = ''; + +SET default_with_oids = false; + +-- +-- Name: companies; Type: TABLE; Schema: public; Owner: fp; Tablespace: +-- + +CREATE TABLE companies ( + id integer NOT NULL, + company_name character varying +); + + +ALTER TABLE public.companies OWNER TO fp; + +-- +-- Name: companies_id_seq; Type: SEQUENCE; Schema: public; Owner: fp +-- + +CREATE SEQUENCE companies_id_seq + START WITH 1 + INCREMENT BY 1 + NO MAXVALUE + NO MINVALUE + CACHE 1; + + +ALTER TABLE public.companies_id_seq OWNER TO fp; + +-- +-- Name: companies_id_seq; Type: SEQUENCE OWNED BY; Schema: public; Owner: fp +-- + +ALTER SEQUENCE companies_id_seq OWNED BY companies.id; + + +-- +-- Name: companies_id_seq; Type: SEQUENCE SET; Schema: public; Owner: fp +-- + +SELECT pg_catalog.setval('companies_id_seq', 3, true); + + +-- +-- Name: persons; Type: TABLE; Schema: public; Owner: fp; Tablespace: +-- + +CREATE TABLE persons ( + id integer NOT NULL, + company_id integer, + person_name character varying +); + + +ALTER TABLE public.persons OWNER TO fp; + +-- +-- Name: persons_id_seq; Type: SEQUENCE; Schema: public; Owner: fp +-- + +CREATE SEQUENCE persons_id_seq + START WITH 1 + INCREMENT BY 1 + NO MAXVALUE + NO MINVALUE + CACHE 1; + + +ALTER TABLE public.persons_id_seq OWNER TO fp; + +-- +-- Name: persons_id_seq; Type: SEQUENCE OWNED BY; Schema: public; Owner: fp +-- + +ALTER SEQUENCE persons_id_seq OWNED BY persons.id; + + +-- +-- Name: persons_id_seq; Type: SEQUENCE SET; Schema: public; Owner: fp +-- + +SELECT pg_catalog.setval('persons_id_seq', 4, true); + + +-- +-- Name: id; Type: DEFAULT; Schema: public; Owner: fp +-- + +ALTER TABLE ONLY companies ALTER COLUMN id SET DEFAULT nextval('companies_id_seq'::regclass); + + +-- +-- Name: id; Type: DEFAULT; Schema: public; Owner: fp +-- + +ALTER TABLE ONLY persons ALTER COLUMN id SET DEFAULT nextval('persons_id_seq'::regclass); + + +-- +-- Data for Name: companies; Type: TABLE DATA; Schema: public; Owner: fp +-- + +COPY companies (id, company_name) FROM stdin; +1 Bigees +2 Organi +3 Boum +\. + + +-- +-- Data for Name: persons; Type: TABLE DATA; Schema: public; Owner: fp +-- + +COPY persons (id, company_id, person_name) FROM stdin; +1 1 Fabien +2 1 Laurence +3 2 Eric +4 3 Ramsy +\. + + +-- +-- Name: companies_pkey; Type: CONSTRAINT; Schema: public; Owner: fp; Tablespace: +-- + +ALTER TABLE ONLY companies + ADD CONSTRAINT companies_pkey PRIMARY KEY (id); + + +-- +-- Name: persons_company_id_fkey; Type: FK CONSTRAINT; Schema: public; Owner: fp +-- + +ALTER TABLE ONLY persons + ADD CONSTRAINT persons_company_id_fkey FOREIGN KEY (company_id) REFERENCES companies(id); + + +-- +-- PostgreSQL database dump complete +-- + diff --git a/_static/example_files/m2m_customers_tags.csv b/_static/example_files/m2m_customers_tags.csv new file mode 100644 index 000000000..e6d74d4f8 --- /dev/null +++ b/_static/example_files/m2m_customers_tags.csv @@ -0,0 +1,6 @@ +Name,Reference,Tags,Customer,Street,City,Country +Credit & Leasing,3,Services,True,Central Avenue 814,Johannesburg,South Africa +Services & Finance,5,"Consultancy Services,IT Services",True,Grove Road 5,London,United Kingdom +Hydra Supplies,6,"Manufacturer,Retailer",True,Palm Street 9,Los Angeles,United States +Bolts & Screws,8,"Wholesaler,Components Buyer",True,Rua Américo 1000,Campinas,Brazil +National Parts & Supplies,18,"Manufacturer,Wholesaler",True,Guangdong Way 20,Shenzen,China diff --git a/_static/example_files/o2m_customers_contacts.csv b/_static/example_files/o2m_customers_contacts.csv new file mode 100644 index 000000000..bf142142d --- /dev/null +++ b/_static/example_files/o2m_customers_contacts.csv @@ -0,0 +1,9 @@ +Name,Is a company,Related company,Address type,Customer,Supplier,Street,ZIP,City,State,Country +Aurora Shelves,1,,,1,0,25 Pacific Road,95101,San José,CA,United States +Roger Martins,0,Aurora Shelves,Invoice address,1,0,27 Pacific Road,95102,San José,CA,United States +House Sales Direct,1,,,1,0,104 Saint Mary Avenue,94059,Redwood,CA,United States +Yvan Holiday,0,House Sales Direct,Contact,1,0,104 Saint Mary Avenue,94060,Redwood,CA,United States +Jack Unsworth,0,House Sales Direct,Invoice address,1,0,227 Jackson Road,94061,Redwood,CA,United States +Michael Mason,0,,,1,0,16 5th Avenue,94104,San Francisco,CA,United States +International Wood,1,,,1,0,748 White House Boulevard,20004,Washington,DC,United States +Sharon Pecker,0,International Wood,Invoice address,1,0,755 White House Boulevard,20005,Washington,DC,United States diff --git a/_static/example_files/o2m_purchase_order_lines.csv b/_static/example_files/o2m_purchase_order_lines.csv new file mode 100644 index 000000000..4778b99cb --- /dev/null +++ b/_static/example_files/o2m_purchase_order_lines.csv @@ -0,0 +1,10 @@ +Order Date,Order Reference,Supplier,Destination,Pricelist,Order Lines / Product,Order Lines / Quantity +2012-12-15,PO00008,ASUSTeK,Stock,Default Purchase Pricelist,ADPT,20 +,,,,,CARD,30 +,,,,,C-Case,40 +2012-12-15,PO00009,Axelor,Stock,Default Purchase Pricelist,CD,5 +,,,,,CPUa8,15 +2012-12-15,PO000010,China Export,Stock,Default Purchase Pricelist,HDD SH-1,10 +,,,,,HDD SH-2,20 +,,,,,LAP-CUS,35 +,,,,,LAP-E5,40 diff --git a/_static/example_files/purchase.order_functional_error_line_cant_adpat.csv b/_static/example_files/purchase.order_functional_error_line_cant_adpat.csv new file mode 100644 index 000000000..3b4287634 --- /dev/null +++ b/_static/example_files/purchase.order_functional_error_line_cant_adpat.csv @@ -0,0 +1,6 @@ +"Order Reference","Supplier","Destination","Pricelist","Order Lines / Product","Order Lines / Quantity" +"PO000020","ASUSTeK","Stock","Default Purchase Pricelist","ADPT",20 +,,,,"CARD",30 +,,,,"C-Case",40 +"PO000021","Axelor","Stock","Default Purchase Pricelist","CD",5 +,,,,"CPUa8",15 diff --git a/applications.rst b/applications.rst index a027224c5..7cd313b14 100644 --- a/applications.rst +++ b/applications.rst @@ -15,5 +15,6 @@ Applications project getting_started/documentation website + general .. expenses .. recruitment diff --git a/conf.py b/conf.py index d95a603ae..8dbdde424 100644 --- a/conf.py +++ b/conf.py @@ -235,7 +235,7 @@ latex_logo = '_static/banners/odoo_logo.png' #latex_show_pagerefs = False # If true, show URL addresses after external links. -latex_show_urls = True +# latex_show_urls = True # Documents to append as an appendix to all manuals. #latex_appendices = [] diff --git a/general.rst b/general.rst new file mode 100644 index 000000000..408727ca6 --- /dev/null +++ b/general.rst @@ -0,0 +1,8 @@ +======= +General +======= + +.. toctree:: + :titlesonly: + + general/base_import \ No newline at end of file diff --git a/general/base_import.rst b/general/base_import.rst new file mode 100644 index 000000000..c0e027665 --- /dev/null +++ b/general/base_import.rst @@ -0,0 +1,8 @@ +=========== +BASE IMPORT +=========== + +.. toctree:: + :titlesonly: + + base_import/import_faq \ No newline at end of file diff --git a/general/base_import/import_faq.rst b/general/base_import/import_faq.rst new file mode 100644 index 000000000..6a7c1aad0 --- /dev/null +++ b/general/base_import/import_faq.rst @@ -0,0 +1,281 @@ +======================= +Import CSV file to Odoo +======================= + + + +Frequently Asked Questions +-------------------------- + + +Need to import data from an other application? +---------------------------------------------- + +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 an other record that links to the +first one, use **XXX/ID** (XXX/External ID) to the original unique identifier. + +The **ID** (External 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. + +I cannot find the field I want to map my column to? +--------------------------------------------------- + +Odoo tries to find with some heuristic, based on the first ten lines of the +files, the type of field for each columns 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 behaviour might be good and +easy for most cases scenarios, it is also possible that it goes wrong sometimes +or that you want to map your column to a field that is not proposed by default. + +If that happens, you just have to check the **Show all fields for completion +(advanced)** option, you will then be able to choose from the complete list of +fields for each columns. + +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 used date format. While this process can +work for a lot of simple date formats, some exotic date formats will not be +recognized and it is also possible to have some confusion (day and month +inverted as example) as it is difficult to guess correctly which part is the +day and which one is the month in a date like '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. + +.. 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. + +Can I import numbers with currency sign (e.g.: $32.00)? +------------------------------------------------------- + +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. + +Examples of supported numbers (using thirty-two thousands as an example): + +- 32.000,00 +- 32000,00 +- 32,000.00 +- -32000.00 +- (32000.00) +- $ 32.000,00 +- (32000.00 €) + +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? +---------------------------------------------------------------------- + +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). + +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. + +How can I change the CSV file format options when saving in my spreadsheet application? +--------------------------------------------------------------------------------------- + +If you edit and save CSV files in speadsheet 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 ( +:menuselection:`in 'Save As' dialog box --> Check the box 'Edit filter settings' --> Save`). + +Microsoft Excel will allow you to modify only the encoding when saving ( +:menuselection:`in 'Save As' dialog box --> click 'Tools' dropdown list --> Encoding tab`). + +What's the 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 3 mechanisms. You must +use one and only one mechanism per field you want to import. + +For example, to reference the country of a contact, Odoo proposes you 3 +different fields to import: + +- 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 the country Belgium, you can use one of these 3 ways to import: + +- Country: Belgium +- Country/Database ID: 21 +- Country/External ID: base.be + +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: + +- 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, but they always have a unique + Database ID) +- Use Country/External ID: Use External ID when you import 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. + +`CSV file for categories <../../_static/example_files/External_id_3rd_party_application_product_categories.csv>`_. + +`CSV file for Products <../../_static/example_files/External_id_3rd_party_application_products.csv>`_. + +What can I do if I have multiple matches for a field? +----------------------------------------------------- + +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. + +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'. + +How can I import a many2many relationship field (e.g. a customer that has multiple tags)? +----------------------------------------------------------------------------------------- + +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. + +`CSV file for Manufacturer, Retailer <../../_static/example_files/m2m_customers_tags.csv>`_. + +How can I import a one2many relationship (e.g. several Order Lines of a Sales Order)? +------------------------------------------------------------------------------------- + +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 addtional 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. + +`File for some Quotations <../../_static/example_files/purchase.order_functional_error_line_cant_adpat.csv>`_. + +The following CSV file shows how to import purchase orders with their respective +purchase order lines: + +`Purchase orders with their respective purchase order lines <../../_static/example_files/o2m_purchase_order_lines.csv>`_. + +The following CSV file shows how to import customers and their respective +contacts: + +`Customers and their respective contacts <../../_static/example_files/o2m_customers_contacts.csv>`_. + +Can I import several times the same record? +------------------------------------------- + +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 usefull 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. + +This feature allows you to use the Import/Export tool of Odoo to modify a batch +of records in your favorite spreadsheet application. + +What happens if I do not provide a value for a specific field? +-------------------------------------------------------------- + +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. + +How to export/import different tables from an SQL application to Odoo? +---------------------------------------------------------------------- + +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). + +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 accoss 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') + +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 +`dump <../../_static/example_files/database_import_test.sql>`_ of such a +PostgreSQL database) + +We will 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:: + + External ID,Name,Is a Company + company_1,Bigees,True + 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: + +.. 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:: + + External ID,Name,Is a Company,Related Company/External ID + person_1,Fabien,False,company_1 + person_2,Laurence,False,company_1 + 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 orignial 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. \ No newline at end of file