Collaborator plugin for Microsoft Word

This plugin is an example of what is possible with Collaborator’s new API. It simplifies the process of uploading a Microsoft Word document to a Collaborator review. It adds a new ribbon bar, with a button to upload the current document.


Developer Notes

We’ve released the full source code to help you get started building your own integration in C#. The full source code is available on GitHub, here:

Fork us! Please feel free to fork this repository, and then send us a pull request with your enhancements. We’d love to see how you’ve extended this, and we’d love to share your work with other integrators.
The plugin was built in, and requires Visual Studio 2013 to compile out of the box, but you should be able to get it to compile on older versions without much effort. The same goes for the .NET framework: It’s built on .NET 4.5, but there’s no reason you couldn’t back port this to an older version, if that suits you better.

The solution contains three sub projects:

  • CollabAPI – The classes required to interact with a Collaborator server. This is really the part that we want to share with you. It provides an example and a base implementation for customers that want to build a custom integration. If that’s you, then this project is all that you need.
  • CollabAddin – This is the Microsoft Word plugin itself. It uses the CollabAPI classes to make the magic happen. Feel free to poke around under the hood.
  • APITest – This was being used to test the API wrapper as we were building it. It also calls into CollabAPI to interact with the Collaborator server. We’ve included it as an additional reference.

Making something useful

For the purposes of this demonstration, we will ignore the CollabAddin and APITest projects, and focus on what it really takes to make a call to the Collaborator server. Here’s a brief synopsis of what it takes to make a successful API call:

The CollabAPI project contains a Json subfolder that has everything that you need to interact with Collaborator’s API.

The Execute() method does most of the work: We’ll pass it our server’s URL, and a list of JsonCommand objects.

The method will interact with the server, and we’ll receive a list of JsonResult objects back. We can then iterate through the results, and check for errors.

If Execute() runs into a problem, it will simply throw an exception, so make sure that you trap errors in a try/catch block!


Before continuing, you should be familiar with the documentation surrounding the Collaborator API. Please find that documentation here:

In the interest of simplicity, we’ll show you how to authenticate with the server, and get your login ticket. You can then use that login ticket to make future API calls as an authenticated user.

Tip: Make sure that you have read the Authentication section in the documentation linked above.


Collaborator’s API methods are grouped into categories, which we’ll refer to as services. In order to authenticate with the server, we’ll need to call the getLoginTicket method in the SessionService category. To do this, we’ll build a List<JsonCommand> object, and send it to the Execute() method. We’ll get back a List<JsonResult> object that contains a single instance of the getLoginTicketResponse class.

JsonCommand objects are used to wrap an instance of a class that is defined in one of the service categories. You’ll find the *Service.cs files in the Json directory of the CollabAPI project. These are just a small sample of the methods available on the server. A complete list of methods can be found in the JavaDoc that ships with your server installation. More information on locating the JavaDoc is available here:

  • JsonResult objects are used to wrap API responses from the server. We’ll either get a *Response class instance back, or an error string.

  • The JsonCommand constructor takes an instance of the getLoginTicket class as a parameter. This class should have its data members populated with the information needed for the server to fulfill the request, make sure you set the login and password values correctly.

  • The JsonResult objects will either contain an error, or a response from the API call. Some API calls return a void response, and if no error is returned, then the API call succeeded on the server. Proper use of this class means checking the isError() method first. If it’s true, then you may call GetErrorString() to get the error details. If there’s no error, and you are retrieving data from the server, such as a login ticket, then you can use the GetResponse<T>() method to get an instance of the correct *Response class. Here, we’re looking for a getLoginTicketResponse.

Here’s the sample code:

List<JsonCommand> requestList = new List<JsonCommand>();

List<JsonResult> responseList;
requestList.Add(new JsonCommand(new SessionService.getLoginTicket(){
                login = "rick",
                password = "supersecretpasscode"
try {
responseList = CollabServerRequest.Execute("http://collab" , requestList);
JsonResult result = responseList.First();
if (result.isError())
       Console.Write("Error: " + result.GetErrorString());
else {
              Console.WriteLine("Your login ticket is: " +
catch (Exception ex) {
       Console.WriteLine("Error sending request " + ex.ToString());

Please find many more examples throughout this solution.

One last note: You’ll also find CollabAPI.cs. This is a higher level wrapper for the classes in the Json subdirectory. It knows how to authenticate, and it will store a login ticket for repeated use. This class is by no means all inclusive, but it provides an example of what a higher level API integration might look like. See the examples in the APITest project, which primarily uses this easier to consume wrapper.

If you have any questions, or would like to contribute to the community, then please post on the SmartBear Developer Network forums, here:

We look forward to hearing from you!


Do you do document review, and just want to use the plugin? We have provided an installation package for you: No coding necessary. It’s available on GitHub, here:
Download and extract the zip file on your computer, and then run setup.exe. Step through the simple prompts, and you’ll be up and running in no time. The plugin is compatible with Microsoft Word 2010 and newer.
Note: An Internet connection may be required, as the installer will automatically download any required extensions for Microsoft Office.


Using the plugin

Once you have installed the plugin, you should see a new SmartBear ribbon bar in Microsoft Word.


Click the Options button to configure your server connection. The settings will be validated when you click save, so make sure that your Collaborator server is online and available.


Now that we’ve got our server connection configured, it’s time to create a review! Open up your favorite Microsoft Word document, and then click the Upload to Review button. You will be presented with the review selection dialog, as shown here. Enter a title for your new review, and click the Upload button.


Success! If everything went well, then you’ll be prompted to open the review in your browser, so that you can add participants, and begin the review.


Need to upload a new revision of your document after some constructive feedback from your peers during the review? No problem! Open the document, make your changes, and save it with the same file name. Click the Upload to Review button again, but this time, select the Add to Existing Review radio button. Select the review that you uploaded to last time, and click Upload.

Hint:  Use the search box to search by review number or title.