Rights + Roles: Background

Relates to

Design new rights, roles and permissions structure based on feedback
Implement Roles / Visibility changes (backend)

Description

The changes in Rights and Roles emerged from the long feedback process which started in 2021 with Regen1 at the time which involved many producers and partners in multiple meetings for feedback and user journey mapping. Then again more recently in 2023 we re-did some of this work internally and with OpenTEAM partners, along with individual meetings with Our Sci users.

2021 UI Review, feedback, and screens: miro board
2023 UI Review, feedback, and screens: https://miro.com/app/board/uXjVNZ88B_o=/?share_link_id=107291312193
2023 User Journeys: https://miro.com/app/board/uXjVNr1mWpQ=/?share_link_id=397978704375

Initially revamping the rights and roles was considered out of scope for the Q1 PCSC Term for OpenTEAM. However, after receiving feedback from Nat, Ankita, Juliet, our internal development team discussions, and looking at concerns from partners like Pasa, we decided it best to do the work now to create a 'granular' permissions system that used language closer to what users expect (think Google Docs, Sharing, etc.).

The focus of these Rights and Roles changes can be summarized as follows

Core Problem: We have the visibility of the survey and the visibility of the results tied together right now. Those should be separate concerns.

Core Concept Statement: Prioritize comparison of methods, not comparison of Data.

While our goal is highly granular Rights and Roles, we also got feedback that more granularity can also create a separate kind of confusion. Thus part of this MVP requires better documentation in how rights relate to creating new entities (Surveys, Question Sets, Scripts, etc.) in the system.

Rights and Roles Design Requirements

Requirements

References
- 2023 UI Review: https://miro.com/app/board/uXjVNZ88B_o=/
  - 2024 Rights and Roles brainstorming: https://miro.com/app/board/uXjVNZ88B_o=/?moveToWidget=3458764580763216806&cot=14
- 2024 Use Cases: https://miro.com/app/board/uXjVNr1mWpQ=/
(ankita, research applications) - Private data must be fully private. No results can be shown, and no summary information (even the number of submissions) can be public.
(past needs assessments / experience) - Users must have clarity of their current Group Thus, actions with Entities or Data must also be in that context.
(past needs assessments / experience) - Users must have clarity of what's available and typical workflows should be prioritized, while not interacting easily with items that are not relevant or useful.
(past needs assessments, last round of feedback) - We need active, real-time support to explain users options, especially around Groups and Survey Rights. It should be provided clearly in a just-in-time way without being diverted to documentation
(use case listing) Use Cases listed above must be intuitively achievable with minimal active support.

General Rules / Business Logic

General Rule

The Data / Entity tables (in group context and Explore menu) is filterable using the ‘pills’ in the table. Clicking on the ‘pill’ causes the filter to add that group/subgroup as a filter. Applies to "Proxy", "<a_group_name>", etc.
- Filtering to a group should always include it's subgroups. This is the expected behavior for the user. They may remove specific subgroups once added if they want to only see the specific top level group without it's subgroups.
- ❌ not in MVP

Entities (surveys, question sets, scripts)

Entities are actively shared - they do not automatically appear or aggregate. Explicit sharing is what causes them to appear in lists in your group context.
- If an entity is no longer actively shared with your group, then you will no longer see it in your group.
  - e.g. If shareSettings.submit and shareSettings.viewAnonResults (for Surveys) and shareSettings.edit (for all Entities) do not point to directly or evaluate to (via $public/$wholeGroup/$subGroupsOnly/$thisGroupOnly) your group, then the entity will not appear in your Context Group's Entity listing.
- Entities marked “Public” allow other groups to share the entity with themselves by adding their group as an entry in the Survey's shareSettings.viewAnonResults. ❗ this is still kind of a proposal, and the wording shouldn't be 'share with myself' but 'add to my group', and should update the entities share settings --> viewAnonResults to cause it to appear in the entity list in that group's context.
- 👍 In a sense - we have this already - entities are not actively shared. We don't have the share updated structure and semantics to allow better sharing in the future - that's where the work is to start.
Interactions with entities always occur in the context of the current group context.
1. Actions which are not possible from your current context will not appear as an option.
2. Actions which will result in confusing UI will have options to redirect the user to an appropriate context.
  - e.g. I am in Group A, using Explore. I see a survey I created in Group B. I will not see an 'edit' option in the dropdown from here. I may click on the Group A pill to go there an edit it.
  - e.g. I am in Group A where a Survey is shared via viewAnonResults. The survey is one I created in Group B. I will not see an 'edit' option in the dropdown from here. I may click on the Group A pill to go there an edit it.
  - ❗ IF we can do this successfully and within scope and budget... great. Review the Rights and Roles spreadsheet... see if this still applies.
When showing entity lists in a Group/Subgroup context, lists are always pre-filtered to that Group/Subgroup. This filtering cannot be modified by the user.
- 👍 this happens today w/ the exception of Question Sets..., but what's missing is the added roles (like 'share w/ group', etc.) and the functionality around them.
  - IF in the MVP we can include a global search, then QS should be scoped to the group
  - IF we CAN'T... maybe we want to find an intermediate solution (having a tab, or section, of the list which shows global QSs)
When showing entity lists in the Explore menu or showing entities shared with the current in context group appearing in in-context group's entity list, the Entity's meta.group will be visible using 'pills'.

Data (drafts, responses, group memberships)

Data are passively (automatically) aggregated to parent groups. As a result, Entity lists show all Data from this Group/Subgroup and all its Subgroups.
- 👍 this is critical
Interactions with data always retain the original context defined in the data. For example, I am in group A, and see a response submitted by someone in group B (a subgroup of A). Resubmitting this response will not change the result’s submittingGroup. Changing the membership status of a member of a subgroup from the context of parent group equally does not change that members status in the parent group.
- 👍 this is critical
- ❓ so does this mean we show memberships from subgroups in higher level groups and generate appropriate UI to manage them in the top level group.
- Requires some UI screens or concepts here...
- Needs review of the interface w/ Dan and the 'derived' logic.
Data should be visible if and only if the current user, or the current users context, are directly listed in, or derived from evaluation from, the responses shareSettings.manage location. This applies in the Results page.
- e.g. shareSettings.manage.[x].role = "respondent" and the user is the response.meta.creator
- e.g. user is in group A context, and the response they are looking at has the following information: response.meta.group.id: <group_a_id> and shareSettings.manage.[x].agent: "respondent" and meta.creator: <this_user>. That would evaluate to allowing this user to view this data.
- 👍 this is critical
- Requires some review of edge cases. I'm an admin of Group A. Survey X is a public survey created in Group A. A person submitted a result in Group A to Survey X. I am also a member of Group B, which also allows submissions to Survey X. I am in Group B's context, and view Survey X results...
- Considerations
  - Users expect to stay in their group to see submissions to a Survey they are managing
  - There are technical reasons why haven't a 'survey x' page in every group isn't ideal
  - ... what's the right mechanism for doing this?
  - Let's ask... what's the most intuitive way to interact with results... you see a survey in group A, you want to see the results. What happens? If you are in a subgroup, you want to see the results.
Always inform the user of who has access to their submission before they start the survey. It addresses the problem described here, without over-designing because this is a minority use case. The information should include:
- Who can manage this submission? --> Admins of Group X and Group Y can view, edit, re-assign, and archive this response. They can also see your private results. Make sure you know and trust these groups before submitting sensitive information. If you expected others to help manage your submission you can try creating this response from another Group (learn more). Option --> (Continue) (cancel).
- 👍 this is critical
Inform users about their ability to filter at least the first time. The issue was discussed here, in short the problem is users will want to investigate data from many groups within their 'normal' without having to go somewhere.
- have popup highlighting the filter with option to 'not show again'.
- helps train the user, but they can turn off the after the first time. They should never end up with an empty table that shouldn't be empty (which would be really confusing).
- Also ensure easy filtering - click on pills adds a filter for that pill. This means a pill for a group will filter to that group. That makes accessing a filter (and learning about filters) even easier for users. Further, it reduces accidentally exiting of their group which (Dan pointed out) would be more likely to cause confusion and not be intentional.
- ❌ ❓ filtering is going to become a lot more important when we have rights and roles implemented... though I think it's still not MVP. This is important tho soon down the road.

Rights and Roles Spreadsheet

Link to Spreadsheet: https://docs.google.com/spreadsheets/d/19SqeZZXNWWttU1CYDGzE2lWW-hlA9yblDyxyAMP1XMI/edit?usp=sharing

This spreadsheet addresses the following:

When items are visible (connecting Actions to Rights)
Rules for entities when viewed outside their meta.group.id.
Where/how actions should appear in the card (menu, button, hover, order, etc.)
Listing of options for Rights and Roles (see second tab)

Data Structure, Entities and Data

// Questions... 
// I think having consistent `shareSettings` is helpful... what do you think?
// Long term goal is to map to things like Solid or other standards... what do you think?
// consider concept of using pointers and reserved terms (using $...) maybe there's better or more standard ways to do this... 
// consider changing 'shareSettings' to 'rights'... probably better...
// consider either using $respondent and using business logic to figure out who that should be (proxy, creator, resubmitter) OR just directly referencing them ($proxy, $creator, $resubmitter)...?

// Tests...
// - what if you change entity.meta.group?
// - what if user interacts with subgroup Results from Parent group Context?
// - could someone lose ability to see data they have rights to?
// - are actual rights maintained to data?  ie could a survey creator remove my rights to a submission?

// Overall benefits
// - shareSettings is structured the same way in Entities and Responses.  Consistent logic can be built to evaluate it in both places.  It can be specified as a schema (for all entities/responses) and subschemas (for just surveys, or just drafts)
// - shareSettings objects (like "edit", "view", "visible") can be clearly outlined and listed in a file.  This makes the roles and permissions structure more obvious and clear in the code
// - Additional shareSettings objects can be specified in the future (like "comment" or "custom_setting") as needs are identified.
// - shareSettings objects also line up with standard CRUD when possible (edit, view), and can expand to include delete (for Entity Creator for example, so that a single individual can prevent Admin deletions)
// - "agent" is the term used in WC3 Solid Web Access Control.  Agent allows specification of a group, a pointer which needs to be evaluates ($pointer), and potentially in the future could reference individuals (user names), etc.
// - "role" lines up with existing roles (admin, member), but could be expanded to additional roles in the future, or even custom roles.
// - could be structured as JSON Schema and is enforceable (enum's, requireds, etc.)

// Overall structure for entities (surveys, question sets, scripts)
// allows additional buckets of rights in future beyond 'edit', 'view', 'visible', like 'comment', etc..
const entity = {
    "meta": {
        "group": { // required
            "id": "entity_group_id", // required.  Changed by Entity Reassign.  Does not change connected Responses (if Survey)
        },
        "shareSettings": { // required
            "edit": [ // required
                { "agent": "$thisGroupOnly", "role": ["admin"] }, // required, fixed for now
            ],
            "view": [ // required
                { "agent": "$thisGroupOnly", "role": ["admin"] }, // required, fixed for now
            ],
            "visible": [ // required
                { "agent": "$public", "role": null }, // required, fixed for now
            ],
        }
    }
}

// Specific example for Surveys containing additional shareSetting options 
const survey = {
    "meta": {
        "group": { // required
            "id": "entity_group_id", // required.
        },
        "shareSettings": { // required
            "submit": [ // required
                { "agent": "$public", "role": null }, // set by user on creation
                { "agent": "a_custom_group_id", "role": ["admin", "member"] }, // set by user on creation
            ],
            "viewAnonResults": [ // required
                { "agent": "$public", "role": null }, // set by user on creation
            ],
            "edit": [ // required
                { "agent": "$thisGroupOnly", "role": ["admin"] }, // required, fixed for now
            ],
            "view": [ // required, fixed for now
                { "agent": "$thisGroupOnly", "role": ["admin"] }, // required, fixed for now
            ],
            "visible": [ // required, fixed for now
                { "agent": "$public", "role": null }, // required, fixed for now
            ],
        }
    }
}

// Structure for Responses / Drafts
// allows additional buckets of rights in future beyond 'manage', like 'comment' or 'view'.

const response = {
    "meta": {
        "group": {
            "id": "survey_group_id", // required, survey group... could change name if we want to surveyGroup... tbd
        },
        "submittingGroup": {
            "id": "submitting_group_id", // required, group submitted from
        },
        "creator": "f232efwef23r", // required
        "resubmitter": "f232efwef23r",
        "proxyUserId": "wef223fwefws",
        "shareSettings": { // required
            "manage": [ // required
                { "agent": "$surveyGroup", "role": ["admin"] }, // required, set by survey settings on response creation.  set role = [] for no access
                { "agent": "$submittingGroup", "role": [] }, // required, set by survey settings on response creation.  set role = [] for no access
                { "agent": "$respondent", "role": null }, // required, set by survey settings on response creation.  role = null because it's not relevant here.  $respondent evaluation must understand proxy v creator v resubmitter... 
            ]
        }
    }
}

Older notes

Response Data (include Responses, Drafts) must include:
1. surveyGroup: <surveyGroup of Survey> (not array)
  - defined at the time of Response creation and pulled from the surveyGroup of Survey.
2. submittingGroup: <context group at time of submission> (not array)
  - defined by the context group (URL) during submission. May be changed via re-assign.
3. shareSettings (object, must contain manage)
  1. manage (object, must contain only 2, referencing surveyGroup and submittingGroup) (❗ could break this up very granular, like edit, re-assign, delete, etc... or bucket those granular permissions into groups like 'manage'...).
    - { agent: 'surveyGroup', role: [admin] }, ... - surveyGroup admin's have access here
    - { agent: 'submittingGroup', role: [] }, ... - submitting Group does not have access here (role: [])
Entity Data (includes Surveys, Question Sets, Scripts). Must include:
1. group: <context group> (not array)
  - defined by an Admin when initiating Entity creation, based on current Context (URL).
2. shareSettings (object)
  1. submit (object, Surveys only) - defined by an Admin the time of saving Entity Settings (?).
    - Note: 'public', 'allGroup', 'subGroups', 'surveyGroup' are reserved IDs and are associated with logic used to determine rights at time of request.
    - { agent: 'public', role: null }, ... - public may submit
    - { agent: 'wholeGroup', role: [admin, member] }, ... - Whole Group may submit
    - { agent: 'subGroupsOnly', role: [admin, member] }, ... - Subgroups only may submit
    - { agent: 'thisGroupOnly', role: [admin, member] }, ... - This Entities Group/Subgroup only may submit
    - { agent: <custom_group>, role: [admin, member] }, ... - This specified Group/Subgroup may submit
  2. viewAnonResults (object, Surveys only) - defined by an Admin the time of saving Entity Settings (?) OR if agent: 'public' then new <custom_group> may be added by any group. This allows them to get the Entity to also show up in their Group's entity listing. ❗ this is mixing two things - visibility and sharing... but generally it makes the data structure simpler. Otherwise, we'd have to go back to the 'Add to' concept and have a separate type of flag for this.
    - Note: 'public', 'allGroup', 'subGroups', 'surveyGroup' are reserved IDs and are associated with logic used to determine rights at time of request.
    - { agent: 'public', role: null }, ... - public may view anonymized results
    - { agent: 'wholeGroup', role: [admin, member] }, ... - Whole Group may view anonymized results
    - { agent: 'subGroupsOnly', role: [admin, member] }, ... - Subgroups only may view anonymized results
    - { agent: 'thisGroupOnly', role: [admin, member] }, ... - This Entity's Group/Subgroup only may view anonymized results
    - { agent: <custom_group>, role: [admin, member] }, ... - This specified Group/Subgroup may view anonymized results
  3. edit (object, all Entities) - fixed, not customizable (yet).
    - { agent: 'thisGroupOnly', role: [admin] }, ... - This Entity's Group admins only
  4. view (object, all Entities) - fixed, not customizable (yet).
    - { agent: 'public', role: null }, ... - Survey Group admins only
  5. visible (object, all Entities) - fixed, not customizable (yet). User later w/ white labelled, private groups.
    - { agent: 'public', role: null }, ... - public may see in public lists (like Explore menu)

Entity Visibility Rules

Explore Menu (top middle search, user specifies Entity type listed)
1. Options in Explore are still in Group Context EXCEPT view.
  - Examples:
    - Clicking "Start Survey" from survey in Explore creates a Draft with the submittingGroup set to the current Group in Context.
    - Clicking "View Results" opens the results still in context (no change in base URL).
    - Clicking "View" opens the Entity in the current
Group Context (sidebar, user specifies Entity type listed

Edited Dec 01, 2024 by Greg Austic