Warning: This document is for an old version of Grey Matter. The latest version is v10.1.0.

Put Service Request

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

Put Request Lifecycle

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

POST /api-gateway/sr-service/platform-srms/service-request

To create a new put service request, a 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 serviceRequest.type parameter set to PUT.

Request Headers:  

• Content-Type – the request’s content-type has to be passed in this header
• Accept – the response content type depends on Accept header
• Authorization – OAuth token to authenticate

Status Codes:

• 200 OK – No error
• 400 Bad Request – Bad data

Example request:

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

{
    "externalServiceRequestId": "PUT-001",
    "type": "PUT",
    "attributes": {
        "tote_id": "Tote1"
    },
    "expectations": {
        "containers": [{
            "products": [{
                "productQuantity": 30,
                "productAttributes": {
                    "pdfa_values": {
                        "product_sku": "MM00001"
                    }
                }
            }]
        }]
    }
}

Example Response:

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

{
    "id": 820,
    "externalServiceRequestId": "PUT-001",
    "serviceRequests": null,
    "type": "PUT",
    "actuals": null,
    "expectations": {
        "containers": [{
            "id": 709,
            "state": null,
            "type": "VIRTUAL",
            "barcode": null,
            "products": [{
                "id": 711,
                "uid": null,
                "uidType": null,
                "productQuantity": 30,
                "productAttributes": {
                    "pdfa_values": {
                        "product_sku": "MM00001"
                    }
                },
                "createdOn": "2018-04-24T10:30:04.026",
                "updatedOn": "2018-04-24T10:30:04.026"
            }],
            "containers": null,
            "containerAttributes": null,
            "createdOn": "2018-04-24T10:30:04.025",
            "updatedOn": "2018-04-24T10:30:04.025"
        }]
    },
    "receivedOn": "2018-04-24T05:00:04.018",
    "status": "CREATED",
    "state": "CREATED",
    "attributes": {
        "tote_id": "Tote1"
    },
    "createdOn": "2018-04-24T05:00:04.018",
    "updatedOn": "2018-04-24T05:00:04.018"
}

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.

See also

Put Staging Notifications

POST /api-gateway/integration-service/wms-integration/butler/api/stage_put_expectation

Request Headers:  

• Content-Type – the request’s content-type has to be passed in this header
• Accept – the response content type depends on Accept header
• Authorization – OAuth token to authenticate

Request JSON Object:  

• serviceRequestId (string) –

  serviceRequest.externalServiceRequestId of the Service Request Object referring to the payload being staged. The following conditions must be true for this to succeed:

  • The serviceRequest.expectations object must contain only one container
  • The container must have only one product in the container.products list
  • The productAttributes of the product inside the container must resolve to only one Item Object in MDM.
• ppsId (string) – 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).
• ppsBinId (string) – The bin id where stage has to be performed. This bin must be empty for stage to succeed.

Status Codes:

• 200 OK – Stage success
• 400 Bad Request – Stage failure due to incorrect or invalid data
• 409 Conflict – Stage failure due to a conflict in SRMS

Example request:

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:

HTTP/1.1 200 OK

Cancel a Put Request

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 Put Request Lifecycle for details.

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

Request Headers:  

• Content-Type – the request’s content-type has to be passed in this header
• Accept – the response content type depends on Accept header
• Authorization – OAuth token to authenticate

Request JSON Object:  

• externalServiceRequestId (string) – serviceRequest.externalServiceRequestId to be cancelled
• type (string) – Should be equal to PUT

Response JSON Object:  

• id (int) – A unique transaction id for this request.

Status Codes:

• 200 OK – No error
• 400 Bad Request – Bad data

Example request:

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

{
    "externalServiceRequestId": "PUT-001",
    "type": "PUT"
}

Example Response:

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

{
    "id": 2
}

Modify a Put Request

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 Put Request Lifecycle for details.

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

Request Headers:  

• Content-Type – the request’s content-type has to be passed in this header
• Accept – the response content type depends on Accept header
• Authorization – OAuth token to authenticate

Request JSON Object:  

• externalServiceRequestId (string) – serviceRequest.externalServiceRequestId to be modified
• type (string) – Should be equal to PUT
• attributes – (optional) Can be passed if attribute(s) have to be modified.
• expectations – (optional) Can be passed if expectation(s) have to be modified.

Response JSON Object:  

• id (int) – A unique transaction id for this request.

Status Codes:

• 200 OK – No error
• 400 Bad Request – Bad data

Example request:

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

{
    "externalServiceRequestId": "PUT-001",
    "type": "PUT",
    "attributes": {
        "tote_id": "Tote1"
    },
    "expectations": {
        "containers": [
            {
                "products": [
                    {
                        "productQuantity": 40,
                        "productAttributes": {
                            "pdfa_values": {
                                "product_sku": "MM00001"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

Example Response:

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

{
    "id": 3
}

Put Request Notifications

All Put Request notifications follow the generic notification format (see Event Notifications), and contain the relevant payload in the 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 Service Request Object with all transactions populated as containers in the serviceRequest.actuals attribute.

Sample JSON:

{
    "notification_type": "put_information",
    "version_number": "1.5.0",
    "notification_id": "unique_id_of_this_notification",
    "notification_data": {
        "status": "PROCESSED",
        "externalServiceRequestId": "04May1829",
        "updatedOn": "2018-05-14T18:02:55.934",
        "createdOn": "2018-05-14T18:02:46.925",
        "expectations": {
            "containers": [
                {
                    "updatedOn": "2018-05-14T23:32:46.925",
                    "createdOn": "2018-05-14T23:32:46.925",
                    "barcode": null,
                    "containerAttributes": null,
                    "state": null,
                    "products": [
                        {
                            "productQuantity": 10,
                            "updatedOn": "2018-05-14T23:32:46.926",
                            "createdOn": "2018-05-14T23:32:46.926",
                            "uidType": null,
                            "productAttributes": {
                                "pdfa_values": {
                                    "product_sku": "I1",
                                    "seller": "S1"
                                }
                            },
                            "id": 94,
                            "uid": null
                        }
                    ],
                    "type": "VIRTUAL",
                    "id": 98,
                    "containers": []
                }
            ]
        },
        "serviceRequests": [],
        "actuals": {
            "containers": [
                {
                    "updatedOn": null,
                    "createdOn": null,
                    "barcode": null,
                    "containerAttributes": {
                        "location": "003.1.A.01-A.02"
                    },
                    "state": "complete",
                    "products": [
                        {
                            "productQuantity": 10,
                            "updatedOn": null,
                            "createdOn": null,
                            "uidType": "ITEM_ID",
                            "productAttributes": {
                                "pdfa_values": {
                                    "product_sku": "I1",
                                    "seller": "S1"
                                }
                            },
                            "id": null,
                            "uid": "3"
                        }
                    ],
                    "type": "VIRTUAL",
                    "id": null,
                    "containers": null
                }
            ]
        },
        "state": "complete",
        "receivedOn": "2018-05-14T18:02:46.925",
        "attributes": {
            "pps_seat_name": "back_2",
            "pps_id": "2",
            "user_name": "admin",
            "tote_id": "cit24",
            "pps_bin_id": "1"
        },
        "type": "PUT",
        "id": 69
    }
}

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.

Exception	Location	Sample JSON
Item Unscannable	Put Back	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "externalServiceRequestId": "dummy_invoice_id", "state": "put_transaction", "actuals": { "containers": [{ "products": [{ "productQuantity": 9 }], "state": "back_unscannable", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "back_2" }, "type": "PUT" } }
Physically Damaged	Put Back	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "externalServiceRequestId": "dummy_invoice_id", "state": "put_transaction", "actuals": { "containers": [{ "products": [{ "productQuantity": 9, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "back_physically_damaged", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "back_2" }, "type": "PUT" } }
Item Oversized	Put Back	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "externalServiceRequestId": "dummy_invoice_id", "state": "put_transaction", "actuals": { "containers": [{ "products": [{ "productQuantity": 1, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "back_oversized_entities", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "back_2" }, "type": "PUT" } }
Extra Items	Put Back	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "externalServiceRequestId": "dummy_invoice_id", "state": "put_transaction", "actuals": { "containers": [{ "products": [{ "productQuantity": 9, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "back_excess_entities", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "back_2", "pps_bin_id" : "1" }, "type": "PUT" } }
Warehouse Full	Put Back	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "externalServiceRequestId": "16feb_02", "state": "complete", "status": "PROCESSED", "expectations": { "containers": [{ "id": 709, "state": null, "type": "VIRTUAL", "barcode": null, "products": [{ "id": 711, "uid": null, "uidType": null, "productQuantity": 30, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } }, "createdOn": "2018-04-24T10:30:04.026", "updatedOn": "2018-04-24T10:30:04.026" }], "containers": null, "containerAttributes": null, "createdOn": "2018-04-24T10:30:04.025", "updatedOn": "2018-04-24T10:30:04.025" }] }, "actuals": { "containers": [{ "products": [{ "productQuantity": 30, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "back_warehouse_full", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "back_2", "pps_bin_id" : "1" }, "type": "PUT" } }
Physically Damaged	Put Front	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "id": 123, "externalServiceRequestId": "16feb_02", "state": "put_transaction", "status": "PROCESSING", "expectations": { "containers": [{ "id": 709, "state": null, "type": "VIRTUAL", "barcode": null, "products": [{ "id": 711, "uid": null, "uidType": null, "productQuantity": 30, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } }, "createdOn": "2018-04-24T10:30:04.026", "updatedOn": "2018-04-24T10:30:04.026" }], "containers": null, "containerAttributes": null, "createdOn": "2018-04-24T10:30:04.025", "updatedOn": "2018-04-24T10:30:04.025" }] }, "actuals": { "containers": [{ "products": [{ "productQuantity": 1, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "front_physically_damaged", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "front_2" }, "type": "PUT" } }
Unscannable / Missing	Put Front	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "id": 123, "externalServiceRequestId": "16feb_02", "state": "put_transaction", "status": "PROCESSING", "expectations": { "containers": [{ "id": 709, "state": null, "type": "VIRTUAL", "barcode": null, "products": [{ "id": 711, "uid": null, "uidType": null, "productQuantity": 30, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } }, "createdOn": "2018-04-24T10:30:04.026", "updatedOn": "2018-04-24T10:30:04.026" }], "containers": null, "containerAttributes": null, "createdOn": "2018-04-24T10:30:04.025", "updatedOn": "2018-04-24T10:30:04.025" }] }, "actuals": { "containers": [{ "products": [{ "productQuantity": 1, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "front_missing", "type": "VIRTUAL", "containerAttributes": {} }, { "products": [{ "productQuantity": 1, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "front_unscannable", "barcode": null, "type": "VIRTUAL", "containerAttributes": {} } ] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "front_2" }, "type": "PUT" } }
Extra Items	Put Front	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "id": 123, "externalServiceRequestId": "16feb_02", "state": "put_transaction", "status": "PROCESSING", "expectations": { "containers": [{ "id": 709, "state": null, "type": "VIRTUAL", "barcode": null, "products": [{ "id": 711, "uid": null, "uidType": null, "productQuantity": 30, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } }, "createdOn": "2018-04-24T10:30:04.026", "updatedOn": "2018-04-24T10:30:04.026" }], "containers": null, "containerAttributes": null, "createdOn": "2018-04-24T10:30:04.025", "updatedOn": "2018-04-24T10:30:04.025" }] }, "actuals": { "containers": [{ "products": [{ "productQuantity": 9, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "front_excess_entities", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "front_2", "pps_bin_id" : "1" }, "type": "PUT" } }
Warehouse Full	Put Front	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "id": 123, "externalServiceRequestId": "16feb_02", "state": "put_transaction", "status": "PROCESSING", "expectations": { "containers": [{ "id": 709, "state": null, "type": "VIRTUAL", "barcode": null, "products": [{ "id": 711, "uid": null, "uidType": null, "productQuantity": 30, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } }, "createdOn": "2018-04-24T10:30:04.026", "updatedOn": "2018-04-24T10:30:04.026" }], "containers": null, "containerAttributes": null, "createdOn": "2018-04-24T10:30:04.025", "updatedOn": "2018-04-24T10:30:04.025" }] }, "actuals": { "containers": [{ "products": [{ "productQuantity": 9, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "front_warehouse_full", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "front_2", "pps_bin_id" : "1" }, "type": "PUT" } }
Space Unavailable	Put Front	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "id": 123, "externalServiceRequestId": "16feb_02", "state": "put_transaction", "status": "PROCESSING", "expectations": { "containers": [{ "id": 709, "state": null, "type": "VIRTUAL", "barcode": null, "products": [{ "id": 711, "uid": null, "uidType": null, "productQuantity": 30, "productAttributes": { "pdfa_values": { "product_sku": "41_test" } }, "createdOn": "2018-04-24T10:30:04.026", "updatedOn": "2018-04-24T10:30:04.026" }], "containers": null, "containerAttributes": null, "createdOn": "2018-04-24T10:30:04.025", "updatedOn": "2018-04-24T10:30:04.025" }] }, "actuals": { "containers": [{ "products": [{ "productQuantity": 9, "uid": "abcd", "productAttributes": { "pdfa_values": { "product_sku": "41_test" } } }], "state": "front_space_unavailable", "type": "VIRTUAL", "containerAttributes": {} }] }, "attributes": { "user_name": "system", "pps_id": "2", "pps_seat_name": "front_2" }, "type": "PUT" } }

Put Staging Notifications

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

Event	Sample JSON
Staging Success	Show/Hide { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "platform:[B@1392c667", "notification_data": { "state": "staged", "status": "PROCESSING", "externalServiceRequestId": "04May18235", "updatedOn": "2018-05-14T04:03:37.547", "createdOn": "2018-05-14T04:03:37.547", "expectations": { "containers": [{ "updatedOn": "2018-05-14T09:33:37.548", "createdOn": "2018-05-14T09:33:37.548", "barcode": null, "containerAttributes": null, "state": null, "products": [{ "productQuantity": 10, "updatedOn": "2018-05-14T09:33:37.548", "createdOn": "2018-05-14T09:33:37.548", "uidType": null, "productAttributes": { "pdfa_values": { "product_sku": "I1", "seller": "S1" } }, "id": 64, "uid": null }], "type": "VIRTUAL", "id": 65, "containers": [] }] }, "serviceRequests": [], "actuals": { "containers": [] }, "receivedOn": "2018-05-14T04:03:37.547", "attributes": { "pps_id": "2", "tote_id": "cit21" }, "type": "PUT", "id": 49 } }
Staging Failure	Show/Hide Warning Note that status field does not come in this notification { "notification_type": "put_information", "version_number": "1.5.0", "notification_id": "unique_id_of_this_notification", "notification_data": { "state": "stage_failure", "id": 123, "externalServiceRequestId": "16feb_02", "type": "PUT", "attributes": { "alert_data": [ { "code": "pps_mode_incorrect", "description": "PPS 2 is not in put mode" } ] } } }
Staging Cancelled	Show/Hide { "notification_data": { "state": "stage_cancelled", "status": "CREATED", "externalServiceRequestId": "04May18234", "updatedOn": "2018-05-13T11:50:51.191", "createdOn": "2018-05-13T11:50:42.865", "expectations": { "containers": [{ "updatedOn": "2018-05-13T17:20:42.869", "createdOn": "2018-05-13T17:20:42.869", "barcode": null, "containerAttributes": null, "state": null, "products": [{ "productQuantity": 10, "updatedOn": "2018-05-13T17:20:42.869", "createdOn": "2018-05-13T17:20:42.869", "uidType": null, "productAttributes": { "pdfa_values": { "product_sku": "I1", "seller": "S1" } }, "id": 63, "uid": null }], "type": "VIRTUAL", "id": 64, "containers": [] }] }, "serviceRequests": [], "actuals": { "containers": [] }, "receivedOn": "2018-05-13T11:50:42.865", "attributes": { "tote_id": "cit20" }, "type": "PUT", "id": 48 }, "version_number": "1.5.0", "notification_id": "platform:[B@1392c667", "notification_type": "put_information" }