Audit APIs
##########

GreyMatter allows performing inventory audits in which manual count of selected
inventory can be performed.

Audits can be created either from the Manager Dashboard or via API. But, they
can be started only from the Manager Dashboard.

Audit Lifecycle
***************

.. mermaid::

   graph TD
       A[created] --> |Start Audit from MD| B[processing_start]
       B --> C[auditlines_created]
       C --> |Ongoing operations on<br/>selected inventory/slot| D[waiting_on_conflict]
       C --> E[queued]
       D --> E
       E --> F[started]
       F --> |Some discrepancy found| G[pending_approval]
       F --> |No discrepancy| H[completed]
       G --> I[approved]
       G --> J[rejected]
       J --> K[sent_for_reaudit]
       Any --> L[cancelled]
       B --> |No matching<br/>inventory found| M[aborted]
       A --> N[deleted]
       Any --> O[paused]
       class G node-failure
       class H node-success
       class I node-success
       class J node-failure
       class K node-success
       class L node-success
       class M node-failure
       class N node-success

Audit Object
************

Audits can be of two types: location audit or SKU audit:

* In a location audit, a list of slots or MSUs are specified which have to be
  audited, and all inventory present in those slots are audited.
* In an SKU audit, product parameters are given, and all products matching those
  parameters are audited. All slots which have those products are brought to the
  audit station for this purpose.


.. js:data:: audit_id

   A unique auto-generated string that identifies the audit

.. js:data:: audit_param_name

   *required string, not unique*

   A string that will be displayed against the audit in manager dashboard

.. js:data:: audit_param_type

   Can be either ``location`` or ``sku``.

.. js:data:: audit_param_value

   .. js:data:: locations_list

      *In case of a location audit*
   
      A list of strings denoting locations (either slot ids or MSU ids)

      **Example**

      .. sourcecode:: json

         {
             "locations_list": [
                 "014",
                 "039",
                 "001",
                 "039.1.E.02",
                 "014.1.E.05"
             ]
         }

   .. js:data:: attributes_list

      *In case of SKU audit*

      A list of SKU selector objects. Each object has two properties: ``sku``
      and ``attributes_sets``.

      **Example**

      .. sourcecode:: json

         {
             "attributes_list": [{
                 "attributes_sets": [{
                     "product_color": [
                         "Green"
                     ]
                 }],
                 "sku": "3001"
             }]
         }


Creating an Audit
*****************

.. http:post:: /api-gateway/integration-service/wms-integration/butler/api/audit

   :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

   :>json string action: ``create``
   :>json string audit_creator_name: Optional string to denote who is creating
                                     the audit
   :>json string audit_param_name: Name of audit to be displayed on UI
   :>json string audit_param_type: Type of audit. ``location`` or ``sku``.
   :>json audit_param_value: An object of type :js:data:`audit_param_value`
   :>json bool kq: Should be ``true`` if keying in quantity is allowed during
                   audit

   .. container:: toggle

      .. container:: header

         **Example: Audit by Location**

      .. compound::

         Request

         .. sourcecode:: http

            POST /api-gateway/integration-service/wms-integration/butler/api/audit HTTP/1.1
            Host: example.com
            Content-Type: application/json
            Accept: application/json, text/javascript

         .. literalinclude:: create_audit_location_request.json
            :language: JSON

         Response

         .. sourcecode:: http

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

         .. literalinclude:: create_audit_location_response.json
            :language: JSON

   .. container:: toggle

      .. container:: header

         **Example: Audit by SKU**

      .. compound::

         Request

         .. sourcecode:: http

            POST /api-gateway/integration-service/wms-integration/butler/api/audit HTTP/1.1
            Host: example.com
            Content-Type: application/json
            Accept: application/json, text/javascript

         .. literalinclude:: create_audit_sku_request.json
            :language: JSON

         Response

         .. sourcecode:: http

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

         .. literalinclude:: create_audit_sku_response.json
            :language: JSON

Audit Notifications
*******************

All Audit notifications follow the generic notification format (see :ref:`Event
Notifications`), and contain the relevant payload in the
:js:data:`notification_data` attribute.

Audit notifications are generated for most :ref:`Audit Lifecycle` events.

Audit Created Notification
--------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: audit_created_notification.json
      :language: JSON

Auditlines Created Notification
-------------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: auditlines_created_notification.json
      :language: JSON

Waiting on Conflict Notification
--------------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: waiting_on_conflict_notification.json
      :language: JSON

Queued Notification
-------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: queued_notification.json
      :language: JSON

Started Notification
--------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: started_notification.json
      :language: JSON

Completed Notification
----------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: completed_notification.json
      :language: JSON

Pending Approval Notification
-----------------------------

.. container:: toggle

   .. container:: header

      Example with 1 auditline started and 1 pending approval
   
   .. literalinclude:: pending_approval_notification_1.json
      :language: JSON

.. container:: toggle

   .. container:: header

      Example with 1 auditline completed and 1 pending approval
   
   .. literalinclude:: pending_approval_notification_2.json
      :language: JSON

Rejected Notification
---------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: rejected_notification.json
      :language: JSON

Approved Notification
---------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: approved_notification.json
      :language: JSON

Sent for Re-audit Notification
------------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: sent_for_reaudit_notification.json
      :language: JSON

Cancelled Notification
----------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: cancelled_notification.json
      :language: JSON

Deleted Notification
--------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: deleted_notification.json
      :language: JSON

Aborted Notification
--------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: aborted_notification.json
      :language: JSON

.. todo:: Add Audit APIs for Delete