WIP v5 Terms API 2.0

[rootelement]

This is a WIP enhancement issue.

Need to clean up the terms service and add some new features:

API Changes

1. Edit/Delete Locking - If anyone has signed terms, you shouldn't be able to edit or delete the terms
2. Draft/Versioning - The exception to the above is a procedural versioning system (kinda like wordpress) where if an edit is published, it increases the version of the document and doesn't save over top of it.
3. Access by slug/key - There are terms that are used throughout topcoder that are currently referenced by ID. So when new terms come out, we need to go into all the different applications and update that id. Doing the draft/versioning will help some, but you should also be able to get key terms by a logical url. Adding a key or slug would allow getting terms something like this: v5/terms?key=nda and you'd get the current, active platform NDA.

Admin App Changes

1. Community App Sign Link - This page is viewable even in incognito. It should redirect the user to log in if they're not logged in: https://www.topcoder.com/challenges/terms/detail/564a981e-6840-4a5c-894e-d5ad22e9cd6f
2. Add a column to the terms admin that shows when the terms were created.
3. Enable column sorting in terms admin.
4. Add column for user totals in the list view.
5. HTML editor doesn't seem to work. Editor to allow terms to be saved.
6. Create a category of terms types that are related. This is related to both the slug feature above and the version feature. It would be helpful to have all "topcoder terms" related somehow. Right now, they are, somewhat arbitrarily related by terms title. It would be helpful to have a class (maybe the slug above) of terms that are related and can be see together.
7. Diff feature. What's changed from one terms to the next. This would help ensure communication and change management. Right now I have to do super hacky things like this https://www.diffchecker.com/GONoB5N4 to see and convey the difference. I'd like to select two items and do a diff. It would make sense to have this per version in support of Bump sequelize from 5.7.3 to 5.15.1 #2 above, but we also create mulitple "terms". I'm also happy to adopt a different paradigm where "Topcoder terms" is one and only one object and we just version it for new terms.
8. A preview or live button. I always have to remember where to go in the platform to actually "see" the terms. Having a preview button would be helpful.
9. A view mode, from the list view. Currently If I click on an item, I'm taken into an edit mode. I'd like to have a view or preview that I can see the current version. This differs from Bump axios from 0.12.0 to 0.19.2 #11 in that number 11 will have a button or a link to take me directly to https://www.topcoder.com/challenges/terms/detail/. This feature is allowing me to view, in the terms admin, the current terms and NOT be in edit mode.
10. "View users" should have the date when they ack'ed the terms.
11. "View users" should have a url for the handle to take them to the member profile and or the admin tool user record. Maybe the user id field should take them to the admin tool user and the handle to the public profile.

[maxceem]

1. [Community App]: This has to be done in the Community App code. Would you like me to log an issue there?

2. [Terms API] + [Admin App]: clear, after Terms API updated

3. [Terms API] + [Admin App]: clear, after Terms API updated.

   • As I understand we should only support sorting by title, type, agreeabilityType and createdAt columns. We should not support sorting by the column Info as it shows 2 kind of data and we hardly need to sort by it. Correct?

4. [Terms API] + [Admin App]: clear, after Terms API updated.

5. HTML editor doesn't seem to work.

   • Hmm, HTML editor works good to me. Could you please share more details on what issues are you facing?

     Editor to allow terms to be saved.

     not sure what you mean

6. [Terms API] + [Admin App]: Are you thinking about using key/slug as a category? Or key/slug would be more like id and there would be additional category which would group several terms like topcoder. So terms with keys nda, community, copilot could be gathered in one group like topcoder.

7. [Terms API] + [Admin App]: clear, after Terms API supports versioning.

8. [Admin App]: As I understand this means open a link like https://www.topcoder-dev.com/challenges/terms/detail/0a8695ab-cd13-4539-8d5f-839654415872 in a new window for any Terms.

9. [Admin App]: Clear.

10. [Terms API] + [Admin App], clear after Terms API is updated to return dates for users.

Changes we would need in Terms API to implement requirements above for Admin App:

1. GET /terms and GET /terms/:termsOfUseId endpoints should return created field.

2. GET /terms endpoint should support sorting by:

   • title
   • type (textual value)
   • agreeabilityType (textual value)
   • created

3. GET /terms and GET /terms/:termsOfUseId endpoints should return totalUsers field with the quantity of users who signed this terms.

4. GET /terms/:termsOfUseId/users endpoint should return a list users using objects instead of list of integer values:

   {
     userId: 123456,
     created: "2020-02-11T05:43:02.000Z",
   }

[rootelement]

[Community App]: This has to be done in the Community App code. Would you like me to log an issue there?

No, by this I meant that the admin app should have a link out to community app (like the example shown). Make sure the community app prefix is configured by environment.

We should not support sorting by the column Info as it shows 2 kind of data and we hardly need to sort by it. Correct?

Correct

Are you thinking about using key/slug as a category? Or key/slug would be more like id and there would be additional category which would group several terms like topcoder. So terms with keys nda, community, copilot could be gathered in one group like topcoder.

Leave this one for now.

As I understand this means open a link like https://www.topcoder-dev.com/challenges/terms/detail/0a8695ab-cd13-4539-8d5f-839654415872 in a new window for any Terms.

I think # 1 and # 8 are the same thing. We need a button in the admin that takes them to the terms view in community app.

[ThomasKranitsas]

Questions on the API changes:

1. How about admins/m2m? Should they be able to edit/delete?
2. 1. What if someone has signed a term, then you publish a newer version? Will there be some sort of "need to re-sign this" flag?
   2. What about rollbacks? Let's say you release a new version but for some reason, you need to go back to a previous version. Will that be an additional update or we can simply select the "active version"
   3. What do you mean by Draft? Will drafts be only available to admins/m2m until they get released? So, we need a status field for that, right?
3. Pretty straightforward.

[rootelement]

Ok, I think there's a little confusion here. Think of it this way...

1. Admin creates Terms A. Terms A is defined as the standard challenge terms v1.
2. Copilot creates Challenge A with the default challenge terms, which is now Terms A
3. Member A goes to the challenge details for that challenge, has not signed Terms A, gets the pop-up, signs the terms, and proceeds to the challenge.
4. Terms A now has 1 signature
5. Admin notices there's a misspelling in the terms. They should be able to update this. No new terms need to be signed. (this is up for discussions whether this should be possible or not)
6. Admin notices there's a missing clause that changes the meaning of the terms. Saving these changes should be Terms B, which are the new default standard challenge terms.
7. Copilot creates Challenge B, Terms B are associated
8. Member A comes to Challenge B, and has not signed Terms B. Member gets the pop-up, signs the terms, and proceeds to the challenge.

A couple points.

1. The admin tool should possibly have an Edit link and a "New Version" link (or Clone?). Then it's up to the admin tool / admin user whether the change means members need to sign new terms. There's really no way to programmatically decide whether a change is enough to warrant a new version or a text edit.
2. When a user signs terms, they should never be un-signed. If a user has to "re-sign" terms, a new terms uuid should be created.
3. You should be able to get the latest, current version of major terms by a key or slug. So I should be able to GET /v5/terms?key=nda and it gets the latest version of the standard nda. This would allow the public site to link to /challenges/terms/details/nda to display the current terms

Example data model to clarify my point:

Terms
id (uuid)
title (String)
key (String) [or slug of the title]
currentVersion (TermsVersions.id)
description (Text)

TermsVersions
id (uuid)
version (String) [or whatever can hold major.minor?]
title (String) [possibly refactor to name]
typeId (TermsOfUseTypes.id)
agreeabilityTypeId (TermsOfUseAgreeabilityType.id)
text (Text optional) [possibly refactor to body]
url (String optional)
docusignId (String optional) [refactor TermsOfUseDocusignTemplateXref into here]
isPublished OR status

[rootelement]

Basically:

1. I need to be able to group terms
2. I need to be able to refer to the current version of that group by some logical/easy identifier
3. I need to be able to draft a new version without making it public/active
4. I need members who sign a current version to be tied to that specific version, not the latest version