[ADD] base_import FAQ

_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

_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

_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
+--
+

_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

_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

_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

_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

applications.rst

@@ -15,5 +15,6 @@ Applications
    project
    getting_started/documentation
    website
+   general
 ..   expenses
 ..   recruitment

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 = []

general.rst

@@ -0,0 +1,8 @@
+=======
+General
+=======
+
+.. toctree::
+   :titlesonly:
+
+   general/base_import

general/base_import.rst

@@ -0,0 +1,8 @@
+===========
+BASE IMPORT
+===========
+
+.. toctree::
+   :titlesonly:
+
+   base_import/import_faq

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</a>)
+
+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.