[IMP] barcode: add nomenclature example

closes odoo/documentation#10458

X-original-commit: 16537bb9c5
Signed-off-by: Felicia Kuan (feku) <feku@odoo.com>
Co-authored-by: ksc-odoo <73958186+ksc-odoo@users.noreply.github.com>
Co-authored-by: Sam Lieber (sali) <36018073+samueljlieber@users.noreply.github.com>

content/applications/inventory_and_mrp/barcode/operations/barcode_nomenclature.rst

@@ -12,111 +12,139 @@ scanned, it is associated to the **first** rule with a matching pattern. The pat
 described in Odoo's nomenclature list using a regular expression, and a barcode is successfully read
 by Odoo if its prefix and/or length matches the one defined in the barcode's rule.
 
-Odoo *Barcode* supports UPC (Universal Product Code), EAN (European Article Number), and GS1
-encoding. The pre-configured nomenclatures in Odoo are *Default Nomenclature* and *Default GS1
-Nomenclature*. The default nomenclature uses |UPC| and |EAN| encoding, and supports |UPC|/|EAN|
-conversion.
+For instance, at a :doc:`Point of Sale <../../../sales/point_of_sale>` station, product weight
+barcodes in the European Article Number (EAN) format, which begin with `21` and have five digits
+specifying the weight, are used to weigh products and generate a barcode depicting the weight and
+price. The `21` and five-digit weight is the barcode pattern used to identify the barcode and can be
+customized to ensure Odoo correctly interprets all barcodes for the business.
+
+.. note::
+   Barcodes are also commonly used with Odoo's **Inventory** and **Barcode** apps.
+
+Odoo **Barcode** supports |EAN|, Universal Product Code (UPC), and :doc:`GS1 <gs1_nomenclature>`
+formats. This document exclusively focuses on :ref:`default rules and patterns in Odoo
+<barcode/operations/default-nomenclature-list>`, which use |UPC| and |EAN| encoding.
 
 .. important::
-   |UPC| and |EAN| barcodes **must** be `purchased from GS1
-   <https://www.gs1.org/standards/get-barcodes>`_ to use these barcodes. GS1 is the **only**
-   official provider of |UPC|/|EAN| and GS1 |GTINs| in the world.
+   To use |UPC| and |EAN| barcodes for uniquely identifying products across the entire supply chain,
+   they **must** be `purchased from GS1 <https://www.gs1.org/standards/get-barcodes>`_.
 
-.. _barcode/operations/set-up-nomenclature:
+   In Odoo, custom barcode patterns can be defined to recognize barcodes specific to the company.
+   Barcodes do not need to be purchased if used only within the company, such as in the
+   :ref:`example <barcode/operations/product-weight>` where the barcode is written in the |EAN|
+   format.
 
-Set up barcode nomenclature
-===========================
+Configuration
+=============
 
 To use default nomenclature, navigate to :menuselection:`Inventory app --> Configuration -->
-Settings`. Under the :guilabel:`Barcode` section, click the checkbox next to :guilabel:`Barcode
-Scanner` to enable barcodes. Doing so installs the *Barcode* app in the database.
+Settings`. Under the :guilabel:`Barcode` section, tick the :guilabel:`Barcode Scanner` checkbox.
+Doing so installs the **Barcode** app in the database.
 
-Next, ensure that the :guilabel:`Default Nomenclature` setting is selected in the :guilabel:`Barcode
-Nomenclature` field. Then, click :guilabel:`Save`.
+Next, in the :guilabel:`Barcode Nomenclature` field, ensure :guilabel:`Default Nomenclature` is
+selected. Then, click :guilabel:`Save`.
 
-.. image:: barcode_nomenclature/barcode-nomenclature-enabled-setting.png
+.. image:: barcode_nomenclature/enable-nomenclature.png
    :align: center
    :alt: Enabled barcode setting with Default Nomenclature selected.
 
-Once the nomenclature is saved and selected, the :menuselection:`Barcode Nomenclatures` settings can
-be accessed, via a hidden menu that is **only** discoverable after enabling :ref:`developer mode
-<developer-mode>`.
+With the **Barcode** module installed, and the :guilabel:`Default Nomenclature` selected, the
+barcode actions using |UPC| and |EAN|, detailed in the :ref:`default nomenclature list
+<barcode/operations/default-nomenclature-list>`, are available for use. And, by default, Odoo
+automatically handles |UPC|/|EAN| conversion.
 
-Once developer mode is enabled, navigate to :menuselection:`Inventory app --> Configuration -->
-Barcode Nomenclatures` menu, and select :guilabel:`Default Nomenclature`.
+.. _barcode/operations/product-weight:
 
-From this page, the :guilabel:`Barcode Nomenclature` is specified at the top as the `Default
-Nomenclature`.
+Example: product weight barcode
+===============================
 
-Under that, the :guilabel:`UPC/EAN Conversion` field is set to :guilabel:`Always`, by default. This
-setting determines if a |UPC|/|EAN| barcode should be automatically converted one way or another
-when trying to match a rule with the other encoding.
+To better understand how barcode nomenclature is used to identify products in Odoo, this example
+where product weight barcodes in |EAN| format are used to allow a :doc:`Point of Sale
+<../../../sales/point_of_sale>` business to automatically print barcodes, and calculate the price
+using the weight of the item.
 
-The other available options for this field are :guilabel:`Never`, :guilabel:`EAN-13 to UPC-A`, and
-:guilabel:`UPC-A to EAN-13`.
+To set up barcodes for weighted products, the following rule is used:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Rule Name
+     - Barcode Pattern
+     - Field in Odoo
+   * - Weighted Barcodes 3 Decimals
+     - (21)....{NNDDD}
+     - :guilabel:`Barcode` field on product form
+
+.. example::
+   To better understand the barcode pattern for weighted products, consider the barcode,
+   `2112345000008`:
+
+   - `21`: code that identifies this a barcode for weighted products.
+   - `12345`: five digits (denoted by `.....` in the table above) that identify the product.
+   - `00000`: five digits (denoted by `{NNDDD}` in the table) representing the weight of the
+     product. On the product form, the five weight values **must** be `00000`. The first two digits
+     are whole number values, and the last three digits are decimal values. For example, "13.5
+     grams" in the `{NNDDD}` format is `13500`.
+   - `8`: `check digit <https://www.gs1.org/services/check-digit-calculator>`_ for `211234500000`.
+
+   Together, these components make up a 13-character |EAN| - 13 barcode.
+
+To configure the product barcode for `Pasta Bolognese`, the |EAN| barcode for weighted products,
+`2112345000008`, is entered in the :guilabel:`Barcode` field on the product form (accessible by
+going to :menuselection:`Inventory app --> Products --> Products`, and selecting the desired
+product). In addition, the :guilabel:`Unit of Measure` is set to :guilabel:`kg`.
+
+.. image:: barcode_nomenclature/barcode.png
+   :align: center
+   :alt: Barcode field on the product form.
+
+Next, a customer's bowl of pasta is weighed to be `1.5` kilograms. This generates a new barcode for
+the pasta, according to the weight: `211234501500`, which has a check digit of `2`. The new barcode
+is `2112345015002`.
+
+.. image:: barcode_nomenclature/weighted-barcode.png
+   :align: center
+   :alt: Generated barcode that includes a weight of 1.5 kg.
+
+Ensure the products scan properly, by navigating to the :menuselection:`Barcode app --> Operations`.
+Next, click any operation type, such as :guilabel:`Receipts`. Then, click the :guilabel:`New` button
+to create a draft stock move. Scan the product weight barcode, such as `2112345015002`, and if the
+intended product appears, the barcode setup is correct.
+
+.. image:: barcode_nomenclature/barcode-scan.png
+   :align: center
+   :alt: Show successfully scanned barcode.
+
+Create rules
+============
 
 .. important::
-   For |UPC|/|EAN| conversion to work for every barcode scanned, the setting in the
-   :guilabel:`UPC/EAN Conversion` field **must** be set to :guilabel:`Always`.
+   Adding new rules is necessary for |UPC| and |EAN| formats that are **not** in Odoo's default
+   list, since barcodes cannot be read successfully if there are unknown fields.
 
-The last field at the top of the page is the :guilabel:`Is GS1 Nomenclature` field. For the
-:guilabel:`Default Nomenclature`, this field should remain unchecked. This is because the
-:guilabel:`Default Nomenclature` uses |UPC| and |EAN| encoding, *not* GS1 encoding.
+    While new rules can be created, Odoo fields do **not** auto-populate with information from these
+    rules. `Custom development <https://www.odoo.com/appointment/132>`_ is required for this
+    functionality.
 
-.. image:: barcode_nomenclature/barcode-nomenclature-page-fields.png
+To create a rule, first enable :ref:`developer mode <developer-mode>`. Then, navigate to
+:menuselection:`Inventory app --> Configuration --> Barcode Nomenclatures`, and select
+:guilabel:`Default Nomenclature`.
+
+On this page, configure the following optional fields:
+
+- :guilabel:`UPC/EAN Conversion`: determines if a |UPC|/|EAN| barcode should be automatically
+  converted when matching a rule with another encoding. Options include :guilabel:`Always` (the
+  default option), :guilabel:`Never`, :guilabel:`EAN-13 to UPC-A`, and :guilabel:`UPC-A to EAN-13`.
+- :guilabel:`Is GS1 Nomenclature`: ensure this checkbox is **not** ticked, as the
+  :guilabel:`Default Nomenclature` uses |UPC| and |EAN| encoding, *not* GS1 encoding.
+
+.. image:: barcode_nomenclature/rule-config.png
    :align: center
    :alt: Default Nomenclature page setting fields.
 
-Further down the page, there is a list showcasing the :guilabel:`Rule Name`, :guilabel:`Type`,
-:guilabel:`Encoding`, and :guilabel:`Barcode Pattern` for the *rules* and *barcode patterns* that
-Odoo supports for the default nomenclature.
-
-The :ref:`default nomenclature list <barcode/operations/default-nomenclature-list>` contains all the
-information that can be condensed with a |UPC|/|EAN| barcode.
-
-.. _barcode/operations/use-upc-ean-barcodes:
-
-Use UPC/EAN barcodes in Odoo
-============================
-
-For product identification using |UPC|/|EAN| barcodes in Odoo, businesses **must** obtain `barcodes
-<https://www.gs1us.org/upcs-barcodes-prefixes/how-to-get-a-upc-barcode>`_ purchased directly from
-GS1.
-
-The |UPC| and |EAN| barcode formats are predominantly used in their own regions. |UPC| is used only
-in the United States and Canada, while |EAN| is used everywhere else globally.
-
-A |UPC| is usually a 12-digit barcode used to identify most products, while |EAN| barcodes use
-13-digit barcodes to identify products.
-
-|UPC| codes can be converted to |EAN| by prefixing them with a zero. In Odoo, by default,
-|UPC|/|EAN| barcodes are automatically converted one way or another when trying to match a rule with
-the other encoding.
-
-Refer to the :ref:`default nomenclature list <barcode/operations/default-nomenclature-list>` to see
-a comprehensive list of all barcode patterns and rules to follow.
-
-Create rules
-------------
-
-|UPC| and |EAN| barcodes contain specific information in the barcode. Scanning these codes from the
-:ref:`default nomenclature list <barcode/operations/default-nomenclature-list>` automatically fills
-corresponding data in the Odoo database.
-
-Adding new barcode rules to this list ensures that non-standard (:dfn:`user-created`) formats are
-interpreted accurately.
-
-To create new rules, first activate :ref:`developer mode <developer-mode>`. Then, navigate to
-:menuselection:`Inventory app --> Configuration --> Barcode Nomenclatures`. Select the
-:guilabel:`Default Nomenclature` list item.
-
-On the :guilabel:`Default Nomenclature` page, select :guilabel:`Add a line` at the bottom of the
+On the :guilabel:`Default Nomenclature` page, click :guilabel:`Add a line` at the bottom of the
 table, which opens a :guilabel:`Create Rules` pop-up window to create a new rule.
 
-.. image:: barcode_nomenclature/barcode-nomenclature-new-rule-popup.png
-   :align: center
-   :alt: Create Rules pop-up window on Default Nomenclature page.
-
 The :guilabel:`Rule Name` field is used internally to identify what the barcode represents.
 
 The :guilabel:`Sequence` field represents the priority of the rule; meaning the smaller the value,
@@ -126,31 +154,23 @@ The barcode :guilabel:`Type` field represents different classifications of infor
 understood by the system (e.g., :guilabel:`Package`, :guilabel:`Lot`, :guilabel:`Location`,
 :guilabel:`Coupon`, etc.).
 
-The :guilabel:`Encoding` field specifies which encoding the barcode uses; this rule **only** applies
+The :guilabel:`Encoding` field specifies which encoding the barcode uses. This rule **only** applies
 if the barcode uses this specific encoding. The available :guilabel:`Encoding` options are:
 :guilabel:`EAN-13`, :guilabel:`EAN-8`, :guilabel:`UPC-A`, and :guilabel:`GS1-28`.
 
 The :guilabel:`Barcode Pattern` field represents how the sequence of letters or numbers is
-recognized by the system to contain information about the product. Odoo follows the sequential order
-of this table, and uses the first rule it matches, based on the sequence.
+recognized by the system to contain information about the product. Sometimes, when a certain amount
+of digits are required, the number of `.` is shown. `N` represents whole number digits, and `D`
+represent decimal digits.
 
-.. note::
-   Barcode patterns can also define how numerical values, such as weight or price, are encoded in
-   the barcode.
-
-   They are indicated by **{NNN}**, where `N` defines where the number's digits are encoded.
-   *Floats* are also supported with the decimals, indicated by `D`, such as **{NNNDD}**.
-
-   In this case, the barcode field on the associated records **must** show these digits as zeros.
+.. example::
+   `1...` represents any 4-digit number that starts with 1. `NNDD` represents a two digit number
+   with two decimal points. For example, `14.25` is 1425.
 
 After filling in the information, click the :guilabel:`Save & New` button to save the rule, and
 instantly start creating another rule. Or, click :guilabel:`Save & Close` to save the rule, and
 return to the table of rules.
 
-.. tip::
-   When the :guilabel:`Barcode Pattern` field contains `.*`, it means it can contain **any** number
-   of characters - those characters being **any** number or type of character.
-
 .. _barcode/operations/default-nomenclature-list:
 
 Default nomenclature list
@@ -212,5 +232,9 @@ written in regular expressions.
      - Any
      - .*
 
+.. note::
+   When the :guilabel:`Barcode Pattern` contains `.*`, it means it can contain any number or type of
+   characters.
+
 .. seealso::
    :doc:`gs1_nomenclature`