Code Collaborator User Guide

1

Code Collaborator v5.0.5022 Owner's Manual

User's and Administrator's Guide

© 2003-2009 Smart Bear Inc.


2

Code Collaborator v5.0.5022 Owner's
Manual

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or
mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the
written permission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered trademarks of the
respective owners. The publisher and the author make no claim to these trademarks.

While every precaution has been taken in the preparation of this document, the publisher and the author assume no
responsibility for errors or omissions, or for damages resulting from the use of information contained in this
document or from the use of programs and source code that may accompany it. In no event shall the publisher and
the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused
directly or indirectly by this document.

Printed November 2009 in Austin, TX, USA.


Contents i

Table of Contents
Foreword 0

Part I Big Picture 1
1 Code Collaborator Overview
................................................................................................................................... 1
2 Moving Parts
................................................................................................................................... 1
3 Quick Start
................................................................................................................................... 3
For System Administrators
.......................................................................................................................................................... 3
For Developers
.......................................................................................................................................................... 4
4 Contact Us
................................................................................................................................... 6

Part II Server Administration 6
1 Installation
................................................................................................................................... 7
Database Installation
.......................................................................................................................................................... 7
Zero-Configuration
......................................................................................................................................................... 7
MySQL ......................................................................................................................................................... 7
SQL Server......................................................................................................................................................... 8
Oracle ......................................................................................................................................................... 9
Server Installation
.......................................................................................................................................................... 11
Server Upgrades
.......................................................................................................................................................... 17
Upgrading......................................................................................................................................................... 18
from v4.0 to v5.0
Upgrading......................................................................................................................................................... 19
from v2.1 to v4.0
Network Configuration
.......................................................................................................................................................... 20
Platform-Specific Notes
.......................................................................................................................................................... 21
2 System Administration
................................................................................................................................... 22
Licensing .......................................................................................................................................................... 22
Backup / Migration
.......................................................................................................................................................... 26
Security Considerations
.......................................................................................................................................................... 29
LDAP Authentication
.......................................................................................................................................................... 30
Configuring HTTPS
.......................................................................................................................................................... 35
JMX Monitoring
.......................................................................................................................................................... 39
Technical Specifications
.......................................................................................................................................................... 40
Troubleshooting
.......................................................................................................................................................... 43
3 Code ...................................................................................................................................
Collaborator Configuration 46
General Settings
.......................................................................................................................................................... 46
User Management
.......................................................................................................................................................... 56
Groups .......................................................................................................................................................... 60
Syncing Groups
......................................................................................................................................................... 64
Using Groups for Organizational Hierarchy
......................................................................................................................................................... 65
Using Groups for Projects
......................................................................................................................................................... 66
Using Groups for Organizational Hierarchy and Projects
......................................................................................................................................................... 67
E-Mail Configuration
.......................................................................................................................................................... 68
Version Control
.......................................................................................................................................................... 70
Custom Fields .......................................................................................................................................................... 73
Role Configuration
.......................................................................................................................................................... 76
Workflow Configuration
.......................................................................................................................................................... 81
Triggers .......................................................................................................................................................... 83
Notification Templates
.......................................................................................................................................................... 84


ii Code Collaborator v5.0.5022 Owner's Manual

Automatic Links
.......................................................................................................................................................... 86
Variable Substitution
.......................................................................................................................................................... 88
Archiving Data
.......................................................................................................................................................... 91
System Status.......................................................................................................................................................... 91

Part III Web User's Guide 93
1 Account Management
................................................................................................................................... 93
Log in / Log out.......................................................................................................................................................... 93
User Preferences.......................................................................................................................................................... 95
Notifications .......................................................................................................................................................... 100
2 Reviews
................................................................................................................................... 102
Review Overview
.......................................................................................................................................................... 102
Action Items.......................................................................................................................................................... 103
Creating a Review
.......................................................................................................................................................... 104
Review Summary Screen
.......................................................................................................................................................... 112
Reviewing Materials
.......................................................................................................................................................... 121
Reviewing Text Files
......................................................................................................................................................... 121
Reviewing Images
......................................................................................................................................................... 126
Reviewing Documents
......................................................................................................................................................... 128
Reviewing URLs
......................................................................................................................................................... 130
Review Chats .......................................................................................................................................................... 131
FAQ's .......................................................................................................................................................... 135
3 Searching & Reporting
................................................................................................................................... 136
Searching .......................................................................................................................................................... 136
Reporting .......................................................................................................................................................... 139

Part IV Clients 144
1 Installation
................................................................................................................................... 144
2 Configuration
................................................................................................................................... 149
Server Connection Configuration
.......................................................................................................................................................... 149
3 GUI Client
................................................................................................................................... 151
Main Screen.......................................................................................................................................................... 152
SCM Configuration
.......................................................................................................................................................... 153
Preferences.......................................................................................................................................................... 154
Troubleshooting
.......................................................................................................................................................... 157
4 Command Line Client
................................................................................................................................... 157
Configuration.......................................................................................................................................................... 158
Commands .......................................................................................................................................................... 159
Graphical Editor
.......................................................................................................................................................... 160
Uploading Diffs
.......................................................................................................................................................... 161
Troubleshooting
.......................................................................................................................................................... 164
Global Options Reference
.......................................................................................................................................................... 165
Command-line Reference
.......................................................................................................................................................... 170
help ......................................................................................................................................................... 172
info ......................................................................................................................................................... 173
login ......................................................................................................................................................... 173
set ......................................................................................................................................................... 174
addchanges......................................................................................................................................................... 174
addfiles ......................................................................................................................................................... 176
addchangelist
......................................................................................................................................................... 177
adddiffs ......................................................................................................................................................... 178


Contents iii

addsvndiffs......................................................................................................................................................... 178
addardiffs ......................................................................................................................................................... 179
addcvsdiffs......................................................................................................................................................... 180
addgitdiffs......................................................................................................................................................... 181
addhgdiffs ......................................................................................................................................................... 182
addp4diffs ......................................................................................................................................................... 183
addstdiffs ......................................................................................................................................................... 184
addvssdiffs......................................................................................................................................................... 185
addversions......................................................................................................................................................... 186
addactivity......................................................................................................................................................... 187
actionitems......................................................................................................................................................... 188
addtrack ......................................................................................................................................................... 188
addstream ......................................................................................................................................................... 189
browse ......................................................................................................................................................... 190
commit ......................................................................................................................................................... 190
addp4job ......................................................................................................................................................... 191
addurls ......................................................................................................................................................... 191
admin ......................................................................................................................................................... 192
syncusers ......................................................................................................................................... 192
review-xml ......................................................................................................................................... 193
batch ......................................................................................................................................... 194
config ......................................................................................................................................... 195
custom-field ................................................................................................................................... 196
edit ................................................................................................................................... 196
review ......................................................................................................................................... 196
create ................................................................................................................................... 197
edit ................................................................................................................................... 198
delete ................................................................................................................................... 199
finish ................................................................................................................................... 199
copy-participants ................................................................................................................................... 200
participant ................................................................................................................................... 200
assign ................................................................................................................................... 201
remove ................................................................................................................................... 201
comment ................................................................................................................................... 202
create ................................................................................................................................... 202
defect ................................................................................................................................... 202
create ................................................................................................................................... 203
mark-external ................................................................................................................................... 203
user ......................................................................................................................................... 204
create ................................................................................................................................... 204
edit ................................................................................................................................... 205
author-subscription ................................................................................................................................... 206
create ................................................................................................................................... 207
edit ................................................................................................................................... 207
delete ................................................................................................................................... 207
file-subscription ................................................................................................................................... 208
create ................................................................................................................................... 208
edit ................................................................................................................................... 209
delete ................................................................................................................................... 209
trigger ......................................................................................................................................... 210
ensure-review-started ................................................................................................................................... 210
ensure-reviewed ................................................................................................................................... 212
ensure-content-reviewed ................................................................................................................................... 214
update-changelist ................................................................................................................................... 216


iv Code Collaborator v5.0.5022 Owner's Manual

create-review ................................................................................................................................... 218
group ......................................................................................................................................... 219
create ................................................................................................................................... 219
edit ................................................................................................................................... 220
delete ................................................................................................................................... 221
sync ................................................................................................................................... 222
member ................................................................................................................................... 223
add ................................................................................................................................... 223
remove ................................................................................................................................... 224
changelist ......................................................................................................................................... 225
update-id ................................................................................................................................... 225
5 Tray ...................................................................................................................................
Notifier 226
6 External Diff Viewer launcher
................................................................................................................................... 227
7 Eclipse Plug-in
................................................................................................................................... 230
Install & Update
.......................................................................................................................................................... 231
Preferences .......................................................................................................................................................... 234
& Configuration
Action Items.......................................................................................................................................................... 235
Add to Review Wizard
.......................................................................................................................................................... 236
Adding Files .......................................................................................................................................................... 239
to a Review
AccuRev Integration
.......................................................................................................................................................... 240
ClearCase Integration
.......................................................................................................................................................... 240
CVS Integration
.......................................................................................................................................................... 241
Perforce Integration
.......................................................................................................................................................... 242
Subversion .......................................................................................................................................................... 245
Integration
Troubleshooting
.......................................................................................................................................................... 247

Part V Version Control Integration 248
1 AccuRev Integration
................................................................................................................................... 249
GUI Client .......................................................................................................................................................... 250
Comparing two Streams
......................................................................................................................................................... 253
Command Line Client
.......................................................................................................................................................... 253
addchanges
......................................................................................................................................................... 254
addchangelist
......................................................................................................................................................... 255
addardiffs
......................................................................................................................................................... 256
addstream......................................................................................................................................................... 257
2 ClearCase Integration
................................................................................................................................... 257
GUI Client .......................................................................................................................................................... 258
Command Line Client
.......................................................................................................................................................... 260
addchanges......................................................................................................................................................... 261
addchangelist
......................................................................................................................................................... 263
addversions
......................................................................................................................................................... 264
addactivity
......................................................................................................................................................... 266
commit ......................................................................................................................................................... 267
3 CMVC Integration
................................................................................................................................... 268
GUI Client .......................................................................................................................................................... 268
Command Line Client
.......................................................................................................................................................... 268
addchangelist
......................................................................................................................................................... 269
addversions
......................................................................................................................................................... 269
addtrack ......................................................................................................................................................... 271
4 CVS ...................................................................................................................................
Integration 272
GUI Client .......................................................................................................................................................... 273


Contents v

Comparing two Labels
......................................................................................................................................................... 275
Comparing two dates
......................................................................................................................................................... 276
Command Line Client
.......................................................................................................................................................... 277
addchanges
......................................................................................................................................................... 278
addcvsdiffs
......................................................................................................................................................... 279
commit ......................................................................................................................................................... 280
5 Git Integration
................................................................................................................................... 281
Command Line Client
.......................................................................................................................................................... 281
addgitdiffs
......................................................................................................................................................... 281
6 Mercurial Integration
................................................................................................................................... 282
Command Line Client
.......................................................................................................................................................... 282
addhgdiffs
......................................................................................................................................................... 283
7 MKS...................................................................................................................................
Source Integrity Integration 284
GUI Client .......................................................................................................................................................... 284
Command Line Client
.......................................................................................................................................................... 287
addchanges
......................................................................................................................................................... 288
addchangelist
......................................................................................................................................................... 289
addversions
......................................................................................................................................................... 290
8 Perforce Integration
................................................................................................................................... 291
Perforce Server Integration
.......................................................................................................................................................... 292
GUI Client .......................................................................................................................................................... 295
Comparing files in a Branch
......................................................................................................................................................... 298
......................................................................................................................................................... 298
Comparing two dates
......................................................................................................................................................... 299
Command Line Client
.......................................................................................................................................................... 300
addchangelist
......................................................................................................................................................... 301
addp4diffs......................................................................................................................................................... 302
addversions
......................................................................................................................................................... 303
commit ......................................................................................................................................................... 304
addp4job ......................................................................................................................................................... 305
syncusers ......................................................................................................................................................... 305
update-id......................................................................................................................................................... 306
P4V / P4Win .......................................................................................................................................................... 306
Integration
Perforce Server Triggers
.......................................................................................................................................................... 308
ensure-review-started
......................................................................................................................................................... 308
ensure-reviewed
......................................................................................................................................................... 310
ensure-content-reviewed
......................................................................................................................................................... 311
update-changelist
......................................................................................................................................................... 312
9 Rational Synergy Integration
................................................................................................................................... 314
GUI Client .......................................................................................................................................................... 315
Command Line Client
.......................................................................................................................................................... 317
addchangelist
......................................................................................................................................................... 318
10 StarTeam Integration
................................................................................................................................... 319
GUI Client .......................................................................................................................................................... 319
Comparing two dates
......................................................................................................................................................... 320
......................................................................................................................................................... 321
Comparing two Revisions
......................................................................................................................................................... 322
Command Line Client
.......................................................................................................................................................... 323
addstdiffs......................................................................................................................................................... 323
11 Subversion Integration
................................................................................................................................... 324
Subversion Server Integration
.......................................................................................................................................................... 326
GUI Client .......................................................................................................................................................... 328


vi Code Collaborator v5.0.5022 Owner's Manual

Comparing two Revisions
......................................................................................................................................................... 331
Comparing two branches / tags
......................................................................................................................................................... 332
Comparing two dates
......................................................................................................................................................... 333
Command Line Client
.......................................................................................................................................................... 334
addchanges
......................................................................................................................................................... 335
addchangelist
......................................................................................................................................................... 336
addsvndiffs
......................................................................................................................................................... 337
commit ......................................................................................................................................................... 338
Subversion Server Hooks
.......................................................................................................................................................... 339
ensure-review-started
......................................................................................................................................................... 339
ensure-reviewed
......................................................................................................................................................... 341
create-review
......................................................................................................................................................... 342
12 Surround SCM Integration
................................................................................................................................... 343
GUI Client .......................................................................................................................................................... 344
Command Line Client
.......................................................................................................................................................... 346
13 Team Foundation Server Integration
................................................................................................................................... 347
GUI Client .......................................................................................................................................................... 347
Command Line Client
.......................................................................................................................................................... 350
addchanges
......................................................................................................................................................... 351
addchangelist
......................................................................................................................................................... 352
commit ......................................................................................................................................................... 353
14 Vault and Fortress Integration
................................................................................................................................... 353
GUI Client .......................................................................................................................................................... 355
Command Line Client
.......................................................................................................................................................... 357
addchanges
......................................................................................................................................................... 358
15 Visual SourceSafe Integration
................................................................................................................................... 359
Command Line Client
.......................................................................................................................................................... 359
addvssdiffs
......................................................................................................................................................... 360

Part VI External Integrations 361
1 Custom Reports
................................................................................................................................... 361
2 Bug-Tracking Integration
................................................................................................................................... 368
3 Scripting
................................................................................................................................... 369
Mirroring Defects to an external issue-tracker
.......................................................................................................................................................... 370
Adding a checklist to new Reviews
.......................................................................................................................................................... 373
Syncing users from Perforce
.......................................................................................................................................................... 375
Conversation with Eliza
.......................................................................................................................................................... 376

Part VII Techniques & Best Practices 381
1 Metrics: Definitions
................................................................................................................................... 382
2 Metrics: Analysis
................................................................................................................................... 383
3 Tips ...................................................................................................................................
and Tricks 385

Part VIII Appendices 386
1 Appendix A: Known Issues
................................................................................................................................... 386
2 Appendix B: Version History
................................................................................................................................... 389
3 Appendix C: Java VM Options
................................................................................................................................... 436


Contents vii

Index 439


1 Big Picture

1 Big Picture
This section will get you acquainted with Code Collaborator and go through the product overview 1 ,
components 1 , and a quick start guide 3 .

1.1 Code Collaborator Overview
Code Collaborator is a peer code review system supporting:
· Multiple, simultaneous reviewers
· Workflow supporting reviewers/authors separated by many time zones
· Version control integration
· Defect-tracking with severity, type, classification, checklists, and external issue-tracker integration
· Full-featured metrics, reports, and data-export
· Project- and role-based rules and reporting
· Web-based, rich-client, and command-line cross-platform clients
· Command-line API for integrations, extensions, automations, and triggers

1.2 Moving Parts
Code Collaborator includes a server component, and a variety of clients, 3rd-party integrations, and client
protocols.


2

Code Collaborator Server 6
As with most enterprise-class software systems, a server process acts as the hub, manager, and controller
of information. The server has a web-based user interface where users and administrators can do
everything — create and perform reviews, configure personal and system-wide settings and run reports.
The server uses an external database 7 to store all data and configuration.

Web Browser Client 93
The web browser client is used by entering an external URL in a web browser to connect to the Code
Collaborator server. This is where most of the review will take place, where you edit, view, configure the
reviews. The web interface supports Internet Explorer, Safari and FireFox.

Command-line Client 157
Developers will typically install the cross-platform client. This tool includes a Command Line Client that
lets you upload local files (and file-changes) into new and existing reviews. The Command Line Client
also includes scripting commands for implementing custom behavior and integrating with external
systems.
There are many reasons why you might want to integrate Code Collaborator with other systems. An
issue-tracker integration point might let you synchronize Code Collaborator "defects" with issue-tracker
"issues," or you might want to mirror review data (metrics/comments/file-differences) into the
associated ticket. A reporting integration point might let you mirror Code Collaborator metrics into your
existing reporting system (examples: defects/kLOC, defects/man-hour, kLOC/man-hour, number of
defects found of different types or severities, etc).


3 Big Picture

GUI Client 151
The cross-platform client install includes a graphical client to complement the web-based user interface
already provided by the server. The GUI client is a cross-platform client available for Windows, Mac,
and Unix/Linux users.

Tray Notifier 226
In addition to uploading files, the GUI Client gives you a taskbar icon that updates to show you whether
you have any pending tasks in Code Collaborator. This is called the Tray Notifier and is available to
Windows and Unix/Linux users. This allows users to easily access pertinent reviews and alerts the user of
any new activity in reviews without being actively involved in the web browser client.

Perforce® Integration 291
Perforce users will probably want to install the Perforce Client Integration tools. These are included in
the client installer 144 .
Integration with P4V and P4Win lets developers upload changelists into new or existing reviews just by
right-clicking on the changelist. This works on both "pending" and "submitted" changelists.
We also supply a special tool for use as a Perforce server trigger. For example, you can use this to
enforce a rule like "Every submit on this branch requires a review." You can also use this to automatically
upload all submitted changelists into Code Collaborator so that you can review code after it has been
checked in. This can be especially useful with off-shore development groups.

Eclipse™ Integration 230
The Eclipse Plug-in gives users the ability to upload files and perform reviews from within any Eclipse-
based application. A variety of applications are supported.

1.3 Quick Start
This section will briefly guide you through the steps of getting started with Code Collaborator. It is only
intended for users who want to jump right into Code Collaborator and start using the basic features. If
you'd like more detailed instructions on how to use Code Collaborator, please visit the appropriate
sections throughout the Owner's Manual.
We've divided this section into two guides. The Quick Start for System Administrators 3 will show you
how to install and configure the server component. The Quick Start for Developers 4 will describe the
steps needed to install the client component and start your first review.

1.3.1 For System Administrators
1. Download the Code Collaborator Server
The first thing you'll need to do is download the server installer from the Code Collaborator
page, http://smartbear.com/codecollab-download.php.

2. Installation Wizard
Once you've downloaded the installer, open it to begin the installation wizard. The wizard
should guide you through the steps below:
a. Welcome Page


For System Administrators 4

This just welcomes you to the installation process. Click Next to proceed.
b. EULA
Read the license agreement, and select "I accept the agreement" before clicking Next.
c. Destination Directory
Choose the folder where you would like the Code Collaborator server to be installed. Make
sure that the directory is writable by the server and that there are at least 5 gigabytes of space
available in the directory.
d. Configure Webserver
Enter an open port number that does not conflict with any existing services.
e. Start Menu Folder
Select a Start Menu folder where you'd like to create the Code Collaborator shortcut.
f. Database Connection
If you are trying out Code Collaborator, we recommend that you select Embedded to keep
things simple. This will not require a prior setup, and you can easily migrate your reviews to
real database later. If you'd like to configure another database now, you will be taken to a
screen that will let you configure your connection to the database server. For more details,
visit the Database section 7 .
g. Authentication Type
Choose one of the following authentication types:
Internal - Code Collaborator should maintain usernames and passwords in its own
database
LDAP - You can use LDAP authentication, which won't require you to maintain the
Code Collaborator usernames and passwords. If this is chosen, the next screen will let
you configure your LDAP integration. For more details, visit the LDAP section 30 .
h. Completed Page
This page will appear once the server is installed. Click Finish.

3. Log into the Web Browser Client
After you finish with the installation, a web browser will open automatically, pointed at your
installed server. Log in as admin, and leave the password field blank.

4. Choose the Product
This is where you can choose whether you'd like to use Code Collaborator or Code Reviewer.
To view the differences between these two products, visit our website, http://smartbear.com/
codecollab-codereviewer.php. You should also enter the Administrative Contact Information.

5. Create User Logins for your Users
You should supply at least two users for this section. Visit the User Management page 56 .

6. Configure the Settings
The Admin section is where you can configure the settings to your liking. Most of the settings
are self-explanatory, but if you need more explanation, visit the Configuration Section 46 .
1.3.2 For Developers
1. Download a client
You'll most likely need a client if you plan on uploading files from your Version Control/SCM.
Download the "Client Installer" listed under your platform from the Download page, http://
www.smartbearsoftware.com/codecollab-download.php. For more information about clients
and to find out which is most appropriate for you, visit the Clients Section 144 .


5 Big Picture

2. Installation Wizard
Once you've downloaded the installer, open it to begin the installation wizard. The wizard
should guide you through the steps below:
a. Welcome Screen
This just welcomes you to the installation process. Click Next to proceed.
b. EULA
Read the license agreement, and select "I accept the agreement" before clicking Next.
c. Destination Directory
Choose the folder where you would like the Code Collaborator client to be installed. You'll
need at least 22 MB of disk space.
d. Start Menu Folder
Select a Start Menu folder where you'd like to create the Code Collaborator shortcut.
e. Code Collaborator Configuration
Here, you will enter the Code Collaborator server URL, username, and password. Remember
to specify the protocol (e.g. http:// or https://) and port number, and path. If you do not
know this, ask your Code Collaborator system administrator.
f. Additional Tasks
Choose whether to run the Tray Notifier 226 on Startup.
g. Finish
Click Finish, and you're done installing the client.

3. Configure the Client to your SCM
GUI - Open up the GUI Client 151 , and click Add... on the right side of the window. Use the
Configuration wizard to enter the location of your local source code into the Local Path field at
the top. For more information, please visit the GUI Client section 151 .
Command-Line - SCM configuration is usually detected automatically. For more information, visit
the Command Line Client page 157 .

4. Log into the Web Browser Client
Open a web browser, and go to the Code Collaborator server URL provided by your system
administrator. Enter your login name and password. Once you log in, you can check your
Action Items 103 to see if you have any assigned reviews. You can also edit Preferences 154 by
clicking Prefs in the menu bar on the top right of the screen.

5. Create a Review as an Author
1. Click New Review in the menu bar at the top right to create a new review.
2. Fill in the basic information such as title and participants in the review wizard.
3. Add review materials via one of the clients or the web browser.
a. GUI Client - Click on the SCM Configuration you created in Step 3 5 . Use the Add to
Review 152 buttons at the bottom to add materials to the review.
b. Command-Line - Visit the Command Line Client section 157 for specifics.
c. Web browser - You can add supporting documents not under Version Control by
clicking Attach File 108 in the Materials section.
4. Click Apply and Begin Review to start the review and send out notifications to participants.

6. Add Comments and Defects as a Reviewer
You will receive an email inviting you to participate in a review. Click the link in the email to
open the review in your web browser. Under the Review Materials section, click a file. The diff
view will open, and you will be able to make comments and defects here.


For Developers 6

Comment 131 - Click on the line you want to comment on, and type your comment. Comments
will be threaded into a conversation, and unread comments from other users will be marked in
yellow. You can click Accept or Mark Read to clear the unread markings.
Defects 133 - Click on the line you want to attribute the defect to. Make sure the Add Defect tab is
selected and write a description of your defect, filling in the fields underneath. Once a defect is
made, you can mark the defect as fixed, edit the defect, delete the defect, or track it externally by
using the links at the bottom of the comment box. If defects are found in the review, authors
should fix the defects and upload the fixes, and the reviewer should inspect the code again until
the code is acceptable.

7. Finish the Review
Once all the defects are found and all the comments are read, you can finish the review by
clicking Finished at the bottom of the Moving On 120 section in your web browser client.

1.4 Contact Us
If you have questions or feature requests, drop us a line, or give us a ring.

For Technical Support:
support@smartbear.com
512.257.1569 or 877.501.5651 (M-F, 9am-5pm Central)

For Sales:
sales@smartbear.com
978.236.7860 (M-F, 9am-5pm Eastern)

These links might also be helpful:
Website:
http://codecollab.com
Downloads:
http://smartbear.com/codecollab-download.php

You can also view some of our FAQ's here:
http://www.smartbear.com/codecollab-faq.php

2 Server Administration
This chapter is useful for system administrators. Regular users of Code Collaborator should refer to the
Web User's Guide 93 instead.
This chapter covers everything from installation 11 /upgrades 17 to backup 26 to licensing 22 to general
system configuration 46 .



2.1 Installation
2.1.1 Database Installation
Code Collaborator supports several databases:
· Embedded 7 . A zero-configuration embedded database useful for trials
· MySQL 7 . v4.1, v5.0, v5.1.
· Microsoft SQL Server 8 . 2000 (v8.0), 2005, 2008.
· Oracle 9 . 10gR2

For trials, the zero-configuration embedded database is the easiest way to get started. MySQL is the best
choice if you need a free, open-source database.
A built-in database migration tool 27 allows you to move between any of the supported databases, so
you can always get started on one and switch to another later on.
For more about the database format, see the section on custom reporting 361 .

2.1.1.1 Zero-Configuration

The server installer comes with support for the Hypersonic embedded database. This in-memory
database is perfect for trials where you want to get up-and-running as easily as possible.
Using this database requires no configuration. When the server installer 11 asks for the database type,
simply select "Embedded."
While the embedded database is great for quick trials, performance goes rapidly downhill once you have
more than a handful of reviews, so for deployment we require a "real" database.
The standard database migration technique 27 works with all databases, so it's possible to move all your
data from the embedded database into a "real" database at any time.

2.1.1.2 MySQL

MySQL is a popular enterprise-class, open-source database supported by MySQL AB. This is your best
choice if you need a free, open-source database. This option scales well -- we have customers with
thousands of users running off a single MySQL database.

Downloading MySQL
For downloads and documentation for all platforms, see the MySQL Developer Zone web site. You'll
need the MySQL Database Server component for the database itself and the MySQL
Administrator component for easy, graphical server administration.
First install the Database Server component (remember that super-user username!), then install the
Administrator component.

Configuring the Database
Code Collaborator needs its own database. To create one, run the Administrator application.


Database Installation 8

The Administrator application will ask for connection information. Supply the super-user username you
established during database install.
To create the Code Collaborator database, first click "Catalogs" in the icon list. Then right-click in the
"Schemata" area below that and select "Create New Schema". Name the new schema "collaborator".
To create the special Code Collaborator username, first click "User Administration" in the icon list. Then
right-click in the "Users Accounts" area below that and select "Create New User". Name the new user
"collaborator" and optionally supply a password. Then switch to the "Schema Privileges" tab, click on the
"collaborator" schema, and assign all privileges by clicking the double-left-arrow button. You must click
"Apply Changes" below to complete the administration.
All of these changes go into effect immediately. You do not have to restart the MySQL server for
changes to take effect.
During the GUI installation screens 11 for the Code Collaborator server, you will be prompted for the
MySQL server host name, TCP/IP port, database name, user name, and password. The installer will
report any connectivity errors. When you visit the web page for Code Collaborator it will detect that you
have a new database and will create all tables, indexes, and views for you automatically.

MySQL Limitations
1. MySQL v4.x does not support the concept of a database VIEW object. Therefore custom reporting
views 366 are only present with v5.x servers.
2. Important: The MySQL native restore feature does not automatically clear the database before
restoring from backup. You can use the MySQL native restore feature, but you must manually drop
all tables in the database before you run the restore. By doing this, you'll ensure an exact reproduction
of your backed-up database. Option two is to use the alternative method 26 provided by Code
Collaborator.

2.1.1.3 SQL Server

This manual assumes you already have Microsoft SQL Server 2000 (v8.0), 2005, or 2008 installed and
running.

Instructions for SQL Server 2008 and alternate JDBC drivers
No single Microsoft JDBC driver supports all the versions of SQL Server that we support. We ship
with a driver that is compatible with many configurations, but not SQL Server 2008. The following
drivers can be installed and used in place of the shipped driver:
This driver supports SQL Server 2000, 2005 and 2008 running Java 1.4 or later:
Microsoft SQL Server JDBC Driver 1.2 Download
This driver supports SQL Server 2000, 2005 and 2008 running Java 5.0 or later:
Microsoft SQL Server JDBC Driver 2.0 EULA and Download
To install one of these drivers, or other JDBC driver:
1. Download the preferred driver.
2. Stop the Code Collaborator server, if it is running.



3. Go to the following location:
[Code Collaborator Server installation directory]/tomcat/
common/lib
4. Replace the sqljdbc.jar in that directory with one just downloaded.
5. Start the Code Collaborator server.

Setting up the database
Create a database for Code Collaborator. It is recommended that you also create a username/password
pair just for Code Collaborator and give this account full access to the database and no access to other
databases. You should use a SQL Server account instead of Windows-based authentication because the
Code Collaborator service might not be running under a normal Windows-based login.
SQL Server host name, TCP/IP port, database name, user name, and password. The installer will report
any connectivity errors. When you visit the web page for Code Collaborator, it will detect that you have a
new database and will create all tables, indexes, and views for you automatically.

SQL Server Limitations
With SQL Server 2000, text fields can contain a maximum 8000 characters. This includes changelist
descriptions, review overview text, and comment and defect text. With SQL Server 2005 and later there
is no such restriction.

Troubleshooting
If you get the error "The TCP/IP connection to the host has failed. java.net.UnknownHostException",
you probably need to enable TCP/IP for your database. By default SQL Server has the TCP/IP
protocol disabled. Code Collaborator needs this option enabled in order to access your database.
Open the SQL Server Configuration Manager and navigate to "Network Configuration" -> "Protocols".
Make sure TCP/IP is enabled.
By default SQL Server is configured to use dynamic ports, which means that the port used is changed
each time the service is restarted. To use static ports instead open properties for "TCP/IP" and change
the "IPAll" settings. Set "TCP Dynamic Ports" to blank and "TCP Port" to the port number you want to
use.

2.1.1.4 Oracle

This manual assumes you already have Oracle Database Server installed and running.

Supported Versions
The versions we've tested against are:
· 10gR2 Express Edition
Your mileage may vary with other versions. Contact us if you have problems -- we are interested in
fixing bugs!


Database Installation 10

Setting up the database
Create a database for Code Collaborator. It is recommended that you also create a username/password
pair just for Code Collaborator and give this account full access to the database and no access to other
databases.
Oracle server host name, TCP/IP port (default is 1521), database service name (not the SID!), user name,
and password. The installer will not report any connectivity errors.

Warning: The database service name is not the same thing as the SID!
This change was made by Oracle in version 9iR2.

The database service name is fully-qualified, corresponding to
GLOBAL_DBNAME in an .ora file. An example would be mysid.
mydomain.com. The database service name is also sometimes
referred to as "TNS alias" or "connect descriptor."

The SID is the shorter name, corresponding to SID_NAME in an .
ora file.

When you first visit the web page for Code Collaborator, it will detect that you have a new database and
will create all tables, indexes, and views for you automatically, or give you an appropriate error message if
there's a connectivity problem. Connectivity problems should be resolved by re-running the installer.

Oracle Limitations
The length of long strings is limited to 1023 characters. This applies to fields such as custom fields,
changelist text, comment text, and defect text.

Troubleshooting
We use the Oracle JDBC driver to connect to your Oracle database. The driver has a few
undocumented behaviors that may come as a surprise. There are threads on Oracle's tech support
forums about this.
Most of the problems arise in the GLOBAL_DBNAME field in your SID_DESC entry from your
listener.ora file. A typical entry might look like this:
(SID_DESC =
(GLOBAL_DBNAME = mysid.mydomain.com)
(ORACLE_HOME = /appl/oracle1/product/10.2.0.1)
(SID_NAME = mysid)
)

Most other Oracle-based programs use the SID_NAME field to identify the database, but the JDBC
driver uses GLOBAL_DBNAME. This would cause a connection error in the example above.
Also note that the database service name is not the same thing as the SID. This change was made by Oracle in
version 9iR2. The installer asks for the database service name, not the SID. The database service name is
also sometimes referred to as "TNS alias" or "connect descriptor."



Typically, this means you should use the GLOBAL_DBNAME in the installer (i.e. mysid.mydomain.
com) and not just the SID (i.e. mysid).

2.1.2 Server Installation
Code Collaborator uses a stand-alone web server for a cross-platform, no-client, firewall-friendly user
interface.

The Graphical Installer
Installers can be run in a graphical, interactive mode or an automatic mode. For first installation, you will
need to run the graphical version so you can select options.
First, you need to download the correct installer for your platform from our website:
http://smartbear.com/codecollab-download.php

The first screen of the wizard lets you know it's working:


Server Installation 12

The second screen is the EULA (End User License Agreement):

The next screen allows you to select the disk location for the installation files. Permissions here are
important:

This directory should be writable by the server because several dynamic files are created here including
web server logs, temporary storage, and long-term storage for file content uploaded by users. All of
these locations can be changed if it is critical that the installation location be read-only, but this requires
significant work on the part of the administrator and makes upgrades more difficult.
Make sure at least 5 gigabytes of space is available in the named directory. Your users will need the space
for file uploads. You can always move and/or archive 91 the file upload directory.



The next screen configures the web server settings:

The port number should be selected as to not conflict with any existing services. The installer will
attempt to connect to this port when you click Next; if the port is already taken by another process, you
will get a warning message. You can elect to try a different port or continue. Continue at your own risk --
probably the server will not be able to start up and you'll have to make the port available and restart the
server manually.
The next screen will ask where you would like to create the Code Collaborator's shortcut. Click "Don't
create a Start Menu folder" if you would not like to create a folder for Code Collaborator.

Next, you configure the database connection. The database should already be installed and ready 7 :



For trial installations, you'll probably want to select the default "Embedded" database 7 . You should
migrate 27 to a full-featured database before you use the server in production.
If upgrading servers 17 , you should select "Existing Configuration" to choose to maintain the same
configuration as your older installation. "Existing Configuration" will only be grayed out during fresh
installations where the server has not been previously installed.
If you picked anything but the "Embedded" database, the next screen lets you configure the connection
to the database server:



The exact format of this screen depends on the database you chose. The Username and Password
fields here refer to the database username and password. Typically, you will want to create a special
database username and password for the Code Collaborator application so you can control exactly
which data it has access to. This usually means full access to the database created for Code Collaborator
and no access to any other database.
The next screen lets you decide how users will be authenticated in Code Collaborator.

The simplest setting is "Internal," which means Code Collaborator should maintain usernames/
passwords in its own database.
If your company uses LDAP or ActiveDirectory, you can use that method to authenticate users in Code
Collaborator, which means you don't have to maintain the Code Collaborator user list at all. If you select
the LDAP method you will get an additional wizard screen that lets you supply the settings for your
LDAP server. See the LDAP section 30 for details.
You will also have the option to choose "Existing LDAP authentication configuration" if you are
upgrading 17 an existing installation.



After this, the installer lays down the server files, stopping any existing server if necessary. Once the new
files are installed, the server is started automatically, and the installer tells you it is finished:

After you click Finish, a web browser will open, pointed at your installed server.

Warning: If the server hasn't quite had enough time to fully start up, it
might take a while for the web page to load and it might even fail to
open. Just "refresh" the browser.

The Non-Graphical Installer
If you are upgrading the server instead of installing from scratch, you have the option of installing
without any graphical user interface.
We recommend that you always use the graphical interface when possible because it gives you the chance
to review settings, especially new settings that we might have added since your last installation.
To run the installer without a GUI, run the installer from a command-line using the -q switch.
To set the installation directory from the command-line, use the -d [directory] switch.

Installing more than one server instance on a single machine
All server instances need to be running on unique and available ports. Each server instance will also need a
separate database and license code.
On Windows, install the different instances in different directories, on different ports, with separate
database instances. This will get all of the software installed, but only the last one will be properly installed
as a service. To install the others as a service, run the following command from the command line:
<install-dir>ccollab-server /install service-name


Code Collaborator User Guide

Recommended

Recommended

More Related Content

What's hot

What's hot (14)

Similar to Code Collaborator User Guide

Similar to Code Collaborator User Guide (20)

More from tutorialsruby

More from tutorialsruby (20)

Recently uploaded

Recently uploaded (20)

Code Collaborator User Guide