To manage reviews and review participants use the ReviewService interface. It provides methods for creating and editing reviews, adding, updating, removing and poking participants, adding review materials, changing review phases, managing comments and conversations and so on.
List Reviews Assigned to Specified User
To get a list of reviews we will use the UserService.getActionItems command which returns a list of incoming and outgoing action items a user is included in.
Request:
[
{"command" : "SessionService.authenticate",
"args":{"login":"jsmith","ticket":"0123456789abcdef0123456789abcdef"}},
{"command" : "UserService.getActionItems"}
]
Response example:
[
{ "result" : { } },
{ "result" : { "actionItems" : [
{ "nextActionText" : "Waiting for comments", "text" : "(No action required) Waiting for comments: Review #10254: \"Fix for case 34534\"" },
{ "nextActionText" : "Finish creating", "text" : "Finish creating: Review #10435: \"Documentation review\"" },
{ "nextActionText" : "Waiting for Defect rework", "text" : "(No action required) Waiting for Defect rework: Review #10188: \"Message Templates\"" }
] } }
]
Create New Review
To create a review use the ReviewService.createReview command. It accepts a number of arguments that define the creator (creator), review title (title), deadline date and time (deadline), specify who can access the review (accessPolicy) and other parameters. All parameters are optional.
Deadline date and time should be specified in a "YYYY-MM-DDTHH:mm:ssZ" format described in JSON Syntax and Data Formats. The accessPolicy argument may have one of the following constants: ANYONE, GROUP, PARTICIPANTS, GROUP_AND_PARTICIPANTS, GROUP_OR_PARTICIPANTS.
The request below creates a new review:
[
{"command" : "SessionService.authenticate",
"args":{"login":"jsmith","ticket":"0123456789abcdef0123456789abcdef"}},
{"command" : "ReviewService.createReview",
"args" :{
"creator" : "jsmith",
"title" : "Check JDK version",
"deadline" : "2015-02-01T09:00:00Z",
"accessPolicy" : "PARTICIPANTS",
"customFields": [
{"name":"Overview", "value":["Please check the JDK version that we use."]},
{"name":"Incident ID", "value":["1321654"]}
]
}
}]
On success the command returns an identifier of a newly created review.
Response example:
[
{ "result" : { } },
{ "result" : { "reviewId" : 10463 } }
]
| Note: | A newly created review is not yet ready for working on it. To proceed, we need to assign review participants and add review materials. |
Add or Change Participants of Review
Web service API offers two commands for assigning participants of the review: ReviewService.setAssignments and ReviewService.updateAssignments. The setAssignments command clears the list of existing review participants (if any) and assigns participants and roles anew. The updateAssignments command adds new participants and changes the roles of existing participants.
Both commands have the same set of arguments:
reviewId - the ID of the review whose participants we want to add or modify.
assignments - an array that defines review participants and their roles.
Each element of the array must be either a {"user", "role"} object or a {"poolGuid", "role"} object. In the first case the object will denote an individual participant and his role, while in the second it will denote a group of users (review pool) that can partake in a review and the role for this group.
The "role" argument can be one of the following constants: AUTHOR, MODERATOR, OBSERVER, READER, REVIEWER, TESTER.
[
{"command" : "SessionService.authenticate",
"args":{"login":"jsmith","ticket":"0123456789abcdef0123456789abcdef"}},
{"command" : "ReviewService.updateAssignments",
"args":{
"assignments": [
"reviewId":"10463",
{"user":"jsmith", "role":"AUTHOR"},
{"user":"mike", "role":"REVIEWER"},
{"poolGuid":"1234567890", "role":"OBSERVER"}
]}
}
]
Assign a Review Pool
To assign a review pool group as the participant of the review use the ReviewService.assignReviewPool command. It has similar set of arguments as assigning individual participants:
reviewId - the ID of the review whose participants we want to add or modify.
assignments - an array that defines review participants and their roles.
Each element of the array must be a {"poolGuid", "role"} object denoting a group of users (review pool) that can partake in a review and the role for this group.
The "role" argument can be one of the following constants: AUTHOR, MODERATOR, OBSERVER, READER, REVIEWER, TESTER.
[
{"command" : "SessionService.authenticate",
"args":{"login":"jsmith","ticket":"0123456789abcdef0123456789abcdef"}},
{"command" : "ReviewService.assignReviewPool",
"args":{
"assignments": [
"reviewId":"10396",
{"poolGuid":"1234567890", "role":"REVIEWER"}
]}
}
]