user-supplied justification for changes to agreement metadata or BLs

[jonnalley]

User Story

As an OPS user, I want to give some kind of justification or substantiation for making a change to agreement metadata or budget lines so that myself or others within OPRE can understand the impetus for an attribute changing, even long after my own memory of the change's impetus has abated.

Acceptance Criteria

• [ ] When a user is editing agreement metadata or budget line(s), before committing/persisting the changes, the user should be prompted for an optional textual reason for the changes.
• [ ] If a reason is specified, the reason for change should then show up in the history log for the agreement that was first started in #1300
• [ ] If the dollar amount for a BL is changing, the user must submit a reason. It should not be optional.
• [ ] If the procurement shop on the whole agreement is changed, which can only happen under limited circumstances, the user must submit a reason. It should not be optional.
• [ ] All user-supplied text should escaped and sanitized for malicious input, obviously.
• [ ] A reasonable character limit should be enforced as this text will have to be displayed in a helpful manner in other places

---

Tasks

UX

• [ ] Determine if change reason is a user need
• [ ] Explore options for adding a "change reason" or "justification" associated with edits
• [ ] Share options with team for internal feedback
• [ ] Refine design
• [ ] Share design with OPRE for feedback
• [ ] Refine design
• [ ] Provide design to Figma Dev page with annotations

Dev

Frontend

Backend

• [ ] #1415

Definition of Done Checklist

• [ ] UI works as designed (UX team)
• [ ] Usability validated (UX team)
• [ ] PR(s) have been merged to main
• [ ] Design/tech debt eliminated
• [ ] Build process updated
• [ ] Documentation updated or added
• [ ] Feature flags/toggles created

Additional Context & Resources

• 679 and #680 are very much related and will also consume this user input in all likelihood

• This particular requirement came up during the evolution of and discussion with OPRE about #1001

[kimschulke]

This topic came up with opre again on 6/27/24

• In MAPS, they take notes on what they changed and when… but the agreement history will provide this automatically
• Need to assess use of notes especially around changing amounts and why. They like that the history says who did what /when, but why might be interesting too. For now, they can use BL Notes or Notes during status change submissions
• UXers explained how we learned some users will write a novel but others will write one word so our strategy so far has been to air on the side of less notes/open text to see how they use them and learn from usability testing how to intentionally structure notes
• discussed for change reasons, maybe we could develop a standard list of options/drop down: reduced level of effort, budget revision, etc and then change reasons would be easier to report on (but might also be annoying to users to have to select a reason on every little change (?))
• Future research could determine if an “edit” of 5 “changes” should be 1 change reason or 5 change reasons
• Will they want a BL history? In addition to the agreement history
• In the past we explored a change reason modal that appeared with the send to approval budget change modal - where they can send to approval with a note or dropdown on the change reason

[kimschulke]

On 9/9/24, we discussed this again with Sheila... the need is to track the reason for changes overtime. For example, how many contracts had increased level of effort. More of a "reporting" need. Don't assume it needs to be a user-entered reason, possible to create reports on this depending on what data is needed. TBD