Expect (v1)

https://github.com/folio-org/mod-orders

Table of contents

Orders Business Logic API

API for transitioning pieces status from Unreceivable to Expected

Expect pieces

Expect pieces spanning one or more PO lines. The endpoint is used to:

POST /orders/expect

Expect pieces spanning one or more PO lines

POST /orders/expect
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of expect",
  "type": "object",
  "properties": {
    "toBeExpected": {
      "description": "List of expect",
      "id": "toBeExpected",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "poLineId": {
            "description": "The id of the expect PO line",
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
          },
          "expected": {
            "description": "The number of pieces to expect",
            "type": "integer"
          },
          "expectPieces": {
            "description": "A collection of piece records",
            "type": "array",
            "id": "expectPieces",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "description": "The id of the piece",
                  "type": "string",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                },
                "comment": {
                  "description": "The free form notes pertaining to the piece",
                  "type": "string"
                }
              },
              "additionalProperties": false,
              "required": [
                "id"
              ]
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "poLineId"
        ]
      }
    },
    "totalRecords": {
      "description": "The total number of pieces to expect in the list",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "toBeExpected",
    "totalRecords"
  ]
}

Example:

{
  "toBeExpected": [
    {
      "poLineId": "3f4f61ab-d3c2-47a9-baa6-c903a4cfba57",
      "expected": 2,
      "expectPieces": [
        {
          "id": "fe729e0b-5c56-4f0a-bb3a-33bc405d71a0",
          "comment": "Captivating cover art for the first edition"
        },
        {
          "id": "4d6b8cf9-73bd-4b3d-8f1b-5b7cbf02d03a",
          "comment": "Intriguing chapter titles and compelling storyline"
        }
      ]
    },
    {
      "poLineId": "7d9fe888-bc7e-4d4e-9241-0b5f2457e0a3",
      "expected": 1,
      "expectPieces": [
        {
          "id": "9a2e97e3-5f8b-4b2c-9e27-16c8e8993018",
          "comment": "A thought-provoking conclusion in the final chapter"
        }
      ]
    }
  ],
  "totalRecords": 3
}

Response 200

Returns processing result of the expect

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of receiving results",
  "type": "object",
  "properties": {
    "receivingResults": {
      "description": "List of receiving/checkin results",
      "id": "receivingResults",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "poLineId": {
            "description": "The id of the receiving/checkin po line",
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
          },
          "processedSuccessfully": {
            "description": "The number of items processed successfully",
            "type": "integer"
          },
          "processedWithError": {
            "description": "The number of items processed with error",
            "type": "integer"
          },
          "receivingItemResults": {
            "description": "List of processed receiving item details",
            "id": "receivingItemResults",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pieceId": {
                  "description": "UUID of this piece record",
                  "type": "string",
                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                },
                "processingStatus": {
                  "description": "The status describing item processing result",
                  "type": "object",
                  "properties": {
                    "type": {
                      "description": "Resulting status of the processed piece record",
                      "type": "string",
                      "enum": [
                        "success",
                        "failure"
                      ]
                    },
                    "error": {
                      "description": "Error details in case receiving/check-in process for the piece record has failed",
                      "type": "object",
                      "readonly": true,
                      "$schema": "http://json-schema.org/draft-04/schema#",
                      "id": "error.schema",
                      "properties": {
                        "message": {
                          "type": "string",
                          "description": "Error message text"
                        },
                        "type": {
                          "type": "string",
                          "description": "Error message type"
                        },
                        "code": {
                          "type": "string",
                          "description": "Error message code"
                        },
                        "parameters": {
                          "description": "Error message parameters",
                          "$schema": "http://json-schema.org/draft-04/schema#",
                          "id": "parameters.schema",
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "pieceId",
                "processingStatus"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "poLineId",
          "receivingItemResults"
        ],
        "additionalProperties": false
      }
    },
    "totalRecords": {
      "description": "The total number of receiving/check-in items in the list",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "receivingResults",
    "totalRecords"
  ]
}

Example:

{
  "receivingResults": [
    {
      "poLineId": "0804ddec-6545-404a-b54d-a693f505681d",
      "processedSuccessfully": 1,
      "processedWithError": 1,
      "receivingItemResults": [
        {
          "pieceId": "c18c49b7-d970-44d6-b5d4-bd76c1c62d83",
          "processingStatus": {
            "type": "success"
          }
        },
        {
          "pieceId": "cb9b0468-f2b4-4a13-b64c-662c4c9ec3ed",
          "processingStatus": {
            "type": "failure",
            "error": {
              "code": "pieceAlreadyReceived",
              "message": "The piece record is already received"
            }
          }
        }
      ]
    },
    {
      "poLineId": "7f0c4975-885e-47d5-8d5a-793dffbba9b2",
      "processedSuccessfully": 1,
      "processedWithError": 0,
      "receivingItemResults": [
        {
          "pieceId": "20241b8c-9076-4cf5-817b-f2c1e2cb242f",
          "processingStatus": {
            "type": "success"
          }
        }
      ]
    }
  ],
  "totalRecords": 3
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: application/json

Type: any

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Media type: text/plain

Type: any

Example:

"unable to update expect -- malformed JSON at 13:4"

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: application/json

Type: any

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Media type: text/plain

Type: any

Example:

internal server error, contact administrator