Scripting is the easiest way to implement custom behaviors with Collaborator.
You can use the Command-Line Client to script actions on your user's machines, or install it on the same machine as the Collaborator Server and invoke it with a trigger.
The Command-Line Client can create, delete, and edit reviews, including templates and review custom fields. It can assign or remove participants within a review, and even move reviews to the next phase (for example, from "planning" to "inspection"). It can also create comments and defects, including defect custom fields, and mark defects as external.
You can use the Command-Line Client to create, edit, enable or disable user accounts. It can be used to set up user information like email addresses and phone numbers. It can also be used to set up author or file-based subscriptions.
Often when scripting you find that you need to run multiple Command-Line Client commands. It is OK to simply run them one after the other in your script, but it is more efficient to group them together using the
ccollab admin batch command. The
batch command takes as input an XML file which lists the commands to be run and optionally global options to use to run them.
It is faster to run multiple commands using the
batch command because the Command-Line Client only has to connect and authenticate with the Collaborator Server once. Also the XML input format is useful if the data you are passing to the Command-Line Client contains characters difficult to encode on the command-line like line feeds, quotes, or multi-byte characters.
ccollab admin review-xml command lets you extract data from one or more reviews in your script. You can supply an XSL file to format the output, or an XPATH expression to select only the specific data you need. You can even use XPATH functions to perform some computation.
You can also query the server for a list of reviews using the built-in reports, and then use the
ccollab admin wget command to download the CSV output format to be parsed by your script. Note the CSV output format of the reports does not consume a license. For example, to get a list of the reviews currently in progress run:
ccollab admin wget "/go?page=ReportReviewList&formSubmittedreportConfig=1&reviewIdVis=y&reviewTitleVis=y&data-format=csv&phaseFilter=inprogress"
You can disable all interactive prompting by specifying the
non-interactive global option.
You can also use the special value "ask" when specifying the
review parameter. Using "ask" will cause the Command-Line Client to interactively prompt the user with the list of reviews they are currently involved in.
If you are invoking more than one command, you can use the special value "last" in combination with "ask". Using "last" will cause the Command-Line Client to address the review most recently accessed by the Command-Line Client. Typically the first command in the script will use "ask" and then subsequent commands use "last" to access the same review.
Opening a Browser
Collaborator is fundamentally a web-based tool and the actual reviewing goes on in a browser. Many Command-Line Client commands automatically open a browser to allow the user to take the next step. You can prevent the Command-Line Client from opening a browser by specifying the
no-browser global option.
"Virtual" Script Users
Often when setting up scripting it is convenient to create a Collaborator user which the script will use to log in to the Collaborator server. Simply create a user in the normal way and give the credentials (login and password) to the script. The command-line scripting commands will not cause the "virtual" script user to consume a license (except
ccollab admin wget, if the URL it is loading consumes a license).
Downloading File Version Content
A special URL lets you download the binary contents of any file version efficiently. The URL is authenticated, so you have to use
ccollab admin wget. Note the version content URL does not consume a license.
For example, to get a file version with ID
ccollab admin wget "/data/server?versionid=12345"
The 'wget' command can also be used to:
Get all diffs in a review:
ccollab admin wget "/diff?context=<context>&reviewid=<review id>"
Get diffs from two specific versions:
ccollab admin wget "/diff?context=<context>&reviewid=<review id>&versionids=<version a>,<version b>