← Back to packages

Package snowballr

Service SnowballR

Message AuthenticationStatusResponse

Message Author

Message AvailableFetchers

Message Blob

Message BoolValue

Message Criterion

Message Criterion.Create

Message Criterion.List

Message Criterion.Update

Message Email

Message ExportRequest

Message FetcherOptions

Message GetAvailableFetcherOptionsRequest

Message Id

Message LoginRequest

Message Nothing

Message Paper

Message Paper.List

Message Paper.PdfUpdate

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.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.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

Enum AuthenticationStatus

Enum CriterionCategory

Enum ExportFormat

Enum MemberRole

Enum PaperDecision

Enum ProjectStatus

Enum ReviewDecision

Enum SnowballingType

Enum UserRole

Enum UserStatus

Services

service SnowballR main.proto

The set of API calls the SnowballR web application uses to communicate with the backend. SnowballR is a tool aiming to assist in scientific research by organizing and managing structured literature reviews. The application is split into a web frontend and a backend on a central server keeping track of all data. This service represents all available interactions between this frontend and backend.

The 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 a http-only cookie set by the server during registration or login. If failing to do so, an UNAUTHENTICATED error will be returned.

Furthermore, the server may respond at any time with the UNAVAILABLE error code if it is unable to process a request.

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

Every enum contains a _UNSPECIFIED variant indicating its absence. 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, a result may never be really guaranteed and proper error handling is advised. In the following, guaranteed shall denote a situation in which the client shall be able to safely make assumptions about a successfully received message.

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

The SnowballR application is split into a frontend and a backend. The frontend is a web page that runs in the browser of a client. The backend runs on a server and contains most if not all logic. It accesses a database to persist data and makes requests to external resources like paper databases.

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 : "reading-list"

This figure shows the relationships between entities/concepts of the SnowballR application. It is not the actual database schema SnowballR's backend is using and solely assists with understanding the broader picture.

Disclaimer:

Access control for these calls is not fully worked out yet. Due to this, the required role for any call may change at any time.

rpc GetAvailableFetchers
Request: Nothing
Response: AvailableFetchers

Query all available origins 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 shall be used by a project to collect papers. The list is guaranteed to be non-empty, but may change at any time.

Errors

No additional errors may occur.

rpc GetAvailableFetcherOptions
Request: GetAvailableFetcherOptionsRequest
Response: FetcherOptions

Query 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 provided fetcher is unknown.

rpc Register
Request: RegisterRequest
Response: Nothing

Create an account. The provided email must not be already registered and every field must not be blank. If successful, login tokens are provided which are automatically used by following 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
ALREADY_EXISTS The provided email is already registered.
INVALID_ARGUMENT At least one input did not meet the requirements. The email needs to be a valid email, the password needs to meet the previously stated criteria and the first and last name must not be blank.

rpc Login
Request: LoginRequest
Response: Nothing

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

Errors

Error Code Description
UNAUTHENTICATED The user does not exist or the password is incorrect.
INVALID_ARGUMENT The email is not an actual email or no password is provided.

rpc Logout
Request: Nothing
Response: Nothing

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

Errors

No additional errors may occur.

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 authenticating the owner of the token is issued. The new pair is guaranteed to contain valid credentials. The refresh token may change too. These credentials are handled automatically and do not need further attention.

Use this call if the access token is expired. This call 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 is registered as an active user, a challenge/token is emailed to that address. That token must 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 is not valid. This does not occur if a valid email is not yet registered.

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 account trying to be reset is not in a state in which the password can be changed.
DEADLINE_EXCEEDED The provided token is expired.

rpc ChangePassword
Request: PasswordChangeRequest
Response: Nothing

Use the old password in order to set a new 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 The provided old password is not correct or the new password does not meet the rules specified in Register.
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 user is not an admin.
UNAUTHENTICATED The user is not signed in.

rpc GetCurrentUser
Request: Nothing
Response: User

Get the currently authenticated user by looking up the provided access token. If properly authenticated, it 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 its id.

Errors

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

rpc GetUserByEmail
Request: Email
Response: User

Get the user with the specified email address.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided email was found.
INVALID_ARGUMENT The email was invalid.

rpc UpdateUser
Request: User.Update
Response: User

Update all in the field-mask specified attributes of the user with the provided id except for status. The role may be updated by a server admin using this call. The updated user is returned and guaranteed to be specified.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
INVALID_ARGUMENT The first name, last name, role or email was invalid.
PERMISSION_DENIED The user is not allowed to modify the user with the specified id.
ALREADY_EXISTS The updated email is already registered.

rpc SoftDeleteUser
Request: Id
Response: Nothing

Prevent the user with the provided id from logging in. It is not fully deleted from the database though, but not considered an active user anymore.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
PERMISSION_DENIED The user is not allowed to delete the user with the specified id.
FAILED_PRECONDITION The user to be deleted is an admin.

rpc SoftUndeleteUser
Request: Id
Response: Nothing

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
PERMISSION_DENIED The user is not allowed to restore the user with the specified id.

rpc GetUserSettings
Request: Nothing
Response: UserSettings

Get the user-specific settings for the calling user. It is guaranteed that the result is specified.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.

rpc UpdateUserSettings
Request: UserSettings.Update
Response: UserSettings

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
INVALID_ARGUMENT The updated settings are invalid.

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

Get all project papers the requesting user is able to review. It is not given 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 a specific project identified by the id, the requesting user is able to review. The returned paper list may be empty if no papers can be reviewed.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not a member of the specified project or is not allowed to review.

rpc GetNextPaper
Request: Id
Response: Project.Paper

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.
FAILED_PRECONDITION There was no next paper.
PERMISSION_DENIED The user is not a member of the specified project.

rpc GetNextPaperToReview
Request: Id
Response: Project.Paper

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.
FAILED_PRECONDITION There was no next paper available to review.
PERMISSION_DENIED The user is not a member of the specified project or is not allowed to review.

rpc GetPreviousPaper
Request: Id
Response: Project.Paper

Get the project paper with the preceding local id of the project paper identified by the provided global id. It is guaranteed that the returned paper is in the same project as the provided one.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.
FAILED_PRECONDITION There was no previous paper.
PERMISSION_DENIED The user is not a member of the specified project.

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
UNAUTHENTICATED The user is not signed in.
NOT_FOUND The specified paper does not exist.

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 user's reading list, nothing will be changed and no error will be returned.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.

rpc RemovePaperFromReadingList
Request: Id
Response: Nothing

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND The specified paper does not exist.

rpc GetPendingInvitationsForUser
Request: Id
Response: Project.List

Get a list of all projects to which the user with the provided id is invited.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
PERMISSION_DENIED The user is not allowed to view the invitations of the specified user.

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, then 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. The provided project has to be active, meaning it is neither deleted nor archived. If a user with the provided email already exists, an invitation is sent. The user is not instantly added to the project. The user may then join the project using the invitation displayed in the frontend. If, however, no user with the provided email exists, an invitation email is sent out. The recipient may register and then accept the invitation. The calling user is required to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
FAILED_PRECONDITION The project is not active, meaning it is either archived or deleted.
PERMISSION_DENIED The user is not allowed to invite users to the specified project.
INVALID_ARGUMENT The provided email is not a valid email address.

rpc GetPendingInvitationsForProject
Request: Id
Response: User.List

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not allowed to view the pending invitations of the specified project.

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 not included.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not allowed to view the members of the specified project.

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

Remove the specified user from the given project. If the user is not part of the project, nothing happens. The calling user is required to be a project admin. A project admin cannot be removed from the project.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided project id or user with the provided user id was found.
PERMISSION_DENIED The user is not allowed to remove the specified user from the project.
FAILED_PRECONDITION The user to be removed is the last project admin.

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

Change the role of the user with the provided id within the given project. The new role must not be unspecified. The calling user is required to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
INVALID_ARGUMENT The provided role is unspecified.
PERMISSION_DENIED The user is not allowed to change the role of the specified user in the project. This could for example be the case if trying to demote a project admin.
NOT_FOUND No project with the provided id or user with the provided id was found.
FAILED_PRECONDITION The user to be updated is not a member of the specified project.

rpc GetAllProjects
Request: Nothing
Response: Project.List

Get a list of all active projects.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
PERMISSION_DENIED The user is not allowed to view all global projects.

rpc GetAllDeletedProjects
Request: Nothing
Response: Project.List

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
PERMISSION_DENIED The user is not allowed to view all global deleted projects.

rpc GetAllDeletedProjectsForUser
Request: Id
Response: Project.List

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
PERMISSION_DENIED The user is not allowed to view the deleted projects of the specified user.

rpc GetAllArchivedProjects
Request: Nothing
Response: Project.List

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
PERMISSION_DENIED The user is not allowed to view all global archived projects.

rpc GetAllProjectsForUser
Request: Id
Response: Project.List

Get a list of all active projects the provided user is a member of. Pending invitations are not included.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
PERMISSION_DENIED The user is not allowed to view the projects of the specified user.

rpc GetAllArchivedProjectsForUser
Request: Id
Response: Project.List

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No user with the provided id was found.
PERMISSION_DENIED The user is not allowed to view the archived projects of the specified user.

rpc CreateProject
Request: Project.Create
Response: Project

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
INVALID_ARGUMENT The provided project name was blank.

rpc GetProjectById
Request: Id
Response: Project

Get a project by its id.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not a member of the specified project.

rpc UpdateProject
Request: Project.Update
Response: Project

Update the project with the given id using the provided data. Only fields specified in the field-mask will be updated. The following fields cannot be modified: current_stage, max_stage. The updated project is returned and guaranteed to be specified. The calling user is required to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
INVALID_ARGUMENT Invalid name, status or project settings specified.
PERMISSION_DENIED The user is not allowed to update the project.
FAILED_PRECONDITION The project is not active.

rpc ExportProject
Request: ExportRequest
Response: Blob

Export the provided project in the given format. A blob is returned. The export includes everything for it to be reimported and be indistinguishable from the original project.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
INVALID_ARGUMENT The specified format is invalid.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not a member of the specified project.

rpc SoftDeleteProject
Request: Id
Response: Nothing

Mark a project as deleted. It is not fully deleted from the database and may later be restored. The calling user is required to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not an admin of the specified project.

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
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not an admin of the specified project.

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

Retrieve information about the specified project. Only attributes specified in the field-mask are included in the response.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not a member of the specified project.

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
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found or the specified stage does not exist.
PERMISSION_DENIED The user is not a member of the specified project.

rpc GetCriterionById
Request: Id
Response: Criterion

Get a criterion by its id.

Errors

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

rpc GetAllCriteriaForProject
Request: Id
Response: Criterion.List

Get all criteria associated with a given project.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not a member of the specified project.

rpc CreateCriterion
Request: Criterion.Create
Response: Criterion

Create a new criterion. Every field must be specified and non-blank. If successful, the newly created criterion is returned.

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

A user-criterion is created by leaving the project_id empty. For project- criterion creation this field has to be set and refer to a valid project in the ACTIVE state. Creating project-criteria requires the calling user to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
INVALID_ARGUMENT At least one field in the provided criterion other than project_id was blank.
NOT_FOUND The project_id was not blank but does not refer to a valid project.
PERMISSION_DENIED A project-criterion is created and the user is not an admin of the specified project.
FAILED_PRECONDITION A project-criterion is created and the specified project is not in the ACTIVE state.

rpc UpdateCriterion
Request: Criterion.Update
Response: Criterion

Update the criterion with the given id using the provided data. Only fields specified in the field-mask will be updated. 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, then then the calling user is required to be a project admin .

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No criterion with the provided id was found.
INVALID_ARGUMENT At least one field in the provided update other than project_id was blank.
PERMISSION_DENIED If the criterion is a user-criterion, then the calling user is not the original creator of the criterion. If the criterion is a project-criterion, then the user is not an admin of the project the criterion belongs to.
FAILED_PRECONDITION If the criterion is a project-criterion, then the project this criterion belongs to is not in the ACTIVE state.

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 updated criterion is a user-criterion, the calling user is required to be the creator of the criterion. If it is a project-criterion, then then the calling user is required to be a project admin

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No criterion with the provided id was found.
PERMISSION_DENIED If the criterion is a user-criterion, then the calling user is not the original creator of the criterion. If the criterion is a project-criterion, then the user is not an admin of the project the criterion belongs to.
FAILED_PRECONDITION If the criterion is a project-criterion, then the project this criterion belongs to is not in the ACTIVE state.

rpc GetProjectPaperById
Request: Id
Response: Project.Paper

Get a project paper by its id.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project paper with the provided id was found.
PERMISSION_DENIED The user is not a member of the project the paper belongs to.

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

Get a project paper using the project id and the local id within that project. The local id is only unique within its project, not, however, globally. Prefer GetProjectPaperById wherever possible.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
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 user is not a member of the project the paper belongs to.

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

Retrieve all project papers associated with the given project.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project with the provided id was found.
PERMISSION_DENIED The user is not a member of the specified project.

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

Add the provided paper to the given project within the specified stage. The stage must be lesser or equal to the projects max_stage. The calling user is required to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND Either the project or the paper with the provided ids were not found.
INVALID_ARGUMENT The provided stage does not exist in the project. This could mean that stage was less than zero or greater than max_stage.
ALREADY_EXISTS The specified paper already exists within the provided project.
PERMISSION_DENIED The user is not part of the specified project or is not a project admin.

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

Update the project paper with the specified id using the provided data. Only fields specified in the field-mask will be updated, excluding local_id, decision, stage and reviews. Furthermore, the composited paper cannot be modified, resort to the UpdatePaper call for this. The updated project will be returned and guaranteed to be specified. The calling user is required to be a project admin.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project paper with the provided id was found.
PERMISSION_DENIED The user is not admin of the project the project paper belongs to.

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
UNAUTHENTICATED The user is not signed in.
PERMISSION_DENIED The user is not an admin of the project the project paper belongs to.

rpc GetReviewById
Request: Id
Response: Review

Get a review by its id.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No review with the provided id was found.
PERMISSION_DENIED The user is not a member of the project the review belongs to.

rpc GetAllReviewsForProjectPaper
Request: Id
Response: Review.List

Retrieve all reviews for a specific project paper.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project paper with the provided id was found.
PERMISSION_DENIED The user is not a member of the project the project paper belongs to.

rpc CreateReview
Request: Review.Create
Response: Review

Create a new review for a specific project paper. Every field must be specified and non-blank. 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. The user also has to be a member of the same project the project paper belongs to. If successful, the created review is returned.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No project paper with the provided id was found.
ALREADY_EXISTS The user already has a review for the specified project paper.
FAILED_PRECONDITION The project paper is not in the UNREVIEWED or IN_REVIEW state.
PERMISSION_DENIED The user is not a member of the project the project paper belongs to.
INVALID_ARGUMENT At least one field in the provided review (except for selected_criteria_ids) was blank. This could be an invalid decision or selected_criteria_ids.

rpc UpdateReview
Request: Review.Update
Response: Review

Update the review with the given id using the provided data. Only fields specified in the field-mask will be updated, excluding user_id. The updated review is returned and guaranteed to be specified. Only the owner of a review is allowed to update a review. The owner of the review has to be a member of the project the review is in, in order to update it. A user is the owner of a review if the review's user_id matches the user's id.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No review with the provided id was found.
INVALID_ARGUMENT At least one field in the provided update was blank. This could be an invalid decision or an empty or invalid selected_criteria_ids.
PERMISSION_DENIED The user is either not the owner of the review or not a member of the project the review belongs to.
FAILED_PRECONDITION The project paper is in a state where no further review modifications are allowed.

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 has to 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
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No review with the provided id was found.
PERMISSION_DENIED The user is either not the owner of the review or not a member of the project the review belongs to.
FAILED_PRECONDITION The project paper is in a state where reviews are not allowed to be deleted.

rpc GetPaperById
Request: Id
Response: Paper

Get a paper by its id.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.

rpc CreatePaper
Request: Paper
Response: Paper

Create a paper using the given data. The id will be ignored and set by the server. All fields may be blank. The created paper will be returned.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
INVALID_ARGUMENT At least one field in the provided paper was invalid.

rpc UpdatePaper
Request: Paper.Update
Response: Paper

Update the paper with the given id using the provided data. Only fields specified in the field-mask will be updated, excluding has_pdf. The updated paper is returned and guaranteed to be specified.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.
INVALID_ARGUMENT At least one field in the provided paper was invalid.
PERMISSION_DENIED The user is not allowed to update the specified paper.

rpc GetForwardReferencedPapers
Request: Id
Response: Paper.List

Get a list of papers that are referred to by the provided paper.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.

rpc GetBackwardReferencedPapers
Request: Id
Response: Paper.List

Get a list of papers that are referring to the provided paper.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.

rpc GetPaperPdf
Request: Id
Response: Blob

Get a paper's PDF as a blob.

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.
FAILED_PRECONDITION The paper has no PDF attached to it. See paper.has_pdf.

rpc SetPaperPdf
Request: Paper.PdfUpdate
Response: Nothing

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

Errors

Error Code Description
UNAUTHENTICATED The user is not signed in.
NOT_FOUND No paper with the provided id was found.
RESOURCE_EXHAUSTED The provided PDF was declined by the server. A possible reason could be, that it was too large.
INVALID_ARGUMENT The provided PDF does not seem to be in the correct format.

Messages

message AuthenticationStatusResponse authentication.proto

Field Type Description
1 authentication_status AuthenticationStatus

message Author paper.proto

Field Type Description
1 first_name string
2 last_name string
3 orcid string

message AvailableFetchers fetcher.proto

Field Type Description
1 fetcher_names repeated string

message Blob base.proto

Field Type Description
1 data bytes

message BoolValue base.proto

Field Type Description
1 value bool

message Criterion criterion.proto

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

message Criterion.Create criterion.proto

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

message Criterion.List criterion.proto

Field Type Description
1 criteria repeated Criterion

message Criterion.Update criterion.proto

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

message Email base.proto

Field Type Description
1 email string

message ExportRequest export.proto

Field Type Description
1 id string
2 format ExportFormat

message FetcherOptions fetcher.proto

Field Type Description
1 options map<string, string>

Map the option name to a (default) value

message GetAvailableFetcherOptionsRequest fetcher.proto

Field Type Description
1 fetcher_name string

message Id base.proto

Field Type Description
1 id string

message LoginRequest authentication.proto

Field Type Description
1 email string
2 password string

message Nothing base.proto

Field Type Description

message Paper paper.proto

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

message Paper.List paper.proto

Field Type Description
1 papers repeated Paper

message Paper.PdfUpdate paper.proto

Field Type Description
1 paper_id string
2 pdf Blob

message Paper.Update paper.proto

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

message PasswordChangeRequest authentication.proto

Field Type Description
1 old_password string
2 new_password string

message PasswordResetRequest authentication.proto

Field Type Description
1 token string
2 new_password string

message Project project.proto

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

Field Type Description
1 name string

message Project.Information project.proto

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

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

message Project.Information.DecisionStatistics.Get project.proto

Field Type Description
1 project_id string
2 stage uint64

message Project.Information.DecisionStatistics.Statistic project.proto

Field Type Description
1 decision PaperDecision
2 count uint64

message Project.Information.Get project.proto

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

message Project.InviteCandidatesRequest project.proto

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

Field Type Description
1 projects repeated Project

message Project.Member project.proto

Field Type Description
1 user User
2 role MemberRole

message Project.Member.Invite project.proto

Field Type Description
1 project_id string
2 user_email string

message Project.Member.List project.proto

Field Type Description
1 members repeated Project.Member

message Project.Member.Remove project.proto

Field Type Description
1 project_id string
2 user_id string

message Project.Member.Update project.proto

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

message Project.Paper project.proto

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

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

message Project.Paper.Get project.proto

Field Type Description
1 project_id string
2 relative_project_paper_id string

message Project.Paper.List project.proto

Field Type Description
1 project_papers repeated Project.Paper

message Project.Paper.Update project.proto

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

message Project.Settings project.proto

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

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

message RegisterRequest authentication.proto

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

message RequestPasswordResetRequest authentication.proto

Field Type Description
1 email string

message Review review.proto

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

message Review.Create review.proto

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

message Review.List review.proto

Field Type Description
1 reviews repeated Review

message Review.Update review.proto

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

message ReviewDecisionMatrix project.proto

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

message ReviewDecisionMatrix.Pattern project.proto

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

message ReviewDecisionMatrix.Pattern.Entry project.proto

Field Type Description
1 review_decision ReviewDecision
2 count uint64

message User user.proto

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

Field Type Description
1 users repeated User

message User.Update user.proto

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

message UserSettings user_settings.proto

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

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

Enums

enum AuthenticationStatus authentication.proto

Name Number Description
AUTHENTICATION_STATUS_UNSPECIFIED 0
AUTHENTICATION_STATUS_UNAUTHENTICATED 1
AUTHENTICATION_STATUS_ACCESS_TOKEN_EXPIRED 2
AUTHENTICATION_STATUS_AUTHENTICATED 3

enum CriterionCategory criterion.proto

Name Number Description
CRITERION_CATEGORY_UNSPECIFIED 0
CRITERION_CATEGORY_INCLUSION 1
CRITERION_CATEGORY_EXCLUSION 2
CRITERION_CATEGORY_HARD_EXCLUSION 3

enum ExportFormat export.proto

Name Number Description
EXPORT_FORMAT_UNSPECIFIED 0
EXPORT_FORMAT_CSV 1
EXPORT_FORMAT_ZIP 2

enum MemberRole project.proto

Name Number Description
MEMBER_ROLE_UNSPECIFIED 0
MEMBER_ROLE_DEFAULT 1
MEMBER_ROLE_ADMIN 2

enum PaperDecision project.proto

Name Number Description
PAPER_DECISION_UNSPECIFIED 0
PAPER_DECISION_UNREVIEWED 1
PAPER_DECISION_IN_REVIEW 2
PAPER_DECISION_DECLINED 3
PAPER_DECISION_ACCEPTED 4

enum ProjectStatus project.proto

Name Number Description
PROJECT_STATUS_UNSPECIFIED 0
PROJECT_STATUS_ACTIVE 1

Project is active and fully editable, including settings.
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.
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.

enum ReviewDecision review.proto

Name Number Description
REVIEW_DECISION_UNSPECIFIED 0
REVIEW_DECISION_DECLINED 1
REVIEW_DECISION_MAYBE 2
REVIEW_DECISION_ACCEPTED 3

enum SnowballingType project.proto

Name Number Description
SNOWBALLING_TYPE_UNSPECIFIED 0
SNOWBALLING_TYPE_FORWARD 1
SNOWBALLING_TYPE_BACKWARD 2
SNOWBALLING_TYPE_BOTH 3

enum UserRole user.proto

Name Number Description
USER_ROLE_UNSPECIFIED 0
USER_ROLE_DEFAULT 1
USER_ROLE_ADMIN 2

enum UserStatus user.proto

Name Number Description
USER_STATUS_UNSPECIFIED 0
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