Plan for implementing role/license acceptance in authoring

authoring-acceptance-plan.rst

Story Workflow

content creation auto acceptance:	UI: 'arthur' creates content Authoring: object created & auto accepts role/license for 'arthur' Authoring: communication with publishing to set 'arthur' to accepted
adding a role to content:	UI: 'arthur' adds 'smoo' to the content as both an editor and illustrator Authoring: updates content object Authoring: adds 'smoo' to it's own acl records with the 'view' permission Authoring: sends an acceptance notification to 'smoo' to accept the role and license
accepting via message link:	UI: 'smoo' follows link from the email to an acceptance page UI: 'smoo' views the acceptance that forces him/her to accept both the role(s) and license together Authoring: updates content object Authoring: communcation with publishing to set 'smoo' to accepted UI: 'smoo' is now shown as having accepted the document
accepting via workspace:	UI: 'smoo' views the workspace that indicates the content 'arthur' added needs role/license acceptance by 'smoo' UI: 'smoo' clicks to the indicator that links to the acceptance page UI: 'smoo' follows link from the email to an acceptance page UI: 'smoo' views the acceptance that forces him/her to accept both the role(s) and license together Authoring: updates content object Authoring: communcation with publishing to set 'smoo' to accepted UI: 'smoo' is now shown as having accepted the document
re-notify neglectful role:	UI: 'arthur' sees that it has been over a week since he has added 'smoo' to the content UI: 'arthur' is given the ability to notify 'smoo' again, asking them to accept the role/license Authoring: update content object Authoring: re-sends an acceptance notification to 'smoo' to accept the role and license

Content GET

The results in a GET request for content will ammend the role values in the list of person info objects. For example, an authors list of [{"id": "able", ...}, {"id": "cane", ...}] to [{"hasAccepted": null, "id": "able", "canNotify": false}, …].

The ammendments structure is as follows:

role_value := {
    "id": <str>,
    ...
    "hasAccepted": <bool|null>,
    "canNotify": <bool>,
    "notifySent": <iso8601|null>,
    "requester": <user-id>,
    "assignmentDate": <iso8601>,
    }

The hasAccepted is a boolean value can be true, false or unknown (null, none or undefined). This would be the indicator for say colorizing the role in the UI. For example, None = oranage, True = green and False = red.

The canNotify is a boolean value which indicates if the authenticated user can request a notification be sent to this person that would ask them to accept the role. On the backend this is a time sensitive value. For example, an author was added 9 days ago and they have not yet accepted their role. The authenticated user would like to resend the acceptance notification to basically poke the author into accepting the role. The application has been configured to allow renotification after 7 days. Therefore, the canNotify value will be true, which will allow this authenticated user to resend the acceptance notification.

The notifySent is an iso8601 value that indicates when the notification message was sent.

The requester value is the user id of the person that added the role.

The assignmentDate is an iso8601 value that indicates when the role assignment was created.

Content POST

The same sort of adjustment that happens in the GET request happens here, with one difference. At this time the object sent should only contain an id. At a later date, the notify property can be used as a boolean value of true or false. This property will default to true, but can be set false to postpone notification.

Content PUT

The same sort of adjust that happens in the GET request happens here, with one difference. The notify property can be used as a boolean value of true or false. This property will noop if the canNotify has is false. If the property is true, the notification message will be sent again. On success, the notifySent property will contain an updated iso8601 datetime value.

Acceptance UI

Each user will have a page off their workspace for accepting the role and license they have been assigned on any document(s). The user will be assumed to have accepted both the role and license at the same time. If the user has already accepted the license and is assigned an additional role, they will be asked to accept the license again. However, the secondary acceptance of the license is a no-op.

We will be adding to the workspace response to include role and license acceptance information. This will allow the affected user to know what they need to accept as well as anyone else on the document. The information sent will be similar to that sent in a GET content request. Specifically, the additional information will include the license, those that need to accept the license and role information.

The only way to get the content to show up in the user's workspace is to give them permission to 'view' the document. So as part of a role assignment, the user will be given the 'view' permission on that content.

The /contents/{id}@draft/acceptance can be used to acquire info about the acceptance as well as receive info to change the acceptance.

Acceptance GET

license:	The license as it appears in a content GET. This is a JSON representation of the cnxauthoring.models.License object.
user:	The user's profile
roles:	An array of JSON containing role, hasAccepted, requester and assignmentDate.
title:	The content's title as it appears in a content GET.
id:	The content's identifier
url:	The url where the content can be viewed.

Acceptance POST

license:	A true or false value indicating that the user accepts the license.
roles:	An array of JSON containing the role name and a boolean hasAccepted.

Workspace Search Adjustment

The workspace is currently (or so I understand) populated by ACL. This needs to change to a search that does both ACL and role. Having being assigned a role on a piece of content should make that document show up in the user's workspace. Likewise, if an ACL is assigned that allows the user to 'view' and/or 'edit' the content should appear in the user's workspace. The content should show up regardless of acceptance state. This is necessary to allow the user to find the content and accept or decline their role.

Also, we'll need to add the roles metadata to the item response of a workspace. This will give webview the ability to colorcode the content to indicate the user needs to accept a role on said content.

ACL Adjustment

The content Access Control List (ACL) needs adjusted to include basic role based permissions. All attributed roles on a piece of content should have the 'view' permission. Additionally, if they have accepted their role for author, editor, translator or illustrator, they will be given the 'edit' permission.