As a developer of OpenLMIS services, I'd like to be able to easily get stock card summary data that leverages the product model so that my service may understand what stock on hand I have, for a facility and by program using the relationships between Commodity Type, Trade Item and Orderable.

Currently we have GET /api/stockcardsummaries which returns an array of stock cards and their current Stock on Hand. And this resource also has a sub-resource GET /api/stockcardsummaries/nocards which is an array of stock cards which have never been created for Orderables which are approved for the facility/program (via FTAP).

We'd like a v2 of this resource which combines these, accessible at /api/v2/stockcardsummaries which returns a paged array of approved Orderable's Stock on Hand which has fields:

• Orderable reference (approved Orderables of facility, regardless if there's a stock card or not)

• stock on hand - either null (if no stock cards) or a positive integer (if more than 0) which is a sum of all stock on hands in the canFulfillForMe field

• canFulfillForMe - is an un-ordered list where each entry is (this orderables that appear here are the orderable paramater as well as that orderable's list of Orderables in canFulfillForMe):

  • stock card reference

  • orderable reference

  • lot reference (if applicable)

  • stock on hand

  • processedDate - most recent processed date of the stock card's line items (note this is a change from the original stockcardsummaries api)

If there is no stock card for canFulfillForMe entry then is should not be on this list.
Those summaries with empty canFulfillForMe list should be sorted to the end (should be on the last pages).

The parameters are the typical paging parameters as well as:

• program (required) - uuid

• facility (required) - uuid

• orderable ids (optional) - if given as one or more Orderable UUID's takes a sub-list of what program and facility would return (doesn't limit the stock cards returned in the canFullfillForMe field)

• asOfDate (optional): limits the stock on hand reported in the return as the stock on hand at the end of the given day (ISO 8601 to the day). If asOfDate is further in the future than we have stock card data for, return the last SoH. If asOfDate is further in the past than we have stock card data for, return null.

Example: https://jsoneditoronline.org/?id=4ee0b90fb862cc935af9e3822864b80e

AC:

• new api resource is created as outlined above

• permissions works the same as existing /api/stockCardSummaries

• /api/stockCardSummaries continues to work, and is marked in the documentation as deprecated

• performance tests are duplicated so that we have tests for both the new and the old resources