To upload review materials use the the ReviewService.addFiles command. This command is rather complex and allows different variants of adding materials to a review. The files may reside on your local computer or be stored in a source code management system. Moreover, the command can add files to an existing review or to create a new review.
You will describe the following use-cases:
Depending on the particular use-case, the syntax of the addFiles command and the number of its arguments will vary. For example, to add materials to an existing review you need to specify the "reviewID" argument. If this argument is omitted, the addFiles command will create a new review with the attached files.
On success the addFiles command returns an ID of the review where the files were added.
Add files to a review
To add files that are stored on a local computer you need to archive them beforehand. The archived files must follow special conventions described below.
Once the archive is created you can send it to a Collaborator server and attach files to a review. There are two ways to do this:
-
Use the /contentupload servlet to upload the archive and the subsequent JSON request to attach files.
-
Send a single multipart request containing both "json" commands and the archive.
Preparing files for upload
Prior to uploading files to the Collaborator server you need to prepare them as follows:
-
Copy the needed files to a temporary folder.
-
Rename each file to its MD5 checksum. In lower-case letters, without any extension.
Suppose that we want to upload a file named "listobject.h" having an MD5 checksum of 198575c00a884ae27968e2fcf7d0a26d. Then the file must be renamed to "198575c00a884ae27968e2fcf7d0a26d".
-
Pack the files into a Zip archive. The name of the resulting Zip archive is not important.
Uploading files via /contentupload servlet
Every Collaborator server has a servlet for uploading data to reviews. It resides at the following URL: yourServer.com/contentupload
The servlet accepts multipart HTTP requests that contain Zip archives with files. The file upload request must conform to RFC 1867: Form-based File Upload in HTML.
The servlet requires authentication parameters in the request before processing file uploads. Authentication can be provided with the following methods:
-
Header: Authorization header that conforms to the Basic Authentication Scheme from RFC 2617.
Authorization: Basic bXl1c2VyOm15cGFzcw==
-
Header cookies: CodeCollaboratorLogin and CodeCollaboratorTicketId. (To obtain a valid
CodeCollaboratorTicketIdyou need to login via web-interface.)Cookie: CodeCollaboratorLogin=jsmith; CodeCollaboratorTicketId=0123456789abcdef0123456789;
If the upload is successful, the servlet will respond with a 200 (OK) status.
Below is an example of multipart HTTP request to the /contentupload servlet:
POST http://yourServer.com/contentupload HTTP/1.1
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
User-Agent: JSON API
Host: yourServer.com/
Cookie: CodeCollaboratorLogin=jsmith; CodeCollaboratorTicketId=0123456789abcdef0123456789;
Content-Length: 1394
---------------------------acebdf13572468
Content-Disposition: form-data; name="file"; filename="localFiles.zip"
Content-Type: application/x-zip-compressed
<Binary data of the localFiles.zip file>
---------------------------acebdf13572468--
Once the archive is uploaded successfully, the server unpacks it. Later on the you need to send a command to add an already uploaded files to reviews. To add files that were uploaded beforehand, use the following syntax of the addFiles command:
{"command" : "ReviewService.addFiles",
"args" : {
"reviewId": "<Id>", OPTIONAL
"changelists" : [{ REQUIRED
"commitInfo" : {<commitInfo>}, OPTIONAL
"versions" : [ { REQUIRED
"md5" : "<md5Checksum>", REQUIRED
"localPath" : "<LocalPathToFile>", OPTIONAL
"scmPath" : "<PathToFileInSCM>", OPTIONAL
"action" : "<ActionType>", OPTIONAL
"source" : "<SourceType>", OPTIONAL
"baseVersion" : OPTIONAL
}, {<version2>},..., {<versionN>}]
}, {<changelist2>},..., {<changelistN>}]
}
When adding already uploaded files, we should specify their MD5 checksums (md5) and either their local paths (localPath) or their paths in SCM (scmPath). All other arguments are optional. Notice that archive name is not specified, as the archive has already been unpacked.
The example below, attaches an uploaded file to the specified review:
[
{"command" : "SessionService.authenticate",
"args" : {"login" : "jsmith","ticket" : "0123456789abcdef0123456789abcdef"}},
{"command" : "ReviewService.addFiles",
"args" : {
"reviewId" : "10463",
"changelists" : [{
"versions" : [ { "md5" : "198575c00a884ae27968e2fcf7d0a26d",
"localPath" : "c:\\work\\collab\\files\\listobject.h",
"source" : "LOCAL" } ]
}]
}
}]
Uploading files with a multipart request
In this approach both the JSON commands and one or more archives to be attached are sent in the same multipart request.
The JSON request must be sent in a string part named "json" or as part of the query string as "json" parameter. The attached files must be sent in parts whose names coincides with the archive names. See RFC 1341: The Multipart Content-Type for detailed description of multipart requests.
To add files that are sent within the same HTTP request, use the following syntax of the addFiles command:
{"command" : "ReviewService.addFiles",
"args" : {
"reviewId": "<Id>", OPTIONAL
"zipName" : "<zipNameForCommand>", OPTIONAL
"changelists" : [{ REQUIRED
"commitInfo" : {<commitInfo>}, OPTIONAL
"versions" : [ { REQUIRED
"md5" : "<md5Checksum>", REQUIRED
"zipName" : "<zipNameForChangelist>", OPTIONAL
"localPath" : "<LocalPathToFile>", OPTIONAL
"scmPath" : "<PathToFileInSCM>", OPTIONAL
"action" : "<ActionType>", OPTIONAL
"source" : "<SourceType>", OPTIONAL
"baseVersion" : OPTIONAL
}, {<version2>},..., {<versionN>}]
}, {<changelist2>},..., {<changelistN>}]
}
When adding files with a multipart request, we should specify the names of archive (zipName), MD5 checksums of individual files (md5) and either their local paths (localPath) or their paths in SCM (scmPath). The archive name (zipName) can be given at the command level or per changelist. The zipName arguments are interchangeable, however at least one of them must be specified. All other arguments are optional.
As mentioned above, the attached files must be sent in parts whose names match the values of zipName arguments of the AddFiles command:
--boundary separator
Content-Disposition: form-data; name="<zipName>"; filename="<zipName>"
Content-Type: application/x-zip-compressed
<Binary data of the archive file>
The overall example of a multipart request may look like this:
POST http://yourServer.com/services/json/v1 HTTP/1.1
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
User-Agent: JSON API
Host: yourServer.com
Content-Length: 2041
---------------------------acebdf13572468
Content-Disposition: form-data; name="json"
Content-Type: application/json;charset=utf-8
[
{"command" : "SessionService.authenticate",
"args" : {"login" : "jsmith","ticket" : "0123456789abcdef0123456789abcdef"}},
{"command" : "ReviewService.addFiles",
"args" : {
"reviewId" : "10463",
"changelists" : [{
"zipName" : "localFiles.zip",
"versions" : [ { "md5" : "198575c00a884ae27968e2fcf7d0a26d",
"localPath" : "c:\\work\\collab\\files\\listobject.h",
"source" : "LOCAL" } ]
}]
}
}]
---------------------------acebdf13572468
Content-Disposition: form-data; name="localFiles.zip"; filename="localFiles.zip"
Content-Type: application/x-zip-compressed
<Binary data of the localFiles.zip file>
---------------------------acebdf13572468--
Add files from source-control system
To add files from source-control system, use the following syntax of the addFiles command:
{"command" : "ReviewService.addFiles",
"args" : {
"reviewId": "<Id>", OPTIONAL
"changelists" : [{ REQUIRED
"commitInfo" : {<commitInfo>}, OPTIONAL
"changelistLog" : ["<changelistID1>", ..., "<changelistIDN>"], OPTIONAL
"scmConnectionParameters" : ["<ConnectionParam1>", ..., "<ConnectionParamN>"], OPTIONAL
"scmToken" : "<scmToken>", OPTIONAL
"versions" : [ { REQUIRED
"md5" : "<md5Checksum>", REQUIRED
"scmVersionName" : "<FileVersionNameInSCM>", OPTIONAL
"scmPath" : "<PathToFileInSCM>", OPTIONAL
"action" : "<ActionType>", OPTIONAL
"source" : "<SourceType>", OPTIONAL
"baseVersion" : OPTIONAL
}, {<version2>},..., {<versionN>}]
}, {<changelist2>},..., {<changelistN>}]
}
When adding files from source-control system, we should specify their MD5 checksums (md5) and their paths in SCM (scmPath), and connection parameters to SCM (scmConnectionParameters). All other arguments are optional.
The example below attaches files from Git commit with ID 85994af65fb900f6e55606cb5ca498cc54463dbc to review 12:
[
{
"command": "SessionService.authenticate",
"args": {
"login": "jsmith",
"ticket": "0123456789abcdef0123456789abcdef"
}
},
{
"command": "ReviewService.addFiles",
"args": {
"changelists": [
{
"versions": [
{
"baseVersion": {
"source": "CHECKEDIN",
"scmVersionName": "40bf3c9346272c4e9eb77e8e379732c922c4f93a",
"md5": "f5212826f77081a8f7cfb9c0fed8967b",
"scmPath": "foobar/src/main/resources/js/view.js",
"action": "MODIFIED",
"commitInfo": {
"comment": "Merge pull request #5",
"date": "2020-04-09T18: 57: 51+03: 00",
"author": "GitHub",
"local": false,
"hostGuid": "266a5c8637da6b0c568803161fcb54a3",
"scmId": "28a221d213b28ad1e38e4805b45b13f995bc5d94"
}
},
"source": "CHECKEDIN",
"scmVersionName": "18d9ace010a575468b33b231040d4776196606d8",
"md5": "cb75d9547200ccc50c4d4142c356d9b3",
"scmPath": "foobar/src/main/resources/js/view.js",
"action": "MODIFIED"
}
],
"changelistLog": [
"85994af65fb900f6e55606cb5ca498cc54463dbc",
"28a221d213b28ad1e38e4805b45b13f995bc5d94"
],
"scmConnectionParameters": [
"https://github.com/acme/foobar.git"
],
"scmToken": "GIT",
"commitInfo": {
"comment": "Merge pull request #6",
"date": "2020-05-05T12:22:34+03:00",
"author": "GitHub",
"local": false,
"hostGuid": "266a5c8637da6b0c568803161fcb54a3",
"scmId": "85994af65fb900f6e55606cb5ca498cc54463dbc"
}
}
],
"reviewId": 12
}
}
]
See Also
How To
Manage Users and User Groups
Manage Reviews and Review Participants