← Back to packages

Package snowballr

Service SnowballR

Message AuthenticationStatusResponse

Message Author

Message AvailableExportFormatsResponse

Message AvailableFetchers

Message Blob

Message BoolValue

Message Criterion

Message Criterion.Create

Message Criterion.List

Message Criterion.Update

Message Email

Message ExportRequest

Message ExportResponse

Message FetcherOptions

Message GetAvailableFetcherOptionsRequest

Message Id

Message LoginRequest

Message Nothing

Message Paper

Message Paper.List

Message Paper.PdfUpdate

Message Paper.SearchQuery

Message Paper.Update

Message PasswordChangeRequest

Message PasswordResetRequest

Message Project

Message Project.Create

Message Project.Information

Message Project.Information.DecisionStatistics

Message Project.Information.DecisionStatistics.Get

Message Project.Information.DecisionStatistics.Statistic

Message Project.Information.Get

Message Project.InviteCandidatesRequest

Message Project.List

Message Project.Member

Message Project.Member.Accept

Message Project.Member.Invite

Message Project.Member.List

Message Project.Member.Remove

Message Project.Member.Update

Message Project.Paper

Message Project.Paper.Add

Message Project.Paper.Get

Message Project.Paper.List

Message Project.Paper.SearchQuery

Message Project.Paper.Update

Message Project.Settings

Message Project.Update

Message RegisterRequest

Message RequestPasswordResetRequest

Message Review

Message Review.Create

Message Review.List

Message Review.Update

Message ReviewDecisionMatrix

Message ReviewDecisionMatrix.Pattern

Message ReviewDecisionMatrix.Pattern.Entry

Message User

Message User.List

Message User.Update

Message UserSettings

Message UserSettings.Update

Message VerifyEmailRequest

Enum AuthenticationStatus

Enum CriterionCategory

Enum MemberRole

Enum PaperDecision

Enum ProjectStatus

Enum ReviewDecision

Enum SnowballingType

Enum UserRole

Enum UserStatus

Services

service SnowballR main.proto

This service contains the complete set of API calls that the SnowballR web application uses to communicate with the backend.

Overview

SnowballR is a tool designed to assist with scientific research by organizing and managing structured literature reviews (SLRs). The application is split into a web frontend and a backend on a central server. The frontend is a web application that runs in the user's browser. The backend runs on a server and contains most, if not all, of the application logic. It tracks all data by accessing a database and makes requests to external resources like paper databases.

architecture-beta
 group frontend(internet)[Frontend]
 service browser(internet)[Browser] in frontend

 group backend(server)[Backend]
 service server(server)[SnowballR Server] in backend
 service db(database)[Database] in backend

 group external(internet)[External Resources]
 service fetcher1(internet)[External Paper Database 1] in external
 service fetcher2(internet)[External Paper Database 2] in external

 junction j1 in external
 junction j2 in external

 browser:R --> L:server

 server:B --> T:db
 server:R -- L:j1

 j1:R -- L:j2
 j1:B --> T:fetcher1
 j2:B --> T:fetcher2

Authentication

A padlock icon in the top-right of a service method description indicates whether a call requires the user to be authenticated. This will happen automatically using an HTTP-only cookie set by the server during registration or login. If the authentication fails, an UNAUTHENTICATED error will be returned in all cases.

Error Handling

Furthermore, the server may respond with the UNAVAILABLE error code at any time if it is unable to process a request. It may also respond with the INTERNAL error code if some unknown server-side errors occur. If the field mask is empty or contains an invalid format the server returns an INVALID_ARGUMENT error. This includes cases where the mask specifies fields that are not defined in the target object type. The error description provides additional details.

Each error should come with a meaningful description, detailing the nature of the error that occurred.

Update Semantics

Updates are applied atomically. If one part of an update request cannot be fulfilled, the entire update fails and no changes are persisted. If the field mask specifies a field that is not allowed to be updated, the update request is rejected. In this case, the server responds with an INVALID_ARGUMENT error.

Enums and Guarantees

Each enum contains an _UNSPECIFIED variant to indicate that no meaningful value was set. If any other variant is present, the field is considered to be specified.

The word guaranteed may only convey meaning in the context of this contract. Due to the nature of the underlying network communication, results can never really be guaranteed, so proper error handling is advised anyway. In the following context, guaranteed denotes a situation in which the client shall be able to safely make assumptions about a successfully received message.

Entities and Relationships

The following figure shows the relationships between the entities/concepts of the SnowballR application. It does not depict the actual database schema used by SnowballR's backend; rather, it provides a broader understanding.

erDiagram
 direction LR

 Project 0+ -- 0+ User : "member of"
 Project 1 -- 1 ProjectSettings : has
 Project 1 -- 0+ ProjectPaper : contains
 Project 1 -- 0+ Criterion : contains

 ProjectSettings 0+ -- 1+ Fetcher : "fetches from"

 ProjectPaper 1 -- 0+ Review : has
 ProjectPaper 1 -- 1 Paper : "refers to"

 Review 0+ -- 1 User : by
 Review 0+ -- 0+ Criterion : "ticks off"

 User 1 -- 1 UserSettings : has
 User 0+ -- 0+ Paper : "on reading-list of"

Disclaimer:

Access control for these calls has not yet been fully worked out. Consequently, the required role for any call may change at any time.

rpc GetAvailableFetchers
Request: Nothing
Response: AvailableFetchers

Get all available fetchers from which a paper may be sourced by the backend. Each source is identified by a unique string and is later used to specify which APIs will be used by a project to collect papers. The list is guaranteed to be non-empty but may change at any time.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc GetAvailableFetcherOptions
Request: GetAvailableFetcherOptionsRequest
Response: FetcherOptions

Get all available options for the specified fetcher. The names and default values of the available options are returned as a string map. Each option name can only appear once. Note that there may be no available options.

Errors

Error Code Description
NOT_FOUND The fetcher with the provided name was not found.
UNAUTHENTICATED The user is not signed in.

rpc Register
Request: RegisterRequest
Response: Nothing

Create an account. The provided email address must not already be registered, and no field may be blank. If successful, login tokens are provided, which are used automatically for subsequent calls.

The password string is required to

  • be at least eight characters long,
  • contain at least two lower-case letters,
  • contain at least two upper-case letters,
  • contain at least two digits,
  • and contain at least two special characters.

Errors

Error Code Description
INVALID_ARGUMENT At least one input did not meet the requirements: The email must be a valid email address, the password must meet the previously stated criteria, and the first_name and last_name must not be left blank.
ALREADY_EXISTS An account with the provided email address is already registered.
INTERNAL The verification email could not be sent.

rpc VerifyEmail
Request: VerifyEmailRequest
Response: Nothing

After registering, a user receives a verification token via email. This call is then used to submit that token, confirming the ownership of the email address and activating the user account.

Errors

Error Code Description
INVALID_ARGUMENT No token was provided.
NOT_FOUND The provided token is invalid, could not be found, or has expired.

rpc Login
Request: LoginRequest
Response: Nothing

If the provided email address and password exactly match those of a user in the server's database and the user's email address has been verified, a new set of login tokens is provided to authenticate as that user. Old access and refresh tokens will remain valid. These credentials are handled automatically and do not require any further attention.

Errors

Error Code Description
INVALID_ARGUMENT The email address is not a valid email address or no password was provided.
UNAUTHENTICATED The email address is not registered (anymore) or verified, or the password is incorrect.

rpc Logout
Request: Nothing
Response: Nothing

Revoke access through the currently used set of access and refresh tokens. Other token pairs may not be affected.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc GetAuthenticationStatus
Request: Nothing
Response: AuthenticationStatusResponse

Acquire the client's authentication status. The result is guaranteed to be specified.

Errors

No additional errors may occur.

rpc RenewSession
Request: Nothing
Response: Nothing

Upon presentation of a valid refresh token, a new set of login tokens is issued, authenticating the owner of the token. This new pair is guaranteed to contain valid credentials. The refresh token may change too. These credentials are handled automatically and do not require any further attention.

Use this call if the access token has expired, as it does not require the user to be authenticated using an access token. Instead, the validity of the accompanying refresh token — which is also set by Register and Login — is confirmed.

Errors

Error Code Description
UNAUTHENTICATED The refresh token is invalid.

rpc RequestPasswordReset
Request: RequestPasswordResetRequest
Response: Nothing

If the provided email address belongs to an active user, the server sends a challenge/token to that address. This token must then be sent alongside a new password (see ResetPassword) in order to update a lost or forgotten password.

Errors

Error Code Description
INVALID_ARGUMENT The email address is not a valid email address. If the email address is valid, but has not yet been registered, this error does not occur.
INTERNAL The verification email could not be sent.

rpc ResetPassword
Request: PasswordResetRequest
Response: Nothing

After requesting a password reset email using RequestPasswordReset, this call may be used to actually set the new password. To verify the ownership of the account, the token sent via email must also be provided and valid. The new password must follow the same rules as during registration.

Errors

Error Code Description
INVALID_ARGUMENT Either the provided token is invalid, or the new password does not meet the rules specified in Register.
FAILED_PRECONDITION The user is not active (i.e., in state USER_STATUS_ACTIVE).
UNAUTHENTICATED The provided token could not be found or has expired.

rpc ChangePassword
Request: PasswordChangeRequest
Response: Nothing

Set a new password using the old password. The new password must follow the same rules as during registration. This serves no recovery purpose and is for user convenience only.

Errors

Error Code Description
INVALID_ARGUMENT Either the provided old password is incorrect, or the new password does not meet the rules specified in Register.
FAILED_PRECONDITION The user is not active (i.e., in state USER_STATUS_ACTIVE).
UNAUTHENTICATED The user is not signed in.

rpc GetAllUsers
Request: Nothing
Response: User.List

Get all registered users.

Errors

Error Code Description
PERMISSION_DENIED The calling user is not a server admin.
UNAUTHENTICATED The user is not signed in.

rpc GetCurrentUser
Request: Nothing
Response: User

Get the user who is currently logged in by looking up the provided access token. If the user is properly authenticated, this call is guaranteed to return a valid user.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc GetUserById
Request: Id
Response: User

Get a user by their ID.

Errors

Error Code Description
INVALID_ARGUMENT The user ID is not a valid UUID.
NOT_FOUND No user with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the same project as the requested user.
UNAUTHENTICATED The user is not signed in.

rpc GetUserByEmail
Request: Email
Response: User

Get the user with the specified email address.

Errors

Error Code Description
INVALID_ARGUMENT The email address is not a valid email address.
NOT_FOUND No user with the provided email address was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the same project as the requested user.
UNAUTHENTICATED The user is not signed in.

rpc UpdateUser
Request: User.Update
Response: User

Update all attributes specified in the field mask for the user with the provided ID, except the status field. A server admin may update the role field using this call. The updated user is returned and guaranteed to be specified.

Errors

Error Code Description
INVALID_ARGUMENT At least one (updated) user detail did not meet the requirements: The id must be a valid UUID, the email must be a valid email address, the first_name and last_name must not be left blank, and the role must be specified.
NOT_FOUND No user with the provided ID was found.
ALREADY_EXISTS Another user with the provided email address already exists.
PERMISSION_DENIED The calling user is neither a server admin nor the requested user themselves.
FAILED_PRECONDITION The user is not active (i.e., in state USER_STATUS_ACTIVE).
UNAUTHENTICATED The user is not signed in.

rpc SoftDeleteUser
Request: Id
Response: Nothing

Prevent the user with the provided ID from logging in. They are not fully deleted from the database but are no longer considered an active user.

Errors

Error Code Description
INVALID_ARGUMENT The user ID is not a valid UUID.
NOT_FOUND No user with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor the requested user themselves.
FAILED_PRECONDITION The user to be deleted is a server admin or the last project admin in any non-deleted project.
UNAUTHENTICATED The user is not signed in.

rpc SoftUndeleteUser
Request: Id
Response: Nothing

Allow a previously soft-deleted user to log in again. The calling user is required to be an admin.

Errors

Error Code Description
INVALID_ARGUMENT The user ID is not a valid UUID.
NOT_FOUND No user with the provided ID was found.
PERMISSION_DENIED The calling user is not a server admin.
FAILED_PRECONDITION The user to be restored is not deleted (i.e., not in state USER_STATUS_DELETED).
UNAUTHENTICATED The user is not signed in.

rpc GetUserSettings
Request: Nothing
Response: UserSettings

Get the user-specific settings for the calling user. The user settings are returned and guaranteed to be specified.

Errors

Error Code Description
NOT_FOUND No user settings were found for the calling user.
UNAUTHENTICATED The user is not signed in.

rpc UpdateUserSettings
Request: UserSettings.Update
Response: UserSettings

Update all attributes specified in the field mask for the user settings of the calling user. The updated user settings are returned and guaranteed to be specified.

Errors

Error Code Description
INVALID_ARGUMENT At least one updated setting did not meet the requirements.
FAILED_PRECONDITION The user is not active (i.e., in state USER_STATUS_ACTIVE).
UNAUTHENTICATED The user is not signed in.

rpc GetAllPapersToReview
Request: Nothing
Response: Project.Paper.List

Get all project papers that the calling user can review. It is not guaranteed that the returned papers belong to the same project. The returned paper list may be empty if no papers can be reviewed.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc GetPapersToReviewForProject
Request: Id
Response: Project.Paper.List

Get all project papers from the project identified by its ID that the calling user can review. The returned paper list may be empty if no papers can be reviewed.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc GetNextPaper
Request: Id
Response: Project.Paper

Get the project paper with the succeeding local ID (local_id) of the project paper identified by the provided global ID (id). It is guaranteed that the returned paper is in the same project as the provided one.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
FAILED_PRECONDITION There is no next project paper in the project.
UNAUTHENTICATED The user is not signed in.

rpc GetNextPaperToReview
Request: Id
Response: Project.Paper

Get the next project paper that the calling user can review. Papers with lower local IDs are preferred. It is guaranteed that the returned paper is in the same project as the provided one.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
FAILED_PRECONDITION There is no next project paper available to review in the project.
UNAUTHENTICATED The user is not signed in.

rpc GetPreviousPaper
Request: Id
Response: Project.Paper

Get the project paper with the previous local ID (local_id) of the project paper identified by the provided global ID (id). It is guaranteed that the returned paper is in the same project as the provided one.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
FAILED_PRECONDITION There is no previous project paper in the project.
UNAUTHENTICATED The user is not signed in.

rpc GetReadingList
Request: Nothing
Response: Paper.List

Get the list of papers on the reading list of the calling user.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc IsPaperOnReadingList
Request: Id
Response: BoolValue

Return whether the paper with the provided ID is on the calling user's reading list.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
UNAUTHENTICATED The user is not signed in.

rpc AddPaperToReadingList
Request: Id
Response: Nothing

Add the paper with the provided ID to the calling user's reading list. If the paper is already on the reading list, nothing will be changed and no error will be returned.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
UNAUTHENTICATED The user is not signed in.

rpc RemovePaperFromReadingList
Request: Id
Response: Nothing

Remove the paper with the provided ID from the calling user's reading list.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
UNAUTHENTICATED The user is not signed in.

rpc GetInviteCandidates
Request: Project.InviteCandidatesRequest
Response: User.List

Get a list of users that match the search query and can be invited. If the query is too short or no users match, an empty list is returned. If a project is specified, i.e., a project ID is given, all current members of that project are excluded from the candidate list. In case no project with the given ID exists, no project members are filtered out from the candidate list. The calling user is always excluded from the candidate list.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc InviteUserToProject
Request: Project.Member.Invite
Response: Nothing

Invite a user to a project. If the user is already a project member or invitee, nothing happens. The provided project must be active, meaning it is neither deleted nor archived. An invitation email is sent to the specified email address. The recipient may need to register first and then accept the invitation. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The email address is not a valid email address, or the project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project.
FAILED_PRECONDITION The project is not active (i.e., archived or deleted).
INTERNAL The invitation email could not be sent.
UNAUTHENTICATED The user is not signed in.

rpc AcceptProjectInvitation
Request: Project.Member.Accept
Response: Nothing

Accept a project invitation. After inviting a user to a project, the invited user receives an email containing the link to accept the invitation. This call is used to accept that invitation.

Errors

Error Code Description
INVALID_ARGUMENT No token was provided.
NOT_FOUND The provided token is invalid, could not be found, or has expired.
FAILED_PRECONDITION The user is not registered or not active (i.e., not in state USER_STATUS_ACTIVE).

rpc GetPendingInvitationsForProject
Request: Id
Response: User.List

Get a list of all users with a pending invitation to the specified project. If the id field of the returned user is specified, it is guaranteed that the user exists. If the field is blank, the user was invited by email and has not yet registered.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc GetProjectMembers
Request: Id
Response: Project.Member.List

Get a list of all members of the specified project. The calling user is included. Pending invitations are excluded.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc RemoveProjectMember
Request: Project.Member.Remove
Response: Nothing

Remove the specified user or invitee from the specified project. If the user is not part of the project, nothing happens. The calling user is required to be a project admin. If there is only one project admin, then the user cannot be removed from the project.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID or the user's email address is not a valid email address.
NOT_FOUND No project with the provided project ID or user with the provided user ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project, nor the project member themselves.
FAILED_PRECONDITION The project member to be removed is the last project admin in the project.
UNAUTHENTICATED The user is not signed in.

rpc UpdateProjectMemberRole
Request: Project.Member.Update
Response: Nothing

Change the role of the user with the provided ID within the specified project. The new role must be specified. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The project ID or the user ID is not a valid UUID, or the provided new role is not specified.
NOT_FOUND No project with the provided ID or user with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project.
FAILED_PRECONDITION The user to be updated is not a member of the specified project or is the last project admin and should be demoted to a project member.
UNAUTHENTICATED The user is not signed in.

rpc GetAllProjects
Request: Nothing
Response: Project.List

Get a list of all active projects.

Errors

Error Code Description
PERMISSION_DENIED The calling user is not a server admin.
UNAUTHENTICATED The user is not signed in.

rpc GetAllDeletedProjects
Request: Nothing
Response: Project.List

Get a list of all projects that are marked as deleted.

Errors

Error Code Description
PERMISSION_DENIED The calling user is not a server admin.
UNAUTHENTICATED The user is not signed in.

rpc GetAllDeletedProjectsForUser
Request: Id
Response: Project.List

Get a list of all projects the specified user is a member of and that are marked as deleted.

Errors

Error Code Description
INVALID_ARGUMENT The user ID is not a valid UUID.
NOT_FOUND No user with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor the calling user.
UNAUTHENTICATED The user is not signed in.

rpc GetAllArchivedProjects
Request: Nothing
Response: Project.List

Get a list of all projects that are marked as archived.

Errors

Error Code Description
PERMISSION_DENIED The calling user is not a server admin.
UNAUTHENTICATED The user is not signed in.

rpc GetAllProjectsForUser
Request: Id
Response: Project.List

Get a list of all active projects the specified user is a member of. Projects that the user is invited to are excluded.

Errors

Error Code Description
INVALID_ARGUMENT The user ID is not a valid UUID.
NOT_FOUND No user with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor the calling user.
UNAUTHENTICATED The user is not signed in.

rpc GetAllArchivedProjectsForUser
Request: Id
Response: Project.List

Get a list of all projects the specified user is a member of and that are marked as archived.

Errors

Error Code Description
INVALID_ARGUMENT The user ID is not a valid UUID.
NOT_FOUND No user with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor the calling user.
UNAUTHENTICATED The user is not signed in.

rpc CreateProject
Request: Project.Create
Response: Project

Create a new project. All fields must be specified and non-blank. The calling user is automatically a member of that project with the project admin role (MEMBER_ROLE_ADMIN). The project is created with the initial settings defined in the user settings of the calling user. If the project was successfully created, it is returned and guaranteed to be specified.

Errors

Error Code Description
INVALID_ARGUMENT The provided project name was blank.
NOT_FOUND No user settings were found for the calling user.
UNAUTHENTICATED The user is not signed in.

rpc GetProjectById
Request: Id
Response: Project

Get a project by its ID.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc UpdateProject
Request: Project.Update
Response: Project

Update all attributes specified in the field mask for the project with the provided ID, except the fields current_stage and max_stage. The updated project is returned and guaranteed to be specified. The calling user is required to be a project admin.

The following rules apply:

  • If status = PROJECT_STATUS_DELETED: No updates are allowed.
  • If status = PROJECT_STATUS_ARCHIVED: Only update of the status field is allowed.
  • If status = PROJECT_STATUS_ACTIVE: All non-immutable fields may be updated.
  • If status = PROJECT_STATUS_ACTIVE_LOCKED: All non-immutable fields, except the slr (project) settings, may be updated.
  • The value PROJECT_STATUS_DELETED is not allowed when updating a project, as the SoftDeleteProject call must be used instead.

Note: If the project is locked and the request sets status to PROJECT_STATUS_ACTIVE, no error is returned and the server keeps the state as PROJECT_STATUS_ACTIVE_LOCKED. Similarly, if the project is active and the request sets status to PROJECT_STATUS_ACTIVE_LOCKED, no error is returned and the server keeps the state as PROJECT_STATUS_ACTIVE.

Errors

Error Code Description
INVALID_ARGUMENT At least one (updated) project detail did not meet the requirements: The id must be a valid UUID, the name must not be left blank, the status must be specified and the project settings must be valid. The status needs to follow the rules outlined above.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project.
FAILED_PRECONDITION The project is not in the appropriate state for the requested change.
UNAUTHENTICATED The user is not signed in.

rpc GetAvailableExportFormats
Request: Nothing
Response: AvailableExportFormatsResponse

Get all available export formats that the backend supports. Each export format is identified by a unique string and can be used to specify the format for the ExportProject call. The list is guaranteed to be non-empty but may change at any time.

rpc ExportProject
Request: ExportRequest
Response: ExportResponse

Export the specified project in the specified format. A blob and a file name is returned. This includes everything necessary for the project to be reimported and remain indistinguishable from the original.

The filename includes the file extension so that the client doesn't have to figure out the file format. This could be e.g. "demo_project-2025-11-10-00-25-31.json".

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID or the format is not a valid export format.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc SoftDeleteProject
Request: Id
Response: Nothing

Mark the specified project as deleted. It is not permanently removed from the database and can be restored later. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project.
UNAUTHENTICATED The user is not signed in.

rpc SoftUndeleteProject
Request: Id
Response: Nothing

Restore a previously deleted project to the active state. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project.
FAILED_PRECONDITION The project to be restored is not deleted (i.e., not in state PROJECT_STATUS_DELETED).
UNAUTHENTICATED The user is not signed in.

rpc GetProjectInformation
Request: Project.Information.Get
Response: Project.Information

Get information about the specified project. The response only includes attributes specified in the field mask or all attributes when the field mask is not specified or has an empty path list.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc GetDecisionStatisticsForStage
Request: Project.Information.DecisionStatistics.Get
Response: Project.Information.DecisionStatistics

Get the distribution of paper decisions within a project's stage, meaning it returns the number of papers for each possible PaperDecision in the specified stage.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found or the specified stage does not exist.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc GetCriterionById
Request: Id
Response: Criterion

Get a criterion by its ID.

Errors

Error Code Description
INVALID_ARGUMENT The criterion ID is not a valid UUID.
NOT_FOUND No criterion with the provided ID was found.
PERMISSION_DENIED If the criterion is a user-criterion, the calling user is not the original creator of the criterion. If the criterion is a project-criterion, the user is not a member of the project the criterion belongs to.
UNAUTHENTICATED The user is not signed in.

rpc GetAllCriteriaForProject
Request: Id
Response: Criterion.List

Get all criteria associated with a given project.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc CreateCriterion
Request: Criterion.Create
Response: Criterion

Create a new criterion. All fields must be specified and non-blank. If the criterion is successfully created, it is returned and guaranteed to be specified.

A user-criterion is created by leaving the project_id empty. For a project-criterion, this field must be set and refer to a valid project in the active state. When creating a project-criterion, the calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT At least one input did not meet the requirements: All fields (except project_id) must not be blank and if the project_id is given, it must be a valid UUID.
NOT_FOUND A project ID is given but does not refer to an existing project.
PERMISSION_DENIED A project ID is given but the calling user is neither a server admin nor a project admin of the project the criterion should belong to.
FAILED_PRECONDITION A project ID is given but does not refer to an active project (i.e., it is archived or deleted).
UNAUTHENTICATED The user is not signed in.

rpc UpdateCriterion
Request: Criterion.Update
Response: Criterion

Update all attributes specified in the field mask for the criterion with the given ID. The updated criterion is returned and guaranteed to be specified. If the updated criterion is a user-criterion, the calling user is required to be the creator of the criterion. If it is a project-criterion, the calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT At least one (updated) criterion detail did not meet the requirements: All fields (except project_id) must not be blank and if the project_id is given, it must be a valid UUID.
NOT_FOUND No criterion with the provided ID was found or a project ID is given but does not refer to an existing project.
PERMISSION_DENIED If the criterion is a user-criterion, the calling user is not the original creator of the criterion. If the criterion is a project-criterion, the calling user is neither a server admin nor a project admin of the project the criterion belongs to.
FAILED_PRECONDITION A project ID is given but does not refer to an active project (i.e., it is archived or deleted).
UNAUTHENTICATED The user is not signed in.

rpc DeleteCriterion
Request: Id
Response: Nothing

Permanently delete the specified criterion. All references to it will also be removed. This cannot be undone. If the deleted criterion is a user-criterion, the calling user is required to be the creator of the criterion. If it is a project-criterion, the calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT If the criterion is a project-criterion, the project ID is not a valid UUID.
NOT_FOUND No criterion with the provided ID was found.
PERMISSION_DENIED If the criterion is a user-criterion, the calling user is not the original creator of the criterion. If the criterion is a project-criterion, the calling user is neither a server admin nor a project admin of the project the criterion belongs to.
UNAUTHENTICATED The user is not signed in.

rpc GetProjectPaperById
Request: Id
Response: Project.Paper

Get a project paper by its ID.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
UNAUTHENTICATED The user is not signed in.

rpc GetProjectPaperByRelativeId
Request: Project.Paper.Get
Response: Project.Paper

Get a project paper using the project ID and the relative ID (local_id) within that project. The relative ID is only unique within its project, not globally. Prefer GetProjectPaperById wherever possible.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID or the relative ID is not a non-negative Long number.
NOT_FOUND No project paper with the provided relative ID was found. Either the project does not exist or the relative ID was not found within the project.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
UNAUTHENTICATED The user is not signed in.

rpc GetAllProjectPapersForProject
Request: Id
Response: Project.Paper.List

Get all project papers associated with the given project.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project.
UNAUTHENTICATED The user is not signed in.

rpc AddPaperToProject
Request: Project.Paper.Add
Response: Project.Paper

Add the provided paper to the given project at the specified stage. The stage must be non-negative and less than or equal to the project's max_stage. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The project ID or paper ID is not a valid UUID, or the provided stage either is not a valid number or does not exist in the project, i.e., the stage was less than zero or greater than max_stage.
NOT_FOUND No project with the provided project ID or paper with the provided paper ID was found.
ALREADY_EXISTS The provided paper already exists within the project.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project.
FAILED_PRECONDITION The project is not active (i.e., archived or deleted).
UNAUTHENTICATED The user is not signed in.

rpc UpdateProjectPaper
Request: Project.Paper.Update
Response: Project.Paper

Update all attributes specified in the field mask for the project paper with the provided ID, except the fields local_id, decision, stage, and reviews. Furthermore, the underlying paper cannot be modified; use the UpdatePaper call for this. The updated project paper is returned and guaranteed to be specified. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID or paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID or paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project the project paper belongs to.
UNAUTHENTICATED The user is not signed in.

rpc RemovePaperFromProject
Request: Id
Response: Nothing

Permanently remove the specified project paper from the project. All references to this project paper will also be deleted. This cannot be undone. The calling user is required to be a project admin.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a project admin of the project the project paper belongs to.
UNAUTHENTICATED The user is not signed in.

rpc GetReviewById
Request: Id
Response: Review

Get a review by its ID.

Errors

Error Code Description
INVALID_ARGUMENT The review ID is not a valid UUID.
NOT_FOUND No review with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the review belongs to.
UNAUTHENTICATED The user is not signed in.

rpc GetAllReviewsForProjectPaper
Request: Id
Response: Review.List

Get all reviews for the specific project paper.

Errors

Error Code Description
INVALID_ARGUMENT The project paper ID is not a valid UUID.
NOT_FOUND No project paper with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
UNAUTHENTICATED The user is not signed in.

rpc CreateReview
Request: Review.Create
Response: Review

Create a new review for the specific project paper. All fields must be specified and non-blank. The field selected_criteria_ids may be empty. The calling user must not currently have another review for this project paper. The paper must also be currently UNREVIEWED or IN_REVIEW, i.e., not finally decided. The user also has to be a member of the same project the project paper belongs to. If the review is successfully created, it is returned and guaranteed to be specified.

Errors

Error Code Description
INVALID_ARGUMENT At least one input did not meet the requirements: The project paper ID must be a valid UUID, the decision must be specified, and if given, the selected criteria IDs must be a list of valid UUIDs.
NOT_FOUND No project paper with the provided ID was found.
ALREADY_EXISTS The user has already created a review for the specified project paper.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the project the project paper belongs to.
FAILED_PRECONDITION The project paper is not in the PAPER_DECISION_UNREVIEWED or PAPER_DECISION_IN_REVIEW state, or the project is not active (i.e., it is archived or deleted).
UNAUTHENTICATED The user is not signed in.

rpc UpdateReview
Request: Review.Update
Response: Review

Update all attributes specified in the field mask for the review with the given ID, except the user_id field. The updated review is returned and guaranteed to be specified. Only the owner of a review is allowed to update a review and must be a member of the project the review is in. A user is the owner of a review if the review's user_id matches the user's id.

Errors

Error Code Description
INVALID_ARGUMENT At least one (updated) review detail did not meet the requirements: The review ID must be a valid UUID, the decision must be specified, and if given, the selected criteria IDs must be a list of valid UUIDs.
NOT_FOUND No review with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin, the owner of the review, nor in the same project as the review.
FAILED_PRECONDITION The project paper is in a state in which no further modifications to the review are allowed, or the project is not active (i.e., it is archived or deleted).
UNAUTHENTICATED The user is not signed in.

rpc DeleteReview
Request: Id
Response: Nothing

Permanently remove the specified review from the project paper. This cannot be undone. Only the owner of a review is allowed to delete a review. The owner of the review must be a member of the project the review is in, in order to remove it. A user is the owner of a review if the review's user_id matches the user's id.

Errors

Error Code Description
INVALID_ARGUMENT The review ID is not a valid UUID.
NOT_FOUND No review with the provided ID was found.
PERMISSION_DENIED The calling user is neither a server admin, the owner of the review, nor in the same project as the review.
FAILED_PRECONDITION The project paper is in a state in which no deletions of reviews are allowed anymore, or the project is not active (i.e., it is archived or deleted).
UNAUTHENTICATED The user is not signed in.

rpc GetPaperById
Request: Id
Response: Paper

Get a paper by its ID.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
UNAUTHENTICATED The user is not signed in.

rpc SearchLocalPapers
Request: Paper.SearchQuery
Response: Paper.List

Search the local database for papers using a search string.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc SearchFetcherPapers
Request: Project.Paper.SearchQuery
Response: Paper.List

Search for papers that match the search query using all available fetchers of the specified project.

Errors

Error Code Description
INVALID_ARGUMENT The project ID is not a valid UUID.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The calling user is neither a server admin nor a member of the specified project.
UNAUTHENTICATED The user is not signed in.

rpc CreatePaper
Request: Paper
Response: Paper

Create a new paper. The id field will be ignored and set by the server. The created paper is returned and guaranteed to be specified.

Validation details:

  • only the title is required, in the sense that it must not be blank
  • text fields: external_id, title, abstrakt, publisher, publication_name and publication_type
  • valid year range: 0 to this year + 1, i.e., if this year is 2025, the maximum year value is 2026
  • valid author list: each author must be valid and the list must not exceed its maximum length
  • valid author: first_name and last_name must both be non-blank and must not exceed their maximum length.

Errors

Error Code Description
INVALID_ARGUMENT At least one of the text fields exceeds its maximum length, the title is blank, the year is invalid, or the author list is invalid. For more details, see above.
ALREADY_EXISTS The paper with the provided information already exists or is too similar to an existing paper.
UNAUTHENTICATED The user is not signed in.

rpc UpdatePaper
Request: Paper.Update
Response: Paper

Update all attributes specified in the field mask for the paper with the given ID, except the field has_pdf. The updated paper is returned and guaranteed to be specified.

For validation details, see CreatePaper.

Errors

Error Code Description
INVALID_ARGUMENT At least one of the text fields exceeds its maximum length, the title is blank, the paper ID is not a valid UUID, the year is invalid, or the author list is invalid. For more details, see CreatePaper.
NOT_FOUND No paper with the provided ID was found.
ALREADY_EXISTS The paper with the provided information already exists or is too similar to an existing paper.
UNAUTHENTICATED The user is not signed in.

rpc GetForwardReferencedPapers
Request: Id
Response: Paper.List

Get a list of papers that are referring to the provided paper, i.e., the papers that cite this paper.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
UNAUTHENTICATED The user is not signed in.

rpc GetBackwardReferencedPapers
Request: Id
Response: Paper.List

Get a list of papers that are referred to by the provided paper, i.e., the references of this paper.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
UNAUTHENTICATED The user is not signed in.

rpc GetPaperPdf
Request: Id
Response: Blob

Get a paper's PDF as a blob.

Errors

Error Code Description
INVALID_ARGUMENT The paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
FAILED_PRECONDITION The paper has no attached PDF (see Paper.has_pdf).
UNAUTHENTICATED The user is not signed in.

rpc SetPaperPdf
Request: Paper.PdfUpdate
Response: Nothing

Set or overwrite the PDF for the specified paper. This call may also be used to remove the PDF of a paper by omitting the pdf field. The paper's has_pdf field is automatically updated by the server.

Errors

Error Code Description
INVALID_ARGUMENT The PDF is not in the correct format, or the paper ID is not a valid UUID.
NOT_FOUND No paper with the provided ID was found.
RESOURCE_EXHAUSTED The PDF was rejected by the server, e.g., because it is too large.
UNAUTHENTICATED The user is not signed in.

Messages

message AuthenticationStatusResponse authentication.proto

Response on whether the user is authenticated.

Field Type Description
1 authentication_status AuthenticationStatus

message Author paper.proto

An author of a paper.

Field Type Description
1 first_name string
2 last_name string

message AvailableExportFormatsResponse export.proto

Response of available export formats.

Field Type Description
1 formats repeated string

message AvailableFetchers fetcher.proto

Response of available fetchers.

Field Type Description
1 fetcher_names repeated string

message Blob base.proto

Binary data.

Field Type Description
1 data bytes

message BoolValue base.proto

A boolean value.

Field Type Description
1 value bool

message Criterion criterion.proto

There are two types of criteria that must be differentiated: user- and project-criteria. A user-criterion has a user but no project attached to it and can be used for the creation of default criteria for a project in the user settings. A project-criterion on the other hand is associated with a project and provide the basis for justifying reviews.

Field Type Description
1 id string
2 tag string
3 name string
4 description string
5 category CriterionCategory

message Criterion.Create criterion.proto

Request to create a criterion.

Field Type Description
1 project_id string
2 tag string
3 name string
4 description string
5 category CriterionCategory

message Criterion.List criterion.proto

List of criteria.

Field Type Description
1 criteria repeated Criterion

message Criterion.Update criterion.proto

Request to update a criterion.

Field Type Description
1 criterion Criterion
2 mask google.protobuf.FieldMask

message Email base.proto

An email as defined by RFC 5322.

Field Type Description
1 email string

message ExportRequest export.proto

Request to export a project.

Field Type Description
1 id string
3 format string

message ExportResponse export.proto

Response of the exported project.

Field Type Description
1 data bytes
2 file_name string

message FetcherOptions fetcher.proto

Options that are used by a fetcher to control behavior.

Field Type Description
1 options map<string, string>

Map the option name to a (default) value

message GetAvailableFetcherOptionsRequest fetcher.proto

Request to get all available fetchers.

Field Type Description
1 fetcher_name string

message Id base.proto

An arbitrary ID. Use for RPCs related to single entities.

Field Type Description
1 id string

message LoginRequest authentication.proto

Request to log in.

Field Type Description
1 email string
2 password string

message Nothing base.proto

Just an empty object. Use when there's no parameter or return value.

Field Type Description

message Paper paper.proto

A scientific paper with it's references and other metadata.

Field Type Description
1 id string
2 external_id string
3 title string
4 abstrakt string
5 year int32
6 publisher string
7 publication_name string
8 publication_type string
9 has_pdf bool
10 authors repeated Author
11 backward_referenced_ids repeated string
12 fetcher_metadata map<string, string>

A key-value map to store arbitrary metadata about the paper. This could for example be a fetcher specific id.

message Paper.List paper.proto

A list of papers.

Field Type Description
1 papers repeated Paper

message Paper.PdfUpdate paper.proto

Request to update the PDF of a paper.

Field Type Description
1 paper_id string
2 pdf Blob

message Paper.SearchQuery paper.proto

Request to search for papers according to a query.

Field Type Description
2 query string

There are no restrictions on this search query in terms of valid values. The backend is fully responsible for deciding which paper attributes this query is matched against and is supposed to provide the best results for the given query.

message Paper.Update paper.proto

Request to update a paper.

Field Type Description
1 paper Paper
2 mask google.protobuf.FieldMask

message PasswordChangeRequest authentication.proto

Request to reset the password of the user while being logged in.

Field Type Description
1 old_password string
2 new_password string

message PasswordResetRequest authentication.proto

Request to actually reset the user's password.

Field Type Description
1 token string
2 new_password string

message Project project.proto

The project response object.

Field Type Description
1 id string
2 name string
3 status ProjectStatus
4 current_stage uint64
5 max_stage uint64
6 settings Project.Settings

message Project.Create project.proto

Request to create a project.

Field Type Description
1 name string

message Project.Information project.proto

Response of relevant project metadata.

Field Type Description
1 project_progress float

In a range from 0.0 to 1.0
2 creation_date google.protobuf.Timestamp
3 last_stage_started google.protobuf.Timestamp

The start time of the last (not necessarily completed) stage

message Project.Information.DecisionStatistics project.proto

Response of decision statistics containing the number of decisions made in the project.

Field Type Description
1 statistics repeated Project.Information.DecisionStatistics.Statistic

message Project.Information.DecisionStatistics.Get project.proto

Request to get the decision statistics for a specific stage of a project.

Field Type Description
1 project_id string
2 stage uint64

message Project.Information.DecisionStatistics.Statistic project.proto

The number of decisions made for a specific decision, e.g. accepted.

Field Type Description
1 decision PaperDecision
2 count uint64

message Project.Information.Get project.proto

Request to get relevant project metadata.

Field Type Description
1 project_id string
2 mask google.protobuf.FieldMask

message Project.InviteCandidatesRequest project.proto

Response of candidates to invite to a project.

Field Type Description
1 query string

The search query to match users by name or email. The query must be at least 3 characters long.
2 project_id string

The id of the project to which potential candidates should be invited. This field is optional and should be left unspecified if candidates are requested for a project that has not yet been created.

message Project.List project.proto

A list of projects.

Field Type Description
1 projects repeated Project

message Project.Member project.proto

A project member.

Field Type Description
1 user User
2 role MemberRole

message Project.Member.Accept project.proto

Request to accept a project invitation.

Field Type Description
1 token string

message Project.Member.Invite project.proto

Request to invite somebody to join the project.

Field Type Description
1 project_id string
2 user_email string

message Project.Member.List project.proto

A list of project members.

Field Type Description
1 members repeated Project.Member

message Project.Member.Remove project.proto

Request to remove an invitee or project member from a project.

Field Type Description
1 project_id string
3 user_email string

message Project.Member.Update project.proto

Request to update a project member.

Field Type Description
1 project_id string
2 user_id string
3 new_role MemberRole

message Project.Paper project.proto

The project paper connecting a project to a paper with additional information.

Field Type Description
1 id string
2 paper Paper
3 stage uint64
4 decision PaperDecision
5 reviews repeated Review
6 local_id string

message Project.Paper.Add project.proto

Request to add a paper to a project.

Field Type Description
1 project_id string
2 stage uint64
3 paper_id string

message Project.Paper.Get project.proto

Request to get a project paper.

Field Type Description
1 project_id string
2 relative_project_paper_id string

message Project.Paper.List project.proto

A list of project papers.

Field Type Description
1 project_papers repeated Project.Paper

message Project.Paper.SearchQuery project.proto

Request to search for project papers according to a query.

Field Type Description
1 project_id string
2 query string

There are no restrictions on this search query in terms of valid values. The backend is fully responsible for deciding which paper attributes this query is matched against and is supposed to provide the best results for the given query.

message Project.Paper.Update project.proto

Request to update a project paper.

Field Type Description
1 project_paper Project.Paper
2 mask google.protobuf.FieldMask

message Project.Settings project.proto

Project related settings.

Field Type Description
5 similarity_threshold float
6 decision_matrix ReviewDecisionMatrix
7 fetchers map<string, FetcherOptions>

Map fetcher name to its fetcher options, i.e. the map of option names to saved option values
8 snowballing_type SnowballingType
9 review_maybe_allowed bool

message Project.Update project.proto

Request to update a project.

Field Type Description
1 project Project
2 mask google.protobuf.FieldMask

message RegisterRequest authentication.proto

Request to register an account.

Field Type Description
1 first_name string
2 last_name string
3 email string
4 password string

message RequestPasswordResetRequest authentication.proto

Request to request the reset of the user's password.

Field Type Description
1 email string

message Review review.proto

A review of a paper made by a user (project member).

Field Type Description
1 id string
2 user_id string
3 decision ReviewDecision
4 selected_criteria_ids repeated string

message Review.Create review.proto

Request to create a review.

Field Type Description
1 project_paper_id string
2 decision ReviewDecision
3 selected_criteria_ids repeated string

message Review.List review.proto

List of reviews.

Field Type Description
1 reviews repeated Review

message Review.Update review.proto

Request to update a review.

Field Type Description
1 review Review
2 mask google.protobuf.FieldMask

message ReviewDecisionMatrix project.proto

Matrix containing the paper decision based on reviews made for a paper. This matrix defines how a paper is decided based on its reviews. For this to work, the entries need to be unique and the patterns exhaustive.

Field Type Description
1 number_of_reviewers uint32
2 patterns repeated ReviewDecisionMatrix.Pattern

message ReviewDecisionMatrix.Pattern project.proto

The actual matrix of the ReviewDecisionMatrix.

Field Type Description
1 entries repeated ReviewDecisionMatrix.Pattern.Entry
2 decision PaperDecision

message ReviewDecisionMatrix.Pattern.Entry project.proto

An entry in the ReviewDecisionMatrix containing the decision and the number of occurrences.

Field Type Description
1 review_decision ReviewDecision
2 count uint64

message User user.proto

A SnowballR user.

Field Type Description
1 id string
2 email string
3 first_name string
4 last_name string
5 role UserRole
6 status UserStatus

message User.List user.proto

A list of users.

Field Type Description
1 users repeated User

message User.Update user.proto

Request to update a user.

Field Type Description
1 user User
2 mask google.protobuf.FieldMask

message UserSettings user_settings.proto

Settings related to a user.

Field Type Description
1 show_hotkeys bool
2 review_mode bool
3 default_project_settings Project.Settings
4 default_criteria Criterion.List

message UserSettings.Update user_settings.proto

Request to update the user settings.

Field Type Description
1 user_settings UserSettings
2 mask google.protobuf.FieldMask

message VerifyEmailRequest authentication.proto

Request to verify a user's email after registering.

Field Type Description
1 token string

Enums

enum AuthenticationStatus authentication.proto

The status of the user's authentication. It is required to be authenticated to use the SnowballR app.

Name Number Description
AUTHENTICATION_STATUS_UNSPECIFIED 0

Unspecified authentication status.
AUTHENTICATION_STATUS_UNAUTHENTICATED 1

The user is unauthenticated. They have to sign into the app.
AUTHENTICATION_STATUS_ACCESS_TOKEN_EXPIRED 2

The user's access token is expired. They have to use the refresh token to get a new access token.
AUTHENTICATION_STATUS_AUTHENTICATED 3

The user is authenticated. They are signed in.

enum CriterionCategory criterion.proto

Category of a criterion, it can only be ever one of it.

Name Number Description
CRITERION_CATEGORY_UNSPECIFIED 0

Unspecified criterion category.
CRITERION_CATEGORY_INCLUSION 1

If this criterion is fulfilled, the paper should be accepted.
CRITERION_CATEGORY_EXCLUSION 2

If this criterion is fulfilled, the paper should be declined.
CRITERION_CATEGORY_HARD_EXCLUSION 3

If this criterion is fulfilled, the paper is definitely declined.

enum MemberRole project.proto

Role of a user inside a project.

Name Number Description
MEMBER_ROLE_UNSPECIFIED 0

Unspecified member role.
MEMBER_ROLE_DEFAULT 1

Default project member role. No elevated rights.
MEMBER_ROLE_ADMIN 2

Admin project member role. Can do everything that a default project member can do and more.

enum PaperDecision project.proto

The decision on how the paper is treated in respect to the SLR.

Name Number Description
PAPER_DECISION_UNSPECIFIED 0

Unspecified paper decision.
PAPER_DECISION_UNREVIEWED 1

The paper has not been reviewed yet.
PAPER_DECISION_IN_REVIEW 2

The paper is currently in review.
PAPER_DECISION_DECLINED 3

The paper was declined and is not considered part of the final SLR paper set.
PAPER_DECISION_ACCEPTED 4

The paper was accepted and is considered part of the final SLR paper set.

enum ProjectStatus project.proto

Status of the project. Can be considered the stage in the lifecycle of a project.

Name Number Description
PROJECT_STATUS_UNSPECIFIED 0

Unspecified project status.
PROJECT_STATUS_ACTIVE 1

Project is active and fully editable, including settings.
PROJECT_STATUS_ARCHIVED 2

Project is read-only and no longer actively used. This project is marked as archived.
PROJECT_STATUS_DELETED 3

Project is marked for deletion and should not be shown to users. This project is marked as deleted.
PROJECT_STATUS_ACTIVE_LOCKED 4

Project is active, but slr settings can no longer be changed. This state is reached as soon as the first review is submitted.

enum ReviewDecision review.proto

The decision based on the review of a paper.

Name Number Description
REVIEW_DECISION_UNSPECIFIED 0

Unspecified review decision.
REVIEW_DECISION_DECLINED 1

The reviewer declined the paper.
REVIEW_DECISION_MAYBE 2

The reviewer was not sure in their decision.
REVIEW_DECISION_ACCEPTED 3

The reviewer accepted the paper.

enum SnowballingType project.proto

The type of snowballing, according to Wohlin (2014). It defines which references (forward or backward) are fetched when a paper is accepted. A backward reference is defined as a paper that is cited by the paper in question. A forward reference is defined as a paper that cites the paper in question, i.e., a paper where the paper in question is a backward reference. Roughly speaking, one could say that "backward" and "forward" are an analogy to the order of the publication dates of two papers, i.e., a backward reference was most probably published before the paper in question and a forward reference afterward.

Name Number Description
SNOWBALLING_TYPE_UNSPECIFIED 0

Unspecified snowballing type.
SNOWBALLING_TYPE_FORWARD 1

All forward references are fetched.
SNOWBALLING_TYPE_BACKWARD 2

All backward references are fetched.
SNOWBALLING_TYPE_BOTH 3

All forward and backward references are fetched.

enum UserRole user.proto

Role of a user inside the SnowballR app.

Name Number Description
USER_ROLE_UNSPECIFIED 0

Unspecified user role.
USER_ROLE_DEFAULT 1

Default user role. No elevated rights.
USER_ROLE_ADMIN 2

(SnowballR instance) Admin user role. Can do everything that a default user can do and more.

enum UserStatus user.proto

Status of the user. Can be considered the stage in the lifecycle of a user.

Name Number Description
USER_STATUS_UNSPECIFIED 0

Unspecified user status.
USER_STATUS_ACTIVE 1

User is registered and has confirmed their email address.
USER_STATUS_DELETED 2

User has requested the deletion of their account.
USER_STATUS_ACTIVE_UNCONFIRMED 3

User is registered, but has not yet confirmed their email address.