[6265][ADD] base_import_match

base_import_match/README.rst

@@ -0,0 +1,207 @@
+=================
+Base Import Match
+=================
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:e971774f4ff82866d317ef5037fc912a4e405a3a426d497f692866b9f5532701
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |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-OCA%2Fserver--backend-lightgray.png?logo=github
+    :target: https://github.com/OCA/server-backend/tree/18.0/base_import_match
+    :alt: OCA/server-backend
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/server-backend-18-0/server-backend-18-0-base_import_match
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
+    :target: https://runboat.odoo-community.org/builds?repo=OCA/server-backend&target_branch=18.0
+    :alt: Try me on Runboat
+
+|badge1| |badge2| |badge3| |badge4| |badge5|
+
+By default, when importing data (like CSV import) with the
+``base_import`` module, Odoo follows this rule:
+
+-  If you import the XMLID of a record, make an **update**.
+-  If you do not, **create** a new record.
+
+This module allows you to set additional rules to match if a given
+import is an update or a new record.
+
+This is useful when you need to sync heterogeneous databases, and the
+field you use to match records in those databases with Odoo's is not the
+XMLID but the name, VAT, email, etc.
+
+After installing this module, the import preview UI adds a **Match**
+column. Checking the box on a field means:
+
+-  Use it to **find existing records** (match key).
+-  **Do not write** its value during the actual import.
+
+This lets you update records by matching on fields like name, email or
+VAT without needing an XMLID in your file.
+
+Pre-configured **Import Match** rules act as templates: their fields are
+pre-checked in the import preview. You can toggle any field on or off
+before importing, regardless of whether a rule exists.
+
+When match-only fields are selected in the UI, matching uses all
+selected fields together to search for a single existing record. If any
+row fails to match exactly one record (zero or multiple matches), the
+entire import is blocked and errors are shown for the affected rows.
+This prevents accidental creation of duplicate records.
+
+Note that conditional rules (fields with a required imported value) are
+only applied during programmatic imports; the UI-driven matching uses
+the selected fields unconditionally.
+
+For programmatic imports (without UI), the configured rules are used
+instead. The import logic in that case is:
+
+-  If you import the XMLID of a record, make an **update**.
+-  If you do not:
+
+   -  If there are import match rules for the model you are importing:
+
+      -  Discard the rules that require fields you are not importing.
+      -  Traverse the remaining rules one by one in order to find a
+         match in the database.
+
+         -  Skip the rule if it requires a special condition that is not
+            satisfied.
+         -  If one match is found:
+
+            -  Stop traversing the rest of valid rules.
+            -  **Update** that record.
+
+         -  If zero or multiple matches are found:
+
+            -  Continue with the next rule.
+
+         -  If all rules are exhausted and no single match is found:
+
+            -  **Create** a new record.
+
+   -  If there are no match rules for your model:
+
+      -  **Create** a new record.
+
+By default 2 rules are installed for production instances:
+
+-  One rule that will allow you to update companies based on their VAT,
+   when ``is_company`` is ``True``.
+-  One rule that will allow you to update users based on their login.
+
+In demo instances there are more examples.
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Configuration
+=============
+
+Import Match rules are optional templates that pre-check the **Match**
+column in the import preview. To configure them:
+
+1. Go to *Settings > Technical > Database Structure > Import Match*.
+2. *Create*.
+3. Choose a *Model*.
+4. Choose the *Fields* that conform a unique key in that model.
+5. If the rule must be used only for certain imported values, check
+   *Conditional* and enter the **exact string** that is going to be
+   imported in *Imported value*.
+
+   1. Keep in mind that the match here is evaluated as a case sensitive
+      **text string** always. If you enter e.g. ``True``, it will match
+      that string, but will not match ``1`` or ``true``.
+
+6. *Save*.
+
+In that list view, you can sort rules by drag and drop.
+
+Usage
+=====
+
+To use this module, you need to:
+
+1. Go to any list or kanban view.
+2. Go to *Action > Import records* and upload your file.
+3. In the import preview, check **Match** on the fields you want to use
+   as matching keys (e.g. name, email, VAT). These fields will be used
+   to find existing records but will not be written.
+4. Proceed with the import as usual. If any row cannot be matched to
+   exactly one existing record, the import will be blocked and error
+   messages will indicate which rows had zero or multiple matches.
+
+If Import Match rules are configured for the model, their fields will be
+pre-checked automatically.
+
+Known issues / Roadmap
+======================
+
+-  Add a setting to throw an error when multiple matches are found
+   during programmatic imports, instead of falling back to creation of
+   new record. (UI-driven imports already block on zero or multiple
+   matches.)
+-  Support matching on child record fields (one2many subfields) in the
+   import preview. Currently, matching only works for direct fields of
+   the imported model.
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-backend/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/OCA/server-backend/issues/new?body=module:%20base_import_match%0Aversion:%2018.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
+-------
+
+* Tecnativa
+
+Contributors
+------------
+
+-  `Tecnativa <https://www.tecnativa.com>`__:
+
+   -  Jairo Llopis
+   -  Vicent Cubells
+   -  Ernesto Tejeda
+
+-  `Quartile <https://www.quartile.co>`__:
+
+   -  Yoshi Tashiro
+
+Maintainers
+-----------
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+This module is part of the `OCA/server-backend <https://github.com/OCA/server-backend/tree/18.0/base_import_match>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

base_import_match/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2016 Grupo ESOC Ingeniería de Servicios, S.L.U. - Jairo Llopis
+# Copyright 2016 Tecnativa - Vicent Cubells
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html).
+
+from . import models

base_import_match/__manifest__.py

@@ -0,0 +1,27 @@
+# Copyright 2016 Grupo ESOC Ingeniería de Servicios, S.L.U. - Jairo Llopis
+# Copyright 2016 Tecnativa - Vicent Cubells
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html).
+{
+    "name": "Base Import Match",
+    "summary": "Try to avoid duplicates before importing",
+    "version": "18.0.1.0.0",
+    "category": "Tools",
+    "website": "https://github.com/OCA/server-backend",
+    "author": "Tecnativa, " "Odoo Community Association (OCA)",
+    "license": "AGPL-3",
+    "application": False,
+    "installable": True,
+    "depends": ["base_import"],
+    "data": [
+        "security/ir.model.access.csv",
+        "data/base_import_match.xml",
+        "views/base_import_match_view.xml",
+    ],
+    "demo": ["demo/base_import_match.xml"],
+    "assets": {
+        "web.assets_backend": [
+            "base_import_match/static/src/**/*.js",
+            "base_import_match/static/src/**/*.xml",
+        ],
+    },
+}

base_import_match/data/base_import_match.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!-- Copyright 2016 Grupo ESOC Ingeniería de Servicios, S.L.U. - Jairo Llopis
+     Copyright 2016 Tecnativa - Vicent Cubells
+     License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html). -->
+<odoo noupdate="1">
+    <!-- Match partners by VAT when is_company is True -->
+    <record model="base_import.match" id="res_partner_vat">
+        <field name="model_id" eval="ref('base.model_res_partner')" />
+        <field name="sequence" type="int">10</field>
+    </record>
+    <record model="base_import.match.field" id="res_partner_vat_vat">
+        <field name="match_id" ref="base_import_match.res_partner_vat" />
+        <field name="field_id" ref="base.field_res_partner__vat" />
+    </record>
+    <record model="base_import.match.field" id="res_partner_vat_is_company">
+        <field name="match_id" ref="base_import_match.res_partner_vat" />
+        <field name="field_id" ref="base.field_res_partner__is_company" />
+        <field name="conditional">True</field>
+        <field name="imported_value">True</field>
+    </record>
+    <!-- Match users by login -->
+    <record model="base_import.match" id="res_users_login">
+        <field name="model_id" eval="ref('base.model_res_users')" />
+        <field name="sequence" type="int">50</field>
+    </record>
+    <record model="base_import.match.field" id="res_users_login_login">
+        <field name="match_id" ref="base_import_match.res_users_login" />
+        <field name="field_id" ref="base.field_res_users__login" />
+    </record>
+</odoo>

base_import_match/demo/base_import_match.xml

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!-- Copyright 2016 Grupo ESOC Ingeniería de Servicios, S.L.U. - Jairo Llopis
+     Copyright 2016 Tecnativa - Vicent Cubells
+     License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html). -->
+<odoo noupdate="1">
+    <!-- Match partners by name, parent_id and is_company -->
+    <record model="base_import.match" id="res_partner_parent_name_is_company">
+        <field name="model_id" eval="ref('base.model_res_partner')" />
+        <field name="sequence" type="int">20</field>
+    </record>
+    <record
+        model="base_import.match.field"
+        id="res_partner_parent_name_is_company_name"
+    >
+        <field name="match_id" ref="res_partner_parent_name_is_company" />
+        <field name="field_id" ref="base.field_res_partner__name" />
+    </record>
+    <record
+        model="base_import.match.field"
+        id="res_partner_parent_name_is_company_parent"
+    >
+        <field name="match_id" ref="res_partner_parent_name_is_company" />
+        <field name="field_id" ref="base.field_res_partner__parent_id" />
+    </record>
+    <record
+        model="base_import.match.field"
+        id="res_partner_parent_name_is_company_is_company"
+    >
+        <field name="match_id" ref="res_partner_parent_name_is_company" />
+        <field name="field_id" ref="base.field_res_partner__is_company" />
+    </record>
+    <!-- Match partner by email -->
+    <record model="base_import.match" id="res_partner_email">
+        <field name="model_id" eval="ref('base.model_res_partner')" />
+        <field name="sequence" type="int">30</field>
+    </record>
+    <record model="base_import.match.field" id="res_partner_email_email">
+        <field name="match_id" ref="base_import_match.res_partner_email" />
+        <field name="field_id" ref="base.field_res_partner__email" />
+    </record>
+    <!-- Match partner by name -->
+    <record model="base_import.match" id="res_partner_name">
+        <field name="model_id" eval="ref('base.model_res_partner')" />
+        <field name="sequence" type="int">40</field>
+    </record>
+    <record model="base_import.match.field" id="res_partner_name_name">
+        <field name="match_id" ref="base_import_match.res_partner_name" />
+        <field name="field_id" ref="base.field_res_partner__name" />
+    </record>
+</odoo>