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

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

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

.. todo:: Have to write this.

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 :js:data:`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.

   .. todo:: Find out more details about 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: :js:data:`externalServiceRequestId`
                                           to be cancelled

   :<json string type: Should be equal to ``PICK``

   :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/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.

   :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/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
:js:data:`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.

It contains a single ``state`` variable in it's :js:data:`notification_data`
that contains either ``success`` or ``failure``.

.. todo:: Confirm pick cancellation / modification failure notification

.. container:: toggle

   .. container:: header

      Show/Hide
   
   .. literalinclude:: pick/cancelled_modified_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