Receiving and Checking-in Materials based on Purchase Orders and Purchase Order Lines (UXPROD-1146)

[MODORDERS-72] Define receiving endpoints in RAML Created: 07/Nov/18  Updated: 24/Jan/19  Resolved: 24/Jan/19

Status: Closed
Project: mod-orders
Components: None
Affects versions: None
Fix versions: 3.0.0
Parent: Receiving and Checking-in Materials based on Purchase Orders and Purchase Order Lines

Type: Story Priority: P3
Reporter: Craig McNally Assignee: Craig McNally
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Attachments: PNG File API_Test_To_Check_501.png    
Issue links:
Blocks
is blocked by MODORDERS-90 Update receiveing and checkin schemas Closed
is blocked by MODORDERS-123 Orders and PO Lines endpoints restruc... Closed
is blocked by MODORDSTOR-31 Create receiving_history API and schema Closed
Relates
relates to MODORDERS-73 Update Module/Deployment Descriptors ... Closed
Sprint: ACQ Sprint 52, ACQ Sprint 55, ACQ Sprint 53
Story Points: 3
Development Team: Thunderjet
Tester Assignee: Craig McNally
Epic Link: Receiving and Checking-in Materials based on Purchase Orders and Purchase Order Lines

 Description   

Define the RAML for the receiving items/check-in pieces functionality. The details can be found in Orders API Listing

Acceptance Criteria:

  • Covers all receiving endpoints
  • Passes raml-cop linting


 Comments   
Comment by Piotr Kalashuk [ 19/Dec/18 ]

Sample scenarios for POST /orders/<id>/receive or /orders/<id>/check-in. Let's assume that we are going to receive a few items (check-in a few pieces) for 5 PO lines.
As far as I can see there are few cases possible:

  1. All data processed successfully. In this case we might return a 201 (Created) response or 200 (OK) response. According to POST specification:

    ...the origin server SHOULD send a 201 (Created) response containing a Location header field that provides an identifier for the primary resource created...

    We might to use path to /receiving_history with query param which could be used to return data for the order as a location header.

  2. No any PO lines processed. The 500 response will be sent back.
  3. Some of the PO line data entries are processed fully (i.e. inventory and storage's pieces updated successfully) but a few PO line data entries failed:
    • The items in the inventory were not updated so the logic stopped and pieces data is unchanged.
    • Only some of the items in the inventory were updated so the logic updated only corresponding pieces data with receiving status.
    • The items in the inventory were updated successfully but pieces data failed to be updated.

In the 3rd case we might return 500 response but with json content returning either:

  • receiving_collection/checkin_collection with only successfully processed entries
  • errors and each error will describe failed entry.

Craig McNally - could you please have a look and advise if you are okay with any of the approaches or you think the behavior should be different.

Thanks,
Piotr

Comment by Piotr Kalashuk [ 20/Dec/18 ]

This story can be only completed once the changes of the MODORDERS-90 Closed and MODORDSTOR-31 Closed are available in master.

Comment by Craig McNally [ 20/Dec/18 ]

1) I like your idea of using 201 w/ location of receiving_history w/ query, but I can't think of an elegant way to form the query... All I can think to do is something like: peiceId== <id1> OR pieceId == <id2>... etc. for each piece being received/checked in. I think the query could potentially get quite long very quickly, especially given the length of a single uuid.

We also need to keep in mind that in the receiving case we won't actually be creating records, but updating existing records. This may be reason for endpoint semantics to diverge, or we could take a more general approach:

Return a 200 (no location header) with a json response body containing the locations of the various receiving_history "records". We might want to include other information in the response body as well about each piece, so it's clear which link/location corresponds to which "piece" in the request. Care must be taken when naming the fields in this schema to avoid confusion... there's already a "location_id" in the check-in collection schema... maybe use the term "link" instead.

2, 3) I think we want to be consistent here... I'm on board with returning a response with a list of errors, but we should respond with the regardless of whether they all failed or only one failed.

It might make sense to combine all this into a single schema where we return some information for each peice in the request, whether it be a link,etc. or an error message.

Thoughts?

Comment by Piotr Kalashuk [ 22/Dec/18 ]

Piotr Kalashuk:

Just would like to provide brief summary.
We agreed that receiving_collection and checkin_collection should be updated to include piece_id so we can return meaningful processing results.
There are several potential approaches from client perspective to get piece_id's:
1. Extend composite_po_line.json schema adding piece info and extend GET /orders/<id> endpoint adding some parameter (like mode with enum values e.g. SUMMARY, FULL_DETAILS, RECEIVING). Depending on this parameter mod-orders will return different content for the composite_purchase_order and composite_purchase_order
2. Introduce GET /orders/<id>/receive which should return required information to start receiving flow. This should include PO line summary + piece info like

pieces: {
  piece_items: {
  type: array:
    {
      id,
      status: [Received | Expected]
    }
  },
  received: number
  total: number
}

3. Similar to 2nd but the piece_id's are not returned when user starts receiving flow but another endpoint introduced to get pieces with Expected] status for PO lines we are going to process

Craig McNally

So the flow would be something like this:
1) open the orders app, search/filter - a list of orders appears (GET /orders)
2) select an order - order details appears (GET /orders/<id>)
3) select the "receive" button in the details pane - the receiving modal comes up and displays receiving info
• for each po_line.... (GET /orders/lines/<id>/pieces) - based on mocks we want to see expected & received.
4) details are entered, e.g. number of each po_line to receive, notes, etc.
5) form is submitted - "Update Item Details" modal is displayed
6) item details are entered, e.g. barcode, location, status, etc.
7) form is submitted ({{POST /orders/<id>/receive)
8) Receiving History is displayed (GET /orders/receiving_history -> purchase_order_id == <order id>) (edited)
note that for 8 to work, we need to add po_line.purchase_order_id to the receiving_history view.
The PO number displayed at the top of this receiving history modal can be parsed from the po_line_number

Comment by Piotr Kalashuk [ 22/Dec/18 ]

The raml file update committed to MODORDERS-72-receiving-endpoints branch.

There are following dependencies:

  • The PR #58 created to acq-models repository for required schema updates.
  • The changes of the MODORDSTOR-31 Closed should be merged to master of the acq-models repository

Once both the changes mentioned above are done, the acq-models sub-module in mod-orders should be switched to latest version and pushed to MODORDERS-72-receiving-endpoints. After this the PR can be created.

Regards,
Piotr

Comment by Piotr Kalashuk [ 14/Jan/19 ]

The PR #58 of the acq-models repository has been merged.
The PR #61 has been opened for mod-orders repository.

Regards,
Piotr

Comment by Piotr Kalashuk [ 21/Jan/19 ]

The PR #61 has been merged to master.

Orders API documentation now has receiving endpoints.

Comment by Piotr Kalashuk [ 23/Jan/19 ]

Verification hsa been done against folio-testing-backend01.aws.indexdata.com back-end that all 3 defined endpoints accessible and return expected at this stage 501 (Not Implemented) response:

The following requests used:
1. Receiving

POST {{protocol}}://{{url}}:{{okapiport}}/orders/receive
{
  "toBeReceived": [
    {
      "poLineId": "{{$guid}}"
    } 
  ],
  "totalRecords": 1
}

2. Check-in

POST {{protocol}}://{{url}}:{{okapiport}}/orders/check-in
{
  "checkInItems": [
    {
      "poLineId": "{{$guid}}"
    } 
  ],
  "totalRecords": 1
}

3. Receiving history

GET  {{protocol}}://{{url}}:{{okapiport}}/orders/receiving-history
Comment by Craig McNally [ 24/Jan/19 ]

I too verified this on folio-testing using similar requests and got 501 responses as expected.

Generated at Thu Feb 08 22:32:49 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.