Metadata-Version: 2.1
Name: odoo14-addon-pattern_import_export
Version: 14.0.2.9.1.dev1
Summary: Pattern for import or export
Home-page: https://github.com/Shopinvader/pattern-import-export
Author: Akretion
License: AGPL-3
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 14.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Requires-Python: >=3.6
Requires-Dist: odoo14-addon-base-export-manager
Requires-Dist: odoo14-addon-base-sparse-field-list-support
Requires-Dist: odoo14-addon-jsonifier
Requires-Dist: odoo14-addon-queue-job
Requires-Dist: odoo14-addon-web-notify
Requires-Dist: odoo<14.1dev,>=14.0a

=====================
Pattern Import Export
=====================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:01355a156338896d1c216e8805a1548e324d8ee31eafd447b7f52727466e24a9
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-shopinvader%2Fpattern--import--export-lightgray.png?logo=github
    :target: https://github.com/shopinvader/pattern-import-export/tree/14.0/pattern_import_export
    :alt: shopinvader/pattern-import-export

|badge1| |badge2| |badge3|

Overview
~~~~~~~~

This module extends the import/export capabilities of Odoo.

Patterns are simply a type of ir.exports model, so you can define them with the native Odoo widget to define export lists.

This module only create a common data structure. Other modules will be used to add specific file type support like excel and csv.


Features
--------

* Key matching: instead of always using IDs, match keys to unique-constrained fields, for example update a product by
  specifying its product_code instead of its database ID or external ID

* One2many and Many2many support: create or update for example invoice lines with a syntax that is very readable and easy to update

* As long as you respect the appropriate format and field names, you are free to add/remove/rename columns, even if they
  are not in the initial Pattern used for the export

**Table of contents**

.. contents::
   :local:

Configuration
=============

* Install another module that supports a specific file type
* Use the Patterns menu to configure your import/export formats

Usage
=====

Configuring a pattern
~~~~~~~~~~~~~~~~~~~~~
First you have to define a pattern:

1. Go on the Import/Export->Patterns menu
2. Create your pattern with fields to export

You can refer to the examples in demo data.


Exporting
---------
* Open the tree view of any model and tick some record selection boxes.
* In the sidebar, click on the "Export with Pattern" button
* Select the pattern that you wish to use, click export and download the generated file.
* A "Pattern file" is created, and its job along with it. Depending on the success or failure of the job,
  you will receive a red/green notification on your window.


Importing
---------
You have two options:

* Open the tree view of any model and tick some record selection boxes (for this step, these don't matter, we only just want to show the sidebar).
* In the sidebar, click on the "Import with Pattern" button
* Select a pattern, upload your file and click import.
* A "Pattern file" is created, and its job along with it. Depending on the success or failure of the job, you
  will receive a red/green notification on your window. You can check the details in the appropriate Import/Export menu.

Or:

* Access the Import wizard through the Import/Export menu
* Select a pattern
* Click on the "Import" button


Import syntax
-------------

One of the strength of pattern_import_export module is the ability to
reference records by natural keys (business keys) instead of technical keys (xmlid or database id).

One or more columns can be the natural key of the record to find and update or to create a new record.
Each column in the natural key has to be suffixed by "#key".

One or more columns can be used as foreign keys can be accessed with "|" syntax.  (for instance on partner: country_id|code )


Example
-------

Here is an example of a simple update on ``product.product``:
Existing record:

- id: 10
- name: "Product 1"
- default_code: "PRD1"

The generated export will look like:

+---------------------+-----------+--------------+
| id                  | name      | default_code |
+=====================+===========+==============+
| 10                  | Product 1 | PRD1         |
+---------------------+-----------+--------------+

Updated file

+---------------------+---------------+--------------+
| id                  | name          | default_code |
+=====================+===============+==============+
| 10                  | Product 1-bis | PRD1B        |
+---------------------+---------------+--------------+

After import, our record will have been updated:

- xml id: "__export__.product1"
- name: "Product 1-bis"
- default_code: "PRD1B"

Now, let's update some relational fields. Here is some more of our starting data:

- seller_ids:

 - id (of the seller_id which is a res.partner): 22
 - name (seller): Partner 1
 - price: 10

The generated export should be like

+---------------------+-----------+--------------+----------------------+--------------------+
| id                  | name      | default_code | seller_ids|1|id      | seller_ids|1|price |
+=====================+===========+==============+======================+====================+
| 10                  | Product 1 | PRD1         | 22                   | 10                 |
+---------------------+-----------+--------------+----------------------+--------------------+

Let's say "ref" is a unique-constrained Char field. For the seller, instead of using its id, let's use its ref.

+---------------------+-----------+--------------+---------------------------+--------------------+
| id                  | name      | default_code | seller_ids|1|ref#key      | seller_ids|1|price |
+=====================+===========+==============+===========================+====================+
| 10                  | Product 1 | PRD1         | partner1-ref              | 10                 |
+---------------------+-----------+--------------+---------------------------+--------------------+

So this ``#key`` means that Odoo should search for a ``res.partner`` where the ref matches the cell value.

Lets take another example, instead of using the id, we want to use the product's default_code as key.

+---------------------+-----------+------------------+---------------------------+--------------------+
| id                  | name      | default_code#key | seller_ids|1|ref#key      | seller_ids|1|price |
+=====================+===========+==================+===========================+====================+
|                     | Product 1 | PRD1             | partner1-ref              | 10                 |
+---------------------+-----------+------------------+---------------------------+--------------------+

Odoo will search the product with the matching ``default_code`` and update it.


Technically
~~~~~~~~~~~
Add a new export format
-----------------------
1. Inherit the ``ir.exports`` model.
2. Add your new file format in the selection field ``export_format``;
3. Implements functions ``_export_with_record_<format>`` and ``_read_import_data_<format>``.

Please take care of iterators (``yield``) to avoid loading full file into the system memory.

Known issues / Roadmap
======================

* Unticking the "Use tab" boolean should clear the previously selected tab_filter_id
* Changing a line's field should clear the previously selected tab_filter_id

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/shopinvader/pattern-import-export/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/shopinvader/pattern-import-export/issues/new?body=module:%20pattern_import_export%0Aversion:%2014.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
~~~~~~~

* Akretion

Contributors
~~~~~~~~~~~~

* Chafique Delli <chafique.delli@akretion.com>
* Sébastien Beau <sebastien.beau@akretion.com>
* François Honoré (ACSONE SA/NV) <francois.honore@acsone.eu>
* Kevin Khao <kevin.khao@akretion.com>
* Raphaël Reverdy <raphael.reverdy@akretion.com>

Maintainers
~~~~~~~~~~~

This module is part of the `shopinvader/pattern-import-export <https://github.com/shopinvader/pattern-import-export/tree/14.0/pattern_import_export>`_ project on GitHub.

You are welcome to contribute.
