Scripting: Overview

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.

The 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:

You can disable all interactive prompting by specifying the non-interactive global option.

If non-interactive is not specified, the Command-Line Client will automatically prompt for server url, user, and password as necessary when it connects to the Collaborator Server.

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.

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.

You can also explicitly open a browser using the ccollab browse command. Note that the browsecommand ignores the no-browser global option.

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

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 12345:

The 'wget' command can also be used to:

Get all diffs in a review:

Get diffs from two specific versions: