Pick Service Request
********************

This type of service request is used for picking inventory out of the butler
system.

Pick Request Lifecycle
======================

.. mermaid::

   graph TD
       A[created] --> |Inventory available and blocked| B[fulfillable]
       B --> |First rack reached| C[cancellation_locked]
       C --> |First pick transaction done| D[pick_started]
       D --> |Pick transactions| D
       D --> |All picks done| E[complete]
       A --> |Inventory not available| F[not_fulfillable]
       A --> |Cancel API call| G[cancelled]
       B --> |Cancel API call| G
       D --> |Partially complete due to<br/>inventory missing| H[abandoned]

       class E node-success
       class F node-failure
       class G node-failure
       class H node-failure

Create a Pick Request
=====================

.. todo:: Write about expectation format

.. http:post:: /api-gateway/sr-service/platform-srms/service-request

   To create a new pick service request, a :ref:`Service Request Object` should
   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.

   Pick requests should have the :gm:data:`serviceRequest.type` parameter set to
   ``PICK``.

   :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/sr-service/platform-srms/service-request HTTP/1.1
         Host: example.com
         Content-Type: application/json
         Accept: application/json, text/javascript

      .. literalinclude:: pick/create_pick_request.json
         :language: JSON

   .. container:: toggle

      .. container:: header

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

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

      .. literalinclude:: pick/create_pick_response.json
         :language: JSON


Cancel a Pick Request
=====================

.. http:post:: /api-gateway/sr-service/platform-srms/service-request/cancel

   A Pick request can only be modified or cancelled before the
   ``cancellation_locked`` state. Please consult the :ref:`Pick Request
   Lifecycle` for details.

   Pick cancellation works asynchronously. So, this API accepts the request, and
   generates a success or failure notification according to the result.

   .. seealso:: :ref:`Cancelled and Modified Notification`

   .. todo:: Write about full vs partial cancellation

   :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

   :<json string externalServiceRequestId: :gm:data:`serviceRequest.externalServiceRequestId`
                                           to be cancelled
   :<json string type: Should be equal to ``PICK``

   :>json int id: A unique transaction id for this request. The result
                  notification will have this transaction id for reference.
   :>json string externalServiceRequestId: :gm:data:`serviceRequest.externalServiceRequestId`
   :>json string type: ``PICK``

   :statuscode 202: The request has been accepted for processing
   :statuscode 400: Bad data

   .. container:: toggle

      .. container:: header

         **Example request**:

      .. sourcecode:: http

         POST /api-gateway/sr-service/platform-srms/service-request/cancel HTTP/1.1
         Host: example.com
         Content-Type: application/json
         Accept: application/json, text/javascript

      .. literalinclude:: pick/cancel_pick_request.json
         :language: JSON

   .. container:: toggle

      .. container:: header

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

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

      .. literalinclude:: pick/cancel_pick_response.json
         :language: JSON


Modify a Pick Request
=====================

.. http:post:: /api-gateway/sr-service/platform-srms/service-request/modify

   A Pick request can only be modified or cancelled before the
   ``cancellation_locked`` state. Please consult the :ref:`Pick Request
   Lifecycle` for details.

   Pick modification works asynchronously. So, this API accepts the request, and
   generates a success or failure notification according to the result.

   .. seealso:: :ref:`Cancelled and Modified Notification`

   :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

   :<json string externalServiceRequestId: :gm:data:`serviceRequest.externalServiceRequestId`
                                           to be modified
   :<json string type: Should be equal to ``PICK``
   :<json expectations: (Optional) Can be passed if expectation(s) of this
                        service request have to be modified.
   :<json serviceRequests: (Optional) Can be passed if child service request(s)
                           of this service request have to be modified.

   :>json int id: A unique transaction id for this request. The result
                  notification will have this transaction id for reference.
   :>json string externalServiceRequestId: :gm:data:`serviceRequest.externalServiceRequestId`
   :>json string type: ``PICK``

   :statuscode 202: The request has been accepted for processing
   :statuscode 400: Bad data

   .. container:: toggle

      .. container:: header

         **Example request**:

      .. sourcecode:: http

         POST /api-gateway/sr-service/platform-srms/service-request/modify HTTP/1.1
         Host: example.com
         Content-Type: application/json
         Accept: application/json, text/javascript

      .. literalinclude:: pick/modify_pick_request.json
         :language: JSON

   .. container:: toggle

      .. container:: header

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

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

      .. literalinclude:: pick/modify_pick_response.json
         :language: JSON

Pick Request Notifications
==========================

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

Fulfillable Notification
------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/fulfillable_notification.json
      :language: JSON

Cancellation Locked Notification
--------------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/cancellation_locked_notification.json
      :language: JSON

Pick Started Notification
-------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/pick_started_notification.json
      :language: JSON

Unfulfillable Notification
--------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/unfulfillable_notification.json
      :language: JSON

Abandoned Notification
----------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/abandoned_notification.json
      :language: JSON

Cancelled and Modified Notification
-----------------------------------

This notification is sent when a cancellation or modification request has been
processed.

Attributes in :gm:data:`notification.notification_data`:

* **id**: Transaction id of the cancellation/modification request for which this
  is a response.
* **state**: Status. Either ``success`` or ``failure``.

Sample Notification:

   .. container:: toggle

      .. container:: header

         Show/Hide

      .. literalinclude:: pick/cancelled_modified_notification.json
         :language: JSON


In case the cancellation or modification is successful, an additional
``order_information`` notification is generated:

   .. container:: toggle

      .. container:: header

         Order Information after cancellation

      .. literalinclude:: pick/cancelled_order_information_notification.json
         :language: JSON


Order Complete Notification
---------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/order_complete_notification.json
      :language: JSON

Bin Complete Notification
-------------------------

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/bin_complete_notification.json
      :language: JSON

Item Picked Notifications
-------------------------

This notification is sent whenever a pick transaction is done. The payload
contains the complete current state of the service request.

Some examples of different cases are shown below:

   .. container:: toggle

      .. container:: header
   
         Item Picked (K-Deep Containers)
      
      .. literalinclude:: pick/item_picked_kdeep_notification.json
         :language: JSON
   
   .. container:: toggle
   
      .. container:: header
   
         Item Picked (Eaches)
      
      .. literalinclude:: pick/item_picked_eaches_notification.json
         :language: JSON

   .. container:: toggle
   
      .. container:: header
   
         Item Picked (Tote Flow)
      
      .. literalinclude:: pick/item_picked_tote_flow_notification.json
         :language: JSON

   .. container:: toggle
   
      .. container:: header
   
         Item Picked (with Item Missing exception)
      
      .. literalinclude:: pick/item_picked_missing_notification.json
         :language: JSON