Product Management
******************

A product in butler system is the final entity uniquely identified by schema of
it's category or an overridden schema at the product level.

Products can be created without creating a parent category or catalog, however
it is advised otherwise.

Item Object
===========

..
   .. csv-table:: **Item Master Attributes**
      :file: item_object_attributes.csv
      :widths: auto
      :header-rows: 1

.. include:: item_object_attributes.inc.rst

                    
Item Object Sample JSON
-----------------------

.. literalinclude:: item_object.json
   :language: JSON

Item Config Object
==================

This object can be used to describe the storage levels for a product. For
example, if a product comes in a case of 10 eaches, then this metadata can be
stored in the product configuration so that the box dimensions, weight, and
other attributes don't have to be passed in each request.

Item config is defined as a recursive object. Each level defines the type,
barcode, quantity, and other attributes for that level.

.. list-table:: **Attributes**
   :widths: 30, 70

   * - | **levelType**
       | *autogenerated integer*
     - This is a unique id for this level

   * - | **label**
       | *required string*
     - Name of this storage level, like ``case``, ``pallet``, ``sub-pack``, etc.

   * - | **type**
       | *required string*
     - This is a string indicating the type of this level. Possible values:

       * ``marked``: Container with a barcode
       * ``unmarked``: Container without a barcode
       * ``virtual``: Not a container (i.e, an each)

   * - | **qty**
       | *required integer*
     - This denotes the quantity of objects in this level that is present in
       it's parent level. For root levels, this value must be 1.

       For example, for the configuration: "10 eaches in case", the quantity at
       case level would be 1, and at each level would be 10.

   * - | **barcode**
       | *optional list*
     - This is a list of barcode objects that uniquely identify this level. Each
       barcode in the barcode objects in this list must be globally unique for
       the whole system.

       It’s structure should be like this:

       .. code-block:: json

          {
              "barcode": [
                  {
                      "barcode": "case1_barcode"
                  }
              ]
          }

   * - | **attributes**
       | *required dict*
     - This is an object containing some metadata that is required, like weight
       and dimensions.

       .. todo:: Verify the structure and required fields

       ..
          .. code-block:: json

             {
                 "attributes": {
                     "weight": {
                         "uom": {
                             "unit": "KG"
                         },
                         "value": 1
                     },
                     "dimension": {
                         "uom": {
                             "unit": "CM"
                         },
                         "length": 24,
                         "width": 1,
                         "height": 7
                     }
                 }
             }

       .. list-table::
          :widths: 30, 70

          * - | **weight**
              | *required integer*
            - Weight of the level in the unit specified by :ref:`WeightUOM`.

              In case of containers (non-each levels), this should be the weight
              of the container box itself, excluding the weight of items inside
              it.

              In case of eaches, this value is ignored and the weight value is
              taken from the :ref:`Item Object`.

          * - | **length, width, height**
              | *required integers*
            - Dimensions of the level in the unit specified by
              :ref:`DimensionUOM`.

              In case of eaches, this value is ignored and the dimensions are
              taken from the :ref:`Item Object`.

          * - | **DimensionUOM**
              | *required string*
            - :abbr:`UOM (Unit of Measure)` for the dimensions.

              * MM - Millimeter
              * CM - Centimeter
              * M - Meter

          * - | **WeightUOM**
              | *required string*
            - :abbr:`UOM (Unit of Measure)` for the weight.

              * G - Gram
              * KG - Kilogram

          * - | **PkgUOM**
              | *required string*
            - Display name for this level

   * - | **level**
       | *optional list*
     - This is an optional list of child level objects to this level.


Item Config Object JSON
-----------------------

.. literalinclude:: item_config_object.json
   :language: json

Product Feature Attributes
==========================


Create or Update Items
======================

.. http:post:: /api-gateway/mdm-service/wms-masterdata/item

   To create or update a product, an :ref:`Item Object` has to be sent in a HTTP
   POST request to the above endpoint. The newly created or modified object will
   be returned in the response if the request is successful.

   :reqheader Content-Type: the request's content-type has to be passed in this
                            header
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: OAuth token to authenticate
   :statuscode 200: No error
   :statuscode 400: Bad data

   .. container:: toggle

      .. container:: header

         **Example request**:

      .. sourcecode:: http

         POST /api-gateway/mdm-service/wms-masterdata/item HTTP/1.1
         Host: example.com
         Content-Type: application/json
         Accept: application/json, text/javascript

      .. literalinclude:: item_object.json
         :language: JSON

   .. container:: toggle

      .. container:: header

         **Example Response**:
      
      .. sourcecode:: http

         HTTP/1.1 200 OK
         Content-Type: application/json;charset=UTF-8

      .. literalinclude:: item_object.json
         :language: JSON