mod-orders-storage (v7)

http://github.com/folio-org/mod-orders-storage

Table of contents

Orders

Get list of purchase orders API. This API is intended for internal use only. Please use the /orders/composite-orders API provided by mod-orders instead.

/orders-storage/orders

Entity representing a order

GET /orders-storage/orders

Get list of purchase orders

GET /orders-storage/orders
Query Parameters
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    with valid searchable fields: for example code

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    ["code", "MEDGRANT", "="]
    
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "collection of purchase order records",
  "type": "object",
  "properties": {
    "purchaseOrders": {
      "description": "collection of purchase order records",
      "type": "array",
      "id": "purchaseOrders",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "purchase order",
        "extends": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "description": "Purchase order number prefix",
          "type": "object",
          "javaName": "entity",
          "properties": {
            "id": {
              "description": "UUID identifying this entity",
              "$schema": "http://json-schema.org/draft-04/schema#",
              "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}$"
            }
          },
          "additionalProperties": false
        },
        "properties": {
          "id": {
            "description": "UUID of this purchase order",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "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}$"
          },
          "approved": {
            "description": "whether or not the purchase order has been approved",
            "type": "boolean",
            "default": false
          },
          "approvedById": {
            "description": "UUID of the user approving the order",
            "type": "object",
            "$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}$"
          },
          "approvalDate": {
            "description": "Date and time when purchase order was approved",
            "type": "string",
            "format": "date-time"
          },
          "assignedTo": {
            "description": "UUID of the user this purchase order his assigned to",
            "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}$"
          },
          "billTo": {
            "description": "UUID of the billing address",
            "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}$"
          },
          "closeReason": {
            "description": "Close reason for purchase order",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "properties": {
              "reason": {
                "description": "close reason description",
                "type": "string"
              },
              "note": {
                "description": "free-form notes related to closing reason",
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "dateOrdered": {
            "description": "Date and time when purchase order was opened",
            "type": "string",
            "format": "date-time"
          },
          "manualPo": {
            "description": "if true, order cannot be sent automatically, e.g. via EDI",
            "type": "boolean"
          },
          "notes": {
            "description": "free-form notes associated with this purchase order",
            "id": "notes",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "poNumber": {
            "description": "A human readable ID assigned to this purchase order",
            "type": "string",
            "pattern": "^[a-zA-Z0-9]{1,22}$"
          },
          "poNumberPrefix": {
            "description": "Purchase order number prefix",
            "type": "string"
          },
          "poNumberSuffix": {
            "description": "Purchase order number suffix",
            "type": "string"
          },
          "orderType": {
            "description": "the purchase order type",
            "type": "string",
            "enum": [
              "One-Time",
              "Ongoing"
            ]
          },
          "reEncumber": {
            "description": "indicates this purchase order should be re-encumbered each fiscal year. Only applies to ongoing orders",
            "type": "boolean",
            "default": false
          },
          "ongoing": {
            "description": "Ongoing information associated with this order",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "properties": {
              "interval": {
                "description": "Renewal interval (in days)",
                "type": "integer"
              },
              "isSubscription": {
                "description": "Whether or not this is a subscription",
                "type": "boolean",
                "default": "false"
              },
              "manualRenewal": {
                "description": "Whether or not this is a manual renewal",
                "type": "boolean"
              },
              "notes": {
                "description": "Notes associated with the Ongoing order",
                "type": "string"
              },
              "reviewPeriod": {
                "description": "Time prior to renewal where changes can be made to subscription",
                "type": "integer"
              },
              "renewalDate": {
                "description": "The date this Ongoing PO's order lines were renewed",
                "type": "string",
                "format": "date-time"
              },
              "reviewDate": {
                "description": "Date when Order has to be reviewed",
                "type": "string",
                "format": "date-time"
              }
            },
            "additionalProperties": false
          },
          "shipTo": {
            "description": "UUID of the shipping address",
            "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}$"
          },
          "template": {
            "description": "The ID of the order template used for this order. Applies to both PO and POL",
            "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}$"
          },
          "vendor": {
            "description": "UUID of the vendor 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}$"
          },
          "workflowStatus": {
            "description": "the workflow status for this purchase order",
            "type": "string",
            "enum": [
              "Pending",
              "Open",
              "Closed"
            ],
            "default": "Pending"
          },
          "acqUnitIds": {
            "description": "acquisition unit ids associated with this purchase order",
            "type": "array",
            "items": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "description": "The UUID format string",
              "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}$"
            }
          },
          "tags": {
            "type": "object",
            "description": "arbitrary tags associated with this purchase order",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "tags",
            "properties": {
              "tagList": {
                "description": "List of tags",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          },
          "metadata": {
            "type": "object",
            "readonly": true,
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "Metadata Schema",
            "description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
            "properties": {
              "createdDate": {
                "description": "Date and time when the record was created",
                "type": "string",
                "format": "date-time"
              },
              "createdByUserId": {
                "description": "ID of the user who created the record",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
              },
              "createdByUsername": {
                "description": "Username of the user who created the record (when available)",
                "type": "string"
              },
              "updatedDate": {
                "description": "Date and time when the record was last updated",
                "type": "string",
                "format": "date-time"
              },
              "updatedByUserId": {
                "description": "ID of the user who last updated the record",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
              },
              "updatedByUsername": {
                "description": "Username of the user who last updated the record (when available)",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "createdDate",
              "createdByUserId"
            ]
          }
        },
        "additionalProperties": false
      }
    },
    "totalRecords": {
      "description": "The number of objects contained in this collection",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "purchaseOrders",
    "totalRecords"
  ]
}

Example:

{
  "purchaseOrders": [
    {
      "id": "0804ddec-6545-404a-b54d-a693f505681d",
      "approved": true,
      "approvedById": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1",
      "approvalDate": "2018-07-19T00:00:00.000Z",
      "assignedTo": "ab18897b-0e40-4f31-896b-9c9adc979a88",
      "billTo": "1df71bab-818c-46ea-988b-a23676d91ae6",
      "closeReason": {
        "reason": "No longer available",
        "note": "Items are no longer available to purchase"
      },
      "manualPo": false,
      "notes": [
        "ABCDEFGHIJKLMNO",
        "ABCDEFGHIJKLMNOPQRST",
        "ABCDEFGHIJKLMNOPQRSTUV"
      ],
      "orderType": "Ongoing",
      "poNumber": "ABC268758XYZ",
      "poNumberPrefix": "AB",
      "poNumberSuffix": "XYZ",
      "reEncumber": false,
      "ongoing": {
        "interval": 182,
        "isSubscription": false,
        "manualRenewal": true,
        "reviewPeriod": 30,
        "renewalDate": "2019-04-09T00:00:00.000Z"
      },
      "shipTo": "0830111e-dcf1-4897-9eee-dcd1ab44adce",
      "template": "678323d2-3d86-4a69-8674-bbd4f8eecb33",
      "vendor": "168f8a86-d26c-406e-813f-c7527f241ac3",
      "workflowStatus": "Pending",
      "tags": {
        "tagList": [
          "important"
        ]
      },
      "acqUnitIds": [
        "1895e539-8dac-441e-b1f5-aab62b3fde60",
        "47f504bd-0c1b-498e-a2ae-e2f0a0cea273"
      ],
      "metadata": {
        "createdDate": "2018-07-19T00:00:00.000+0000",
        "createdByUserId": "28d1057c-d137-11e8-a8d5-f2801f1b9fd1"
      }
    }
  ],
  "totalRecords": 1
}

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: text/plain

Type: any

Example:

"unable to list orders -- malformed parameter 'query', syntax error at column 6"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

"unable to list orders -- unauthorized"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"order not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator