Skip to content

document request reviewers #847

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

document request reviewers #847

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bdd624a
global: document request reviewers feature
zzacharo Aug 1, 2025
b82e40d
review comments
zzacharo Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions docs/maintenance/architecture/requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,22 @@ With the above examples in mind, a request ...

- is created by someone who can cancel it
- is received by someone who can accept or decline it
- may have reviewers assigned to provide feedback and recommendations
- may require clarifications (i.e. a conversation) between the creator of the request and the recipient(s)
- may expire after a certain amount of time

### Reviewers in Requests

Reviewers are optional participants in the request process who can be assigned to provide expert opinion, feedback, or recommendations. Unlike the receiver who makes the final decision to accept or decline the request, reviewers serve as consultants or advisors.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would use the terms consultant or advisor:

Suggested change
Reviewers are optional participants in the request process who can be assigned to provide expert opinion, feedback, or recommendations. Unlike the receiver who makes the final decision to accept or decline the request, reviewers serve as consultants or advisors.
Reviewers are optional participants in a request process. They provide expert opinions, feedback, or recommendations but cannot make the final decision to accept or decline the request. That responsibility lies solely with the receiver.


Key characteristics of reviewers:
- Can be individual users or groups
- Multiple reviewers can be assigned to a single request
- Do not have direct authority to accept or decline the request
- Provide input through comments and feedback in the request timeline
- Can be added or removed throughout the request lifecycle
- Have specific permissions to view and comment on the request

## Entities

The key entities in the data model:
Expand All @@ -53,14 +66,16 @@ The key entities in the data model:
- Request actions associated to a given request type.
- Request events and comments
- Entity references
- Reviewers (optional entities that can provide feedback and recommendations)

## Properties

A request has four key properties:
A request has five key properties:

- **Creator** - the entity creating request
- **Topic** - the entity the request is about
- **Receiver** - the entity the request is addressed to
- **Reviewers** - optional entities assigned to review and provide input on the request
- **Status** - the state a request is in

## Statuses
Expand Down Expand Up @@ -108,7 +123,7 @@ Note, we do not allow updating closed requests.

## Entity references

Entity references is an abstraction that allows any type of creator, topic and
Entity references is an abstraction that allows any type of creator, topic, reviewer and
receiver to be modelled.

Technically it's just a type and persistent identifier. Below is an example of
Expand Down Expand Up @@ -140,7 +155,7 @@ user have access to.
An entity grant is a combination of:

- Prefix - The prefix qualifies the grant within the record (e.g. ``creator``,
``receiver``, ``read``, ``write``).
``receiver``, ``reviewers``, ``read``, ``write``).
- Permission need - Entity reference as a permission need (e.g ``UserNeed(1)``).

*Permission needs* are just tuples. Below you find examples of permission
Expand All @@ -156,6 +171,7 @@ into a token that we can use for querying:
Examples for entity grant tokens:

- ``creator.user.1`` - expresses that the creator.user.1 is granted access.
- ``reviewers.group.review-board`` - expresses that the group review board is granted access.
- ``receiver.community.123.manager`` - expresses that the community 123
managers are granted access.

Expand Down
72 changes: 72 additions & 0 deletions docs/operate/customize/requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Requests

_Introduced in InvenioRDM v14_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
_Introduced in InvenioRDM v14_
_Introduced in v14_


Configure the requests system in InvenioRDM, including the reviewers feature for enhanced review workflows.

## Reviewers Configuration
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should use CamelCase for titles (as always suggested by LLMs). Applicable to all new titles.

Suggested change
## Reviewers Configuration
## Reviewers configuration


The reviewers feature enables assignment of external experts, collaborators, or community members to provide feedback on requests without granting them decision-making authority.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The reviewers feature enables assignment of external experts, collaborators, or community members to provide feedback on requests without granting them decision-making authority.
The reviewers feature enables assignment of external experts, collaborators, or community members to provide feedback on requests without granting them the possibility of accepting or declining a request.


### Enable/Disable Reviewers

```python
# Enable the reviewers feature (default: True)
REQUESTS_REVIEWERS_ENABLED = True
```

### Reviewer Limits

Control the maximum number of reviewers that can be assigned to a single request. This helps manage workflow complexity and ensures review processes remain manageable.

```python
# Maximum number of reviewers per request (default: 10)
REQUESTS_REVIEWERS_MAX_NUMBER = 5
```

- **Purpose**: Prevents overwhelming requests with too many reviewers
- **Considerations**: Balance between comprehensive review and manageable workflow

### Group Reviewers

Enable the assignment of user groups as reviewers, allowing entire teams or committees to be assigned to review requests collectively.

```python
# Enable assignment of groups as reviewers (requires invenio-users-resources)
USERS_RESOURCES_GROUPS_ENABLED = True
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove this flag (from the code): if groups is enabled, why having this extra flag? Any benefit?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is the flag that enable groups in the system, it was not newly added.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah right, then in the doc it is not super clear, in particular the comment

```

- **Requirements**: Requires the `invenio-users-resources` module to be installed and configured
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's always the case in InvenioRDM

Suggested change
- **Requirements**: Requires the `invenio-users-resources` module to be installed and configured

- **Use cases**:
- Institutional Review Boards (IRBs)
- Editorial committees
- Subject matter expert panels
- Department review teams
- **Behavior**: All members of the assigned group receive access to view and comment on the request
- **Notifications**: Group members may receive notifications based on your notification configuration

## Usage

When enabled, community curators, managers and owners can:

- Assign individual users or groups as reviewers to any request
- Share requests with external experts outside the community
- Grant access to community members who normally wouldn't see requests (e.g., readers)
- Allow multiple reviewers to provide independent feedback
- Track all reviewer interactions in the request timeline

Reviewers can view the request, participate in conversations, and provide recommendations, but cannot accept or decline the request.

## Permissions

Reviewer assignment requires appropriate community permissions:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Reviewer assignment requires appropriate community permissions:
By default, reviewer can be added or removed by community members with roles:

Can the submitter assign reviewers?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We decided not to allow them in the first implementation.

- **Owners** and **managers** can assign/remove reviewers
- **Curators** can assign/remove reviewers (if configured)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how do I configure it?

- **Reviewers** can view and comment on assigned requests
- **Readers** cannot assign reviewers but can be assigned as reviewers

## Related Configuration

See also:
- [Communities](../../use/communities.md#requests) - User guide for requests and reviewers
- [Architecture documentation](../../maintenance/architecture/requests.md) - Technical overview of the requests system
4 changes: 3 additions & 1 deletion docs/use/communities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,4 +126,6 @@ In the **Requests** tab, you can view all requests for your community. It allows

The request page provides a dedicated space for communication. You can **have a conversation with the submitter** directly within the request, and you can **accept or decline the inclusion request** based on your community's curation policies.

You can find the high-level architecture documentation for communities [here](../maintenance/architecture/communities.md).
When a submission requires expert input or peer review, you can **assign reviewers** to give specific users or groups access to evaluate the request. This allows you to share the request with external experts, collaborators outside your community, or community members who normally wouldn't have access (such as readers). Reviewers can provide feedback on the research publication draft or assess whether a record meets your community's inclusion criteria. They participate in the request conversation and share their expertise to help you make an informed curation decision, while you retain the final authority to accept or decline the request.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When a submission requires expert input or peer review, you can **assign reviewers** to give specific users or groups access to evaluate the request. This allows you to share the request with external experts, collaborators outside your community, or community members who normally wouldn't have access (such as readers). Reviewers can provide feedback on the research publication draft or assess whether a record meets your community's inclusion criteria. They participate in the request conversation and share their expertise to help you make an informed curation decision, while you retain the final authority to accept or decline the request.
When a submission requires expert input or peer review, you can **assign reviewers** to give specific users or groups access to review the inclusion request. This allows you to share the request with external experts, collaborators outside your community, or community members who normally wouldn't have access (such as readers). Reviewers can provide feedback on the research publication draft or assess whether a record meets your community's inclusion criteria. They participate in the request conversation and share their expertise to help you make an informed curation decision, while you retain the final authority to accept or decline the request.

while you retain the final authority to accept or decline the request.

Unclear, who is you?


You can find the high-level architecture documentation for communities [here](../maintenance/architecture/communities.md) and configuration options for requests and reviewers [here](../operate/customize/requests.md).