feat: User agreements API for generic agreement records

[xitij2000]

Description

This change adds a new kind of generic user agreement that allows plugins or even the core platform to record a user's acknowledgement of an agreement.

Supporting information

NA

Testing instructions

• This creates a new REST API at /api/agreements/v1/agreement/<agreement_id>
• You can use GET, which will return a 404 if a user hasn't acknowledged the agreement, or the timestamp of acceptance if they have
• You can do a simple empty POST to mark acknowledgement
• You can use the ?after=... query param with get to filter agreements after that date

Deadline

"None"

Open Questions

• Perhaps the text of the licence / agreement etc should also be stored in a django model and versions in an update-only manner.

[openedx-webhooks]

Thanks for the pull request, @xitij2000!

What's next?

Please work through the following steps to get your changes ready for engineering review:

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

🔘 Let us know that your PR is ready for review:

Who will review my changes?

This repository is currently maintained by @openedx/wg-maintenance-edx-platform. Tag them in a comment and let them know that your changes are ready for review.

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[kaustavb12]

Since the primary use of this record would be for generating complaince reports, I feel we should only create records here and not update them. This would also be useful if, for example, some user agreement needs to be accepted periodically.

[xitij2000]

The idea here is that if you have an agreement, let's say "termsofservice", that can be updated, you can check if a user has accepted the agreement and also if they've accepted the latest agreement. For a report you can simply check which user's have a record for the agreement created after the date of the new agreement. If it needs to be accepted periodically then you can simply check in the frontend that the agreement was accepted in the current period.

[kaustavb12]

The idea here is that if you have an agreement, let's say "termsofservice", that can be updated, you can check if a user has accepted the agreement and also if they've accepted the latest agreement

We can do that just the same even if we keep all records and not update them. No ?

In fact, specifically for the "terms of sevice" example, keeping all old records would enable someone doing an audit to determine under which version of the terms did an old user activity (for example if the user uploaded copyright protected files) take place.

I can see how old records can be retained even with update_or_create function by perhaps changing the agreement type for each version of the agreement, but it seems right to retain things like agreement records instead of updating them.

[xitij2000]

I don't think automatically changing the agreement type is a good idea. It's definitely an option that can be adopted by consumers of these APIs. For instance, you could have an agreement type of "toc-2024" and then "toc-2026" and they will both be tracked separately.

However, I guess I'm just not seeing what you're talking about as a realistic scenario in this case. What you are talking about is a more complex requirement for auditing and I don't think this is trying to be that.

What I'm looking at is a few simple scenarios. A ToS agreement, a fair use agreement etc. All you want to know is if the person has agreed to the current form of the agreement. You can do that by recording the date on which the updated agreement was posted and comparing against the date that the user last accepted the agreement. If they accepted after the latest agreement was posted, then they are good to go, otherwise, ask them to accept the agreement again.

If you want to, you can make the logic more complex and check if there have been multiple updates to the agreement since their last acceptance, and if so, show then a UI that shows the differences between versions. Or at the very least show an "our terms have changed" UI.

In the scenario you shared, it probably doesn't matter in what duration those files were posted, as long as they were posted before the current agreement, because they might not align with it.

I don't think it would be a big deal or a lot of effort to adapt this code to keep one record for each acceptance, but currently this will scale with users * agreements and with your proposed change it will scale with users * agreements * agreement change and someone could simply code a loop posting agreements and flood the db.

I guess they still can because the agreement type is not validated, so perhaps that is one way to go next.

[kaustavb12]

However, I guess I'm just not seeing what you're talking about as a realistic scenario in this case. What you are talking about is a more complex requirement for auditing and I don't think this is trying to be that.

I was basing my assumption about auditing requirements based on this portion of the client's requirements which triggered this PR :

• Log user interactions with the agreement (e.g., acceptance date) for auditing and compliance.
• Enable report generation to check who has accepted the agreement within a given timeframe.

It is a bit unclear in these statements as to how complex these "auditing and compliance" requirements are, and thought maintaining all records would be a safer option (without needing too much changes to the current implementation) which would provide users the flexibility to go beyond simple acceptance checking if need be.

But for now I guess I am ok with moving forward with the implementation as is. We can always change it later if so required.

[xitij2000]

I interpreted that as log the acceptance date not log every acceptance date, however, maybe I'm wrong and we can consult with them to clarify.

For the report generation they only wanted that it be possible for them to do so using SQL on their side.

[kaustavb12]

👍

• I tested this: Tested in local setup
• I read through the code