As a user filling out a Requisition,
I want to record the "Date physical stock count completed" for this requisition (rather than just having the requisition associated with a date range from its period, e.g. monthly or quarterly),
so that my data stored in OpenLMIS stock service can be more accurate.
For example, if I did my physical inventory and filled out my Requisition form on the 7th of July, I would like to enter that into the system. This is more exact/accurate. Otherwise, the system only knows that my requisition is with the June period (June 1st-30th).
This work is part of the "connecting requisition and stock management" work described here: https://openlmis.atlassian.net/wiki/spaces/OP/pages/114234797/Connecting+Stock+Management+and+Requisition+Services
This date field is something that can be edited by anyone with edit rights on the Requisition itself as long as the requisition is in INITIATED, SUBMITTED or REJECTED status. When a user pushes the Submit or Authorize button, that will trigger a pop-up where they can enter or edit the date. Once the requisition is AUTHORIZED, the users working on it can change approved quantities as usual but cannot change this date. The date is really a date that the facility submitting the requisition is saying they did their physical inventory—the date when their stock numbers are accurate as of. That is not something that the user at a different physical location can know or modify. They can REJECT it, and the people at the facility can then change the date again, if needed.
What are we going to use this date for?
This will be the date used late when Requisition sends data to Stock service in a future phase of the epic--see background page linked above. What about pre-existing requisitions that do not have this date? If a requisition does not have this date field collected, then the Requisition service will likely use the last day of the reporting period as the effective date for the stock events (this work will be in a later ticket https://openlmis.atlassian.net/browse/OLMIS-2834). EG, when the services are connected, a June requisition that does not have a date field would create a stock physical inventory dated June 30th. However, even if we use June 30th to create stock events, we do not want June 30th to display in the UI as the "Date physical stock count completed" date. If a requisition does not have this date, we want to leave it blank. The field is only a required field at the time of Submit and Authorize status changes. But otherwise, this field can be blank. Meaning pre-existing requisitions that already got Submitted and Authorized before this feature was in place can still be saved and still move later in the work flow (Approve, Release, Reject) without this date field filled in.
Background about the semantic meaning of this date
It is important to remember that there might be A LOT of dates about a Requisition:
end of reporting period
date a storeroom clerk did a physical inventory to count stock (this is the particular date we are trying to collect with this new field)
date a paper form was filled out (if there is a paper step in their workflow)
date a paper form was received at a district office (or at some other location that does data entry into OpenLMIS)
date of the data entry into OpenLMIS (again, only if there is a paper step in their workflow)
date Approved, Release, etc (dates of all other statuses, and date of Rejection, re-submission, and such)
...So we want to be clear what the semantic meaning of this new date field is. Because we will use it for creating stock events in our stock management service. We do know that some countries have asked for other date fields to be collected as part of a requisition. We do not want this date field to be used for the wrong purpose, because that would mess up data accuracy.
Our current decision is to NOT make this new date field configurable. For now, we will implement WITHOUT configuration. Will wait for more feedback form Product Committee and others before making configurable.
Make the date field a configurable field that is turned on/off in the Requisition Template for each program by the admin who can edit the program settings and template.
There are a bunch of edge cases/scenarios for the data migration that need to work smoothly in scope of this ticket:
Implementations with pre-existing data in OpenLMIS 3 (a previous version before this feature) have requisitions that do not contain the date field. In that case, when they upgrade to the new OpenLMIS with this feature:
database migration runs smoothly to allow for storage of this new field; and the Requisition service can handle pre-existing requisitions fine even when they do not have this field in their data (perhaps it becomes stored as a NULL date, and returned in the JSON as a null);
users must be able to view old requisitions that did not have a date field;
users must be able to start a new requisition which gets a date field and users are prompted to provide a date (when they submit or authorize);
requisitions that were in-progress but not finished during the upgrade must work smoothly (please test for Requisitions that were in INITIATED, SUBMITTED, AUTHORIZED, REJECTED, IN_APPROVAL, and RELEASED status)
Programs that enable this field at any time (if we decide for this to be configurable) need to have their requisitions work smoothly in those same cases.
Programs that disable this field at any time also need to have their requisitions work smoothly in those cases (old requisitions might have dates, ones in progress might or might not, new requisitions would not get a date).
Requisition service has support for this date field. Handle and test for all of the edge cases for data migration detailed above. This should be a LocalDate on the backend.
With this new date field, users must provide a valid date in the date field (cannot leave it blank) when they try to advance the requisition to Submitted and Authorized state.
If they have not filled out the date field, the API stops them from changing the status to Submitted or Authorized and gives a helpful error.
If the date is invalid date ("2017-FOO-BAR"), the API gives a helpful error.
If the date is in the future, the API stops them and gives a helpful error. Something like this: "You cannot record stock data for the future. You must enter a date when this stock data has been observed or verified. The date can be today or a past date."
If the user is making a different status change (Approve, Reject, Release), this date field is not required for requisitions to move to those statuses. So the date is not required at that step; a requisition with the date blank (NULL) can move to those statuses.
If the user is just saving the requisition and not moving it to a different state, they can save without a date (they would not have gotten the modal yet, because that happens when moving to Submitted or Authorized).
Requisition UI shows this date field for requisitions in the requisition header ONLY when the field has a value.
We want the field to appear when it is set (when it has a value) but not appear when it is blank (before it is set or on requisitions that do not have that field set). The UI design mockup shows that first case: a requisition before submission does not have this field set, so it does not appear in the header. Then the user clicks Submit, they get a modal to fill in the field (date is required in that modal/required for Submit and Authorize), then after that the date does appear in the requisition header.
A requisition that gets a date set, later gets Rejected, and starts back at the beginning of the workflow, will indeed display the date field.
Requisition UI modal makes it required to enter the field when submitting or authorizing
Requisition UI should show the modal when clicking the submit and authorize buttons. If the date was already recorded, the modal should be pre-populated with it. If no date was set yet, the date field starts out blank.
Check the edge cases in the UI, including date validation rules as listed above.
The Requisition service and UI both handle viewing and editing past requisitions that were in the system before this new date field feature was added. (See specific edge cases to test in Data Migration section above).
Print view of Requisition now includes this date field (when it is set, not displayed when NULL) (As of 8/15 this is a separate ticket)
RAML is updated
CHANGELOG is updated
Automated test coverage
Video showcase of this new feature
Good catch, fixed
I fixed performance tests, they still fails but obviously for some other reasons, I believe this ticket is ready to be moved to done (after it pass QA).
in Firefox the error message still shows, but I'm able to submit after I've corrected the date.
The behavior in Chrome is correct.
It looks like you have some old cache because error handling looks different now (errors are shown below input). I tested on Firefox and it works fine for me (like in Chrome).
all tests passed. Moving to done. Thank you!