UX for changing document rights

[MichaelHamann]

Hi everyone,

this is another proposal regarding document rights, this time about the user experience. As a short reminder, the idea of document rights is to have a new property on each document that controls which rights the content and objects of that page can have, and, at the same time, restricts editing to users with these rights. Basically, at least initially, there will be the following options:

1. Legacy mode, the rights of the last author apply and anybody with edit right can edit - default for existing documents.
2. No scripting, regardless of the rights of the author no script or programming right is available - default for new documents.
3. Script right, script right but not programming right is available if the last author has it, only users with script right can edit.
4. Wiki admin right, script right and wiki admin right are available if the last author has them (e.g., for wiki macros or UIX), only users with wiki admin right can edit.
5. Programming right, all rights are available if the last author has them, only users with programming right can edit.

These options will be in the page information tab and in the panel during editing as previously discussed. Note that back then we called this concept required rights, but I’m using the term document rights for the same concept now to avoid confusion with the recently introduced required rights application.

What I would like to discuss here is when and how we should propose setting document rights. Thanks to the aforementioned required rights application, we have analyzers that can tell us which rights a document should have. There are cases where we’re sure that a right is needed, for example, a Velocity macro needs script right, and there are cases where a right could be needed, but a manual review is needed to confirm this, for example, a Velocity macro could also need programming right depending on the actually called methods.

Based on the analysis result, we can suggest one of three options:

1. Suggest setting a document right for documents that are using the legacy mode. This means basically changing from the first value to any of the other values.
2. Suggest adding rights when a document contains a macro or XObject that needs more rights than the document has. This means changing from a value 2, 3, 4, or 5 to a higher value.
3. Suggest removing rights when a document no longer contains any macro or XObject that needs them. For example, after removing the last script macro, script right should be removed to allow editing by users without script right.

What we should consider here is that the first operation is basically migration support and not strictly necessary. We could also just provide a tool for admins to perform this migration.

The second operation is crucial to make it easy to use script macros, but it is potentially dangerous as the rights will be granted to all and not just new content.

The third operation is not crucial, but having the least possible rights is desirable also to allow editing by as many users as possible, so we should support users with that. It could, however, also happen that we’re missing an analyzer and a right is required even though we cannot detect it. This would be a bug but still means that we shouldn’t push users too aggressively to remove rights.

My ideas for this are the following:

1. Display hints about all three operations in the page information tab with buttons to perform them if we’re certain and display a less strong hint when manual review would be required. In all cases, if the analysis identified any elements requiring rights, the analysis result will be shown in a dialog.
2. When performing operation 2, require the user to see the full analysis result that includes all script contents, for example, by placing the confirmation button below the content. Also, enable the confirm button only after a timeout of a few seconds.
3. When saving, suggest operation 2 when new rights are required. So, for example, when saving after adding the first Velocity macro, a dialog would show all script macros and suggest enabling either script or programming right. However, when the user select script right, there won’t be any request to enable programming right when saving again unless the user added, e.g., a Groovy macro that always needs programming right.
4. In error messages about missing script right, display a button to enable script right when the user has it - this would again show the dialog with the analysis result.

I’m also wondering if we should display certain hints, in particular about operation 1, only to advanced users. For operation 2 and 3 to be available, the user would need at least script right, anyway, so I think they could be displayed to all users with the respective rights.

While we could already suggest enabling a right when a macro or XObject is added, in many cases the rights depend on the macro parameters, macro content or XObject fields. Therefore, I fear this would be too early and could result in several, annoying prompts when the user changes values several times.

Do you have any feedback for these ideas?

[vmassol]

@MichaelHamann

Note that back then we called this concept required rights, but I’m using the term document rights for the same concept now to avoid confusion with the recently introduced required rights application.

I think we might need to find a better term because for me “document rights” are the standard rights for documents, i.e. view, edit, delete, script, programming, etc. Basically https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Access%20Rights/. Unless you’re considering that it’s the same topic? (ie same module in the code, same documentation page). Maybe “Computed Document Rights” or “Content Rights” (short for “Content-based Document Rights”).

@MichaelHamann

Do you have any feedback for these ideas?

Sounds good globally. We need to be careful that it’s not painful to use, and hide the maximum for simple users. But I see you already started thinking with these constraints. It would be simpler to visualize when there’s some wireframes for it or some preliminary implementation.

One point is that I think we eventually might need a new Rights extradoc tab and not use the Information tab. The reason is that the info tab is already quite heavy in content and we already have had lots of requests in the past, for a way to view the computed rights for the current page, and a Rights tab could accomodate that need in the future + those special rights options.

Thanks

[mleduc]

Thanks again for working on this difficult topic. I’m +1 for the general idea.

The main difficulty as you mentioned is to handle uncertainty, false-positive (and/or the lack of accurate analysis). And, to make sure this is conveyed in a clear way to users.

I’m digressing but do you think we could make some of those document rights enabled implicitly?
For instance:

• and user with script right edit a new document with no script rights, and is not editing realtime with other users
• the user adds a velocity macro

At this point, do you feel like granting script right to the document deserves user confirmation, or can it just be done transparently?

For the rest, I agree with Vincent that having wireframes could help understand the experience from a user point of view.

[tkrieck]

Hey everyone, jumping onto this topic.

@vmassol

Maybe “Computed Document Rights” or “Content Rights” (short for “Content-based Document Rights”).

Maybe “Necessary Rights”? Yes, it is the same as Required Rights, but at least using a synonym to keep it different from the Required Rights App. I worry that using something as “Content Rights” can send the message of rights as in ‘copyright’. Meaning the user that has rights over that content. I might be overthinking this, but our usage of the word “Rights” usually is “Permission” on other software.

@mleduc

At this point, do you feel like granting script right to the document deserves user confirmation, or can it just be done transparently?

IMO, user confirmation is important the first time when adding content to a document that can unknowingly render edits by another user impossible. Something like: “The macro XYZ requires that editing users have the script permission. Proceed with the addition?” From now on the document have the required rights set and this confirmation will no longer appears, unless there’s an escalation of required right (to Admin for example).

@mleduc

For the rest, I agree with Vincent that having wireframes could help understand the experience from a user point of view.

On it =)

[tkrieck]

Hey everyone, I spent the week on the docs and designing some options for this work. It took a little longer than I anticipated because of the complexity of the topic.

@MichaelHamann

These options will be in the page information tab and in the panel during editing

Something like this?

Note that the “analyze rights” link would be shown for advanced users only. When clicking it, we can have a dialog informing the suggestions of operations based on @MichaelHamann options:

1 - Suggest setting a document right for documents that are using the legacy mode;
2 - Suggest adding rights and;
3 - Suggest removing rights;

Example:

@MichaelHamann

While we could already suggest enabling a right when a macro or XObject is added, in many cases the rights depend on the macro parameters, macro content or XObject fields. Therefore, I fear this would be too early and could result in several, annoying prompts when the user changes values several times.

If it’s something that would appear only the first time that an escalation is necessary, I don’t see a problem in having the suggestion:

Dashboard / Extradoc Tabs

@vmassol

One point is that I think we eventually might need a new Rights extradoc tab and not use the Information tab. The reason is that the info tab is already quite heavy in content and we already have had lots of requests in the past, for a way to view the computed rights for the current page, and a Rights tab could accomodate that need in the future + those special rights options.

I still don’t know the best place for it, but I feel it could be in the Rights section of the administration pages. Or maybe both, a Rights tab on the document (for advanced users) AND on the Admin pages.

@MichaelHamann told me of a proposal by @evalica that could be used as an inspiration for the dashboard (https://design.xwiki.org/xwiki/bin/view/Proposal/RightsUI9xCheck). So I did the one below. In this mockup the user selects a page and a user on the top fields and details are shown below them.

Inputing pages and users should feature a search or autocomplete.

The table of computed rights feature the following conventions for the markings

The information at the top of the table is the most granular, meaning it can have inherited rights from entities that are shown on the table rows below it.

Because the computation of rights for pages can have a long list of entities we have a Load All button besides the page name. Expanding it would look like below:

Here we can see that “Example Page” is inheriting the Scripting Right requirement from “Page AB” and that the basic editing right is set on the Wiki level. Both are explicit at their origins, denoted by the blue filled background on the asterisk.

The same way works for the rights for our example user “Jane”. She has all her permissions inherited from groups that are shown in the rows below her username.

Some other examples:

User John
Here, John doesn’t belong to the group “Editors” and he does not have the required Right explicitly given to him. So he can’t edit “Example Page”

User Alex
Alex can’t edit as well, while he belongs to “Editors”, he explicitly has the “Deny” on Scripting Rights.

There’s still a lot to show, but honestly I don’t know how. Especially the rules from this table:

XWiki

Perhaps a link to a documentation.

I am sure a lot of details still need to be defined on the UI, but I wanted to show what I have now and gather your feedback on it.

Please let me know if there’s something that’s not clear or that can improve.

Thank you all for reading.

[vmassol]

@tkrieck

Something like this?

I don’t understand the screenshot. It says “required rights” (and “This pages requires the following rights”) and then below “edit rights”. Required rights for what? For view? for edit? for delete? for … ?

Obviously you don’t need edit rights to view a page for example.

@tkrieck

If it’s something that would appear only the first time that an escalation is necessary, I don’t see a problem in having the suggestion:

For macros, there’s a proposal at Add concept of required permissions for Macros to not show macros for which you don’t have the rights. The intent is to increase usability by not overflowing the user with concepts or knowledge that he/she doesn’t have (like proposing scripting macros when you don’t have scripting rights because you’re a standard user supposed to only add content in your wiki for ex).

@tkrieck

I still don’t know the best place for it, but I feel it could be in the Rights section of the administration pages. Or maybe both, a Rights tab on the document (for advanced users) AND on the Admin pages.

I still believe that we need to show users who are not admins why they cannot edit a page for example, at least advanced users.

Ofc we need an admin page to set and view rights and inherited rights globally. Asking for computing the rights of a given user could also be in the admin UI but I think being in an extradoc tab is interesting for advanced users too.

Re your proposed UI based on Caty’s, I haven’t evaluated it, it’s been discussed a lot in the past and it’s a complex topic to be sure to represent the computed rights properly (might not even be possible and might need a new rights store or get them from the security cache or …). I’ll let others more qualified than me start the discussion on this.

It seems this thread is mixing the doc rights with the required rights. I still don’t understand at this stage if they’re the same thing or not.

Thx

[CharpentierLucas]

A couple quick notes about the designs:

@tkrieck

Here, it seems like Analyse Rights triggers the action of opening a modal. Therefore, it should be styled like a button and not a link. If we decide the dialogue is done in another page then it can make sense to use a link (even though IMO it would still look better with button styling).

---

@tkrieck

We need to make sure there’s an easy way for users to see this. It could be a help button that opens a modal, so that it doesn’t clutter the UI for users that already understand it, but trying to make sense of the rights details below without being able to find easily the meaning of all these symbols would be difficult IMO.

Thanks for your work on this UI!

Lucas C.

[tkrieck]

Hey everyone,

@vmassol

I don’t understand the screenshot. It says “required rights” (and “This pages requires the following rights”) and then below “edit rights”. Required rights for what? For view? for edit? for delete? for … ?

The purpose of this area is to show the user what rights are to edit the document. Perhaps my choice of words in this section was not the best. Below is a better example.

Also, thanks @CharpentierLucas for the heads up. I edited the section to use a button instead of a link.

@CharpentierLucas

We need to make sure there’s an easy way for users to see this.

Agreed, a tooltip in each icon can also have this effect, however I don’t know how accessible this would be.

[CharpentierLucas]

@tkrieck

Agreed, a tooltip in each icon can also have this effect, however I don’t know how accessible this would be.

As long as the implementation takes into account accessibility, there’s no fundamental problem with it
See for example Tooltip Pattern | APG | WAI | W3C

[MichaelHamann]

@tkrieck

Something like this?

Note that the “analyze rights” link would be shown for advanced users only. When clicking it, we can have a dialog informing the suggestions of operations based on @MichaelHamann options:

1 - Suggest setting a document right for documents that are using the legacy mode;
2 - Suggest adding rights and;
3 - Suggest removing rights;

Example:

While these proposals look good in general, I have some questions and suggestions:

1. I think the wording needs to be improved further. While you adapted it already to state that these rights are required for editing, what isn’t conveyed in my opinion is that these are also the rights to which content of this page is restricted. The user should understand that, for example, if script right isn’t set, no script macros can be used in the page. Maybe there could be a short text that is always displayed that links to some help page or allows expanding a longer explanation to further explain this topic?
2. How would this look like when required rights aren’t enforced? In that case, only the rights of the last author count and there should be an action that encourages advanced users (and admins?) to enable enforcing required rights in order to increase security - of course only if they have the rights that are found by the required rights analyzer.
3. I would suggest running the required rights analysis already when displaying the information tab (we could cache it if it should turn out to be too costly, but it should actually be faster than displaying the page content itself) and then to propose different actions:
4. Grant additional required rights if the analysis indicates that rights are definitely missing. This should always be displayed if the current user has these rights. This is because the page is very likely broken and granting these rights fixes the page. We could even think about displaying such an action at the top of the page.
5. Remove rights if they aren’t needed. This should only be suggested to advanced users and the suggestion should be weaker as the indication could be wrong - initially, there could be macros or XObjects in particular from extensions that are missing an analyzer and therefore aren’t recognized.
6. Manually change required rights even though no action is suggested by the analyzer. Users should be able to define any right even if the analyzer says that everything is fine. A frequent variant of this will be that the analysis says that a right might be needed, but manual review is required. What I would suggest is to always have a small edit icon, and maybe for advanced users a summary of the analysis result that, e.g., indicates that a script could potentially need programming right.

In theory, a page could be both missing rights and not needing rights. This can only be the case when required rights are used in combination with extension rights which will be possible but initially not the case. Still, I think this is something we should take into account.

Where we need to be careful in the popup is that rights can imply other rights. For example, a page that currently requires programming right has all rights. A page might not need programming but scripting right. In this case, the suggested action should be to remove programming and to add scripting right.

In the rights analysis popup, the user should have the option to review all content that requires rights in order to be able to make an informed decision similar to the warnings that we currently have (those warnings won’t be displayed anymore when required rights are enforced on a page). There should be an emphasis on the content that will get more rights by the proposed action (e.g., when a page has already script right and the proposal is to grant programming right, an HTML doesn’t need to be highlighted as nothing changes for it, but a groovy macro should be highlighted).

[tkrieck]

Hi @MichaelHamann,
Thanks for the thorough feedback. I refactored some of my mockups to make the analysis dialog a little bit more clear. I hope I haven’t gone too overboard with my changes.

Rights Analysis Dialog

The dialog has undergone significant updates in both its layout and text content to improve clarity and visual communication. It now clearly displays the current rights associated with the document and any proposed changes, using a visual hierarchy to represent the relationship between different rights. For example, “Programming” rights automatically include “Scripting” rights, and “Scripting” rights include “Editing” rights.

To convey this hierarchy, color and iconography are used:

• Hue and brightness: A darker blue indicates the current and proposed rights, while a lighter blue represents rights that are inherited.
• Arrow icons: Placed above the current and proposed rights names.

The other rights are shown to provide additional context, helping users understand the full scope of permissions associated with the document.

It is essential to note that these elements are purely informational; they are not interactive buttons and should not suggest any clickability. This should be relatively easy to make with CSS

In the Proposed Rights section, there’s also a “More Details” area that can be opened to check the individual steps that will be taken upon confirmation.

This dialog also features more objective buttons (Confirm Proposed Changes) and also a link to documentation and to the Rights Admin screen.

Some other configurations for this dialog

Rights De-escalation

Rights Escalation

Information Tab

I cleared a little bit the field on the information tab and also differentiated it for Simple and Advanced User.

Simple Users

For simple users, this section is very light on default info and provides a “More Information” link to an informative dialog (see section below).

Page not enforcing Rights:

Page enforcing Rights:

Advanced Users

For advanced users, this section provides the same info for simple users + brief information about the Rights Analyzer. To review these recommendations, there’s a link called “Review Recommendation” which opens the dialog explained above.

Different states for this field:

Rights enforced, with ADD and REMOVE recommendation

Rights Enforced, with REMOVE recommendation:

Rights enforced, width ADD recommendation:

Rights enforced, no recommendation:
In this case, because there’s no recommendation to review, a link to the Manage Rights screen is shown

More information Dialog

This dialog is mainly for simple users as it explains a little bit what these rights are and don’t provide any interaction, it’s an informative screen only accessed from the “More Information” link explained above. Here we’d also have the visual representation of Rights.

WDYT?

[MichaelHamann]

As I’m now a bit further into the implementation I noticed that in many cases there will actually be two recommended actions where the user basically needs to decide. There could also be more, but this should be rare. The situation will usually be that a page contains a script macro and this script requires either script or programming right. We can be sure that script right is needed, but we don’t know if programming right is needed. The instruction for the user is basically to review the analysis result that we should display that includes the content of the analyzed script macros or XObjects. It depends on the analyzed object what we display, it follows a screenshot we display this in the current warning dialog:

Notice that there can be several sections for different parts of the document (like XObjects) and for each result we have a short description and then a detailed display of the actual content with key-value pairs and an optional hint. We display these boxes collapsed by default, I’ve expanded them for the screenshot to show their contents.

Do you have any suggestions how to arrange the choice and the detailed analysis results in the proposed dialog?

[tkrieck]

I can see that this dialog can become quite text heavy on the UI.

In this case, I would recommend progressively disclosing all the information to the user. We start with the simplest UI possible and based on interactions we detail more and more.

Initial state
Show only the current rights and the proposed one

I changed colors a bit to not give false impressions of something that looks interactive, but it is not (the Rights hierarchy flow).

Now we show three buttons at the bottom of the dialog, one for each Right, but only make primary the one that would allow editing the whole content by the user. If no recommendation can be made, then show them all as secondary

The user can then choose to review the recommendation using the “Why this is being recommended” link.

Opening “Why this is Recommended?”

There’s no option to go back to the previous interaction, once the detailing of the Rights is open, it stays that way.

But each recommendation has an expand/collapse button to check the individual pieces of code that requires the new Right.

Expanding a section

Scroll bars

And of course this dialog can become quite tall, so it’s important to provide a scroll bar when necessary, but the buttons should always be visible.

This progressive disclosure, while requiring more interactions, is done this way to not overwhelm our user with (very technical) information right from the start, which I consider more harmful. What do you think?