Put Service Request
*******************

This type of service request is used for inventory inbound into the butler
system.

Put Request Lifecycle
=====================

.. mermaid::

   graph TD
       A[created] --> |Stage API Call| B[stage_requested]
       B --> |Stage successful| C[staged]
       A --> |Put back stage operation| C
       C --> |Put transactions| C1{Finished?}
       C1 --> |No| C
       C1 --> |Yes| D[complete]
       D --> |Tote/Roll cage released| E[released]
       A --> |Cancelled from API| F[cancelled]

       class D node-success
       class E node-success
       class F node-failure

Create a Put Request
====================

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

   To create a new put 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.

   Put requests should have the :gm:data:`serviceRequest.type` parameter set to
   ``PUT``.

   :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:: put/create_put_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:: put/create_put_response.json
         :language: JSON

Stage a Put Request
===================

A put request can either be staged manually by an operator at a put station, or
can be automatically staged via some hardware integration. In case of hardware
integration, GreyMatter provides an API to stage the put request in our system
which triggers the put calculation and brings MSUs to the station.

.. seealso:: :ref:`Put Staging Notifications`

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

   :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 serviceRequestId:
          :gm:data:`serviceRequest.externalServiceRequestId` of the
          :ref:`Service Request Object` referring to the payload being staged.
          The following conditions must be true for this to succeed:

          * The :gm:data:`serviceRequest.expectations` object must contain only
            one container
          * The container must have only one product in the
            :gm:data:`container.products` list
          * The ``productAttributes`` of the product inside the container must
            resolve to only one :ref:`Item Object` in MDM.

   :<json string ppsId: The PPS Id where stage action has to be performed. This
                        PPS must be in put mode, and must be logged in to
                        (unless staging is allowed with logout in the
                        configuration).

   :<json string ppsBinId: The bin id where stage has to be performed. This bin
                           must be empty for stage to succeed.

   :statuscode 200: Stage success
   :statuscode 400: Stage failure due to incorrect or invalid data
   :statuscode 409: Stage failure due to a conflict in SRMS

   **Example request**:

   .. sourcecode:: http

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

      {
          "serviceRequestId": "PUT-123",
          "ppsId": "3",
          "ppsBinId": "1"
      }

   **Example Response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK


Cancel a Put Request
====================

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

   A Put request can only be modified or cancelled when it is in ``CREATED``
   state. Please consult the :ref:`Put Request Lifecycle` for details.

   This is a synchronous request. The response will tell if the cancellation
   failed or succeeded.

   :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 ``PUT``

   :>json int id: A unique transaction id for this request.

   :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:: put/cancel_put_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:: put/cancel_put_response.json
         :language: JSON


Modify a Put Request
====================

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

   A Put request can only be modified or cancelled when it is in ``CREATED``
   state. Please consult the :ref:`Put Request Lifecycle` for details.

   This is a synchronous request. The response will tell if the modification
   failed or succeeded.

   :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 ``PUT``
   :<json attributes: (optional) Can be passed if attribute(s) have to be
                      modified.
   :<json expectations: (optional) Can be passed if expectation(s) have to be
                        modified.

   :>json int id: A unique transaction id for this request.

   :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:: put/modify_put_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:: put/modify_put_response.json
         :language: JSON

Put Request Notifications
=========================

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


Put Complete Notification
-------------------------

This notification is generated when put is complete for the expectation. This
notification has the consolidated data for all successful and unsuccessful
transactions in the put process for a service request.

The payload for this notification has the complete :ref:`Service Request Object`
with all transactions populated as :gm:data:`container`\ s in the
:gm:data:`serviceRequest.actuals` attribute.

.. container:: toggle

   .. container:: header

      **Sample JSON**:
   
   .. literalinclude:: put/put_complete_notification.json
      :language: JSON


Put Exception Notifications
---------------------------

These notifications are generated whenever there is any user or system generated
exception in the put process flow. It is usually not necessary to subscribe to
these notifications because the final put complete notifications contain details
about all exceptions that occurred in that service request.

.. list-table::
   :header-rows: 1
   :widths: 30, 15, 55

   * - Exception
     - Location
     - Sample JSON

   * - Item Unscannable
     - Put Back
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/item_unscannable_put_back_notification.json
             :language: JSON

   * - Physically Damaged
     - Put Back
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/physically_damaged_put_back_notification.json
             :language: JSON

   * - Item Oversized
     - Put Back
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/item_oversized_put_back_notification.json
             :language: JSON

   * - Extra Items
     - Put Back
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/extra_items_put_back_notification.json
             :language: JSON

   * - Warehouse Full
     - Put Back
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/warehouse_full_put_back_notification.json
             :language: JSON

   * - Physically Damaged
     - Put Front
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/physically_damaged_put_front_notification.json
             :language: JSON

   * - Unscannable / Missing
     - Put Front
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/unscannable_missing_put_front_notification.json
             :language: JSON

   * - Extra Items
     - Put Front
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/extra_items_put_front_notification.json
             :language: JSON

   * - Warehouse Full
     - Put Front
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/warehouse_full_put_front_notification.json
             :language: JSON

   * - Space Unavailable
     - Put Front
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/space_unavailable_put_front_notification.json
             :language: JSON


Put Staging Notifications
-------------------------

In the cases when put process' staging is controlled via API (instead of
manually), these extra notifications can be generated.

.. list-table::
   :header-rows: 1
   :widths: 30, 70

   * - Event
     - Sample JSON

   * - Staging Success
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/staging_success_notification.json
             :language: JSON

   * - Staging Failure
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide

          .. warning:: Note that ``status`` field does not come in this
                       notification
          
          .. literalinclude:: put/staging_failure_notification.json
             :language: JSON

   * - Staging Cancelled
     - .. container:: toggle
       
          .. container:: header
       
             Show/Hide
          
          .. literalinclude:: put/staging_cancelled_notification.json
             :language: JSON