Applies to Collaborator 11.4, last modified on December 3, 2018

Collaborator seamlessly integrates with the Perforce version control system. This section provides a general overview of integration preferences, ways to review files controlled by Perforce, and so on.

About Integration

Using the built-in Collaborator Perforce integration, you can quickly upload various files to the Collaborator server to create a review directly from the desktop client of your choice. The types of files you can upload include:

  • Pending changelists.
  • Submitted changelists.
  • Arbitrary Perforce diffs.
  • Files in branch.
  • Differences between labels.
  • Differences between dates.

Perforce integration uses Perforce client applications that are already installed on the client computer. That is, integration supports all protocols, authentication settings, proxies, and other configuration specifics. This includes configuration from environment variables, $P4CONFIG files, p4 set registry values, and so on.

Ways of Integration

You can enable the integration between Collaborator and Perforce for GUI Client, Command-Line Client, Eclipse Plug-in, Collaborator server, or use the integration in the p4v and p4win client applications.

GUI Client

To enable the integration:

  1. Start GUI Client.

  2. Click Add to create a new SCM configuration.

  3. In the subsequent SCM Configuration dialog, specify the local source code location.

  4. Select Perforce in the SCM drop-down list.

  5. Several options will become available. These are specifically tailored to configure Perforce integration.

    Option Description
    P4 Executable A full path referring the p4 executable.
    P4PORT A p4port required to connect to the perforce server.
    P4USER A username you want Collaborator to use on connecting to the Perforce server.
    P4PASSWD A password you want Collaborator to use on connecting to the Perforce server.
    P4CLIENT A mapping string used to transfer Perforce server data to the local machine.
    Ignore Integration History If selected, integration will ignore the integration history wile calculating the predecessor changelist.
    P4CHARSET A Perforce character set used for translation of Unicode files.
    Require empty default changelist If selected, does not allow to upload if the default changelist contains any files.
    Specify Perforce command charset If selected, requires a character set to be specified on connecting to the Perforce server.
    SCM Configuration: Perforce

    Click the image to enlarge it.

  6. Once ready, click Validate to make sure the integration is operational.

After that, a new configuration for Perforce will appear on the main screen of the GUI Client.

Select it, then click on the corresponding button depending on what you want to do next:

Add to Review buttons
  • Add Pending Changelists – Upload files in a Perforce pending changelist to the Collaborator server and add these to a review.

    Add Perforce Pending Changelists
    Note: You cannot upload the default changelist.
  • Add Submitted Changelists – Upload files in a Perforce submitted changelist to the Collaborator server and add these to a review.

    Add Perforce Submitted Changelists
  • Add Perforce Diffs – Upload arbitrary Perforce diffs to the Collaborator server and add these to a review.

    Add Perforce Diffs

    On the Branch tab of the dialog, you can upload the files in a branch.

    Upload the files in a branch

    On the Labels tab of the dialog, you can upload the difference between two labels.

    Upload the difference between two Labels

    On the Dates tab of the dialog, you can upload the difference between two dates.

    Upload the difference between two dates

Command-Line Client

In the Command-Line Client, you can create a review for various activities and files contolled by Perforce.

Commands recommended for Perforce

ccollab addchangelist - Attaches an atomic changelist to a review.

ccollab addp4diffs - Uploads diffs generated from p4 diff2 command.

ccollab addversions - Attaches any 2 given versions to a review.

ccollab commit - Commit changes in the review.

ccollab addp4job - Adds all numbered local changes that fix a job to the review.

ccollab admin syncusers - Synchronizes the Perforce user list with the Collaborator server.

ccollab admin changelist update-id - Updates the changelist ID so Collaborator reflects the renumbered Perforce changelist ID.

The addchangelist command will upload Perforce changelists into Collaborator. You can upload changelists either before or after they are submitted, but you cannot upload the default changelist.

In most cases, the Command-Line Client can automatically detect your Perforce configuration. Try testing your configuration to verify the configuration is detected correctly.

If the Command-Line Client is unable to detect your Perforce configuration or you want to override the detected settings, you can manually specify Perforce settings using global options.

To manually configure the Command-Line Client to use Perforce, execute the following command:

ccollab set scm perforce

Perforce-specific Options

Option

Description

--p4 <value>

Full path to the P4 executable.

--p4port <value>

How to connect to the Perforce server.

--p4user <value>

Perforce user name.

--p4passwd <value>

Perforce password or ticket.

--p4client <value>

Mapping of Perforce server data to the local machine.

--p4-ignore-integration-history <value>

Ignore integration history when calculating predecessor.

--p4charset <value>

Perforce character set used for translation of Unicode files.

--p4-require-empty-default-changelist

If true, do not allow uploads if the default changelist contains files.

--p4-specify-command-charset <value>

Should a character set be specified for communication with Perforce.

If your Perforce server requires ticket-based authentication (server security level 3), then the configured p4-password will be used to automatically issue the p4-login and acquire a new ticket as necessary.

If you want to ignore the integration history of files when determining the previous version of the file and look only at the path, you should set p4-ignore-integration-history to yes.

ccollab set p4-ignore-integration-history yes

Note for Windows users: Sometimes Perforce server uses Windows machine host name as a default name, ignoring the real Perforce client name. To avoid that issue, specify the needed Perforce client name directly in the Collaborator with the --p4client <name> command.

Eclipse Plug-in

You can upload locally modified Perforce files to a review directly from Eclipse Plug-in. Right-click on any changelist entry in Eclipse, either before or after it is submitted.

To learn more, please see Add to Review Wizard.

P4V and P4Win

The Collaborator client installer includes an integration point with P4V and P4Win clients.

Configuring P4V and P4Win Clients

If you installed the client yourself and decided to configure addons to Perforce visual tools, then you can skip the manual configuration of the integration. However, if the Collaborator client was installed by an administrator on your computer, or the configuration failed at install time, you can manually configure them.

  1. Go to Tools.

  2. Click Manage Custom Tools.

  3. In the subsequent dialog, click Import Tools.

  4. Navigate to the Collaborator client installation directory and select one of the following files:

    • P4V-Tools-Import.txt
    • P4V-Tools-Import.xml
  1. Go to Tools.

  2. Click Import.

  3. Navigate to the Collaborator client installation directory and select the P4Win-Tools-Import.txt file.

The plug-ins will work only if the Perforce command-line tool (p4) is in your PATH environment variable.
How Integration Features Work

Once configured, integration allows to create Collaborator reviews for pending and submitted changelists directly from the P4V or p4Win client.

Right-click on one or more changelists in the Pending Changelists or Submitted Changelists view and select SmartBear - Add to Review.

Adding pending changelist in P4V client

Click the image to enlarge it.

Right-click on one or more changelists in the Pending Changelists or Submitted Changelists view and select SmartBear - Create New Review with Changelist or SmartBear - Attach Changelist to Existing Review.

Adding pending changelist in P4Win client

Click the image to enlarge it.

Multiple Perforce workspaces and servers

The P4V and P4Wind plugins are able to work with multiple Perforce workspaces and servers. All the Perforce connectivity parameters are taken from the UI, so whatever workspace, server, and authentication you are currently using when you right-click the item the plugin will be able to handle the integration automatically. None of this affects the behavior or configuration of the command line client, so you can freely use the plug-ins without disturbing that configuration.

Troubleshooting

For any issues with the P4V and P4Win plugins, provide a debugging log to the SmartBear support. To do this, edit the custom tool configuration (Tools > Manage Custom Tools > Edit), and add a --debug argument to the beginning of the arguments list. This will create a log file at the following location: ~/.smartbear/log/ccollab.log on Unix platforms and %USERPROFILE%/.smartbear/log/ccollab.log on Windows platforms.

Please contact our technical support and send the log file along with a full description of what you were trying to do when the error occurred.

Collaborator Server

The Collaborator server can be configured to communicate directly with your Perforce server. This allows users to review submitted changelists completely from the browser, without having to install any client programs.

To enable this feature:

  1. Install and configure a Perforce client on the Collaborator server.

  2. Go to the Version Control tab of the administration interface.

  3. Once there, create an entry for your Perforce server.

    Tip: Entries are also appear automatically if one of the client programs uploads files from a server that does not match any of the currently configured servers.
    Perforce Version Control Server entry

Please refer to the following table to configure the integration properly:

Option Description
Title The title is displayed to users, so it should be something that everyone will understand, even if they are going through proxies, VPNs, or other such things. When a version control server entry is created automatically, this is filled in with the server address (p4port) of the server.
Attach changelists from browser If enabled, this feature lets users select submitted changelists to review directly from the web browser, without having to install any client programs.
P4 Executable Full path to the P4 executable.
P4PORT Address to use to connect to the server. When a version control server entry is created automatically, this is filled in with the server address obtained from the client.
P4USER Perforce user name.
P4PASSWD Perforce password or ticket.
P4CHARSET Perforce character set used for translation of Unicode files.
Perforce protections

The Collaborator server can be configured to check Perforce protections with the Perforce server whenever a user tries to access a file.

When enabled, Collaborator will check access permission with your Perforce server whenever a user tries to access the content of a file managed by this server. Note that this assumes that the user's Perforce username is the same as their Collaborator login.

To check Perforce protections the configured P4USER must have Perforce superuser permissions. If you do not want to provide an account with that level of permission, you can instead configure a script for Collaborator to run instead of calling 'p4 -s protects' directly.

The script will be passing arguments "-p <p4port> -u <user> -h <host> <depotPath>". For example, this script could be implemented as a Windows batch file:

@p4 -u admin -s -p %2 protects -u %4 -h %6 %7
The script must produce exactly the same stdin, stdout, and process error code as if Collaborator ran p4 -s protects directly. Also make sure the script runs as fast as possible, because it will be invoked every time any user tries to view the contents a file from this server.
Client configuration mapping

You can supply Java-style regular expressions to map changelists uploaded from our client tools to this Perforce server. It is important to set up these regular expressions so that files uploaded by the various Collaborator client tools are correctly associated with this server-side Perforce configuration.

Option Description
P4PORT Pattern Match on the client configured P4PORT. Using the Server Address Pattern is better, but clients before 5.0.5009 did not upload server address, so you can configure this as a fallback.
Server Address Pattern Match on the server address returned from running p4 -p <p4port> info on the client. This is generally more reliable than matching on the P4PORT, and works through Perforce proxy servers and other complications. When a version control server entry is created automatically, this is filled in with the server address obtained from the client.

Supported Versions

To enable the integration via GUI Client and Command-Line Client, you need the Perforce command line client (p4) to communicate with the server. We support all client and server versions later than 2002.1.

Eclipse Plug-in can use the Perforce plugin for Eclipse starting from version 2009.2.234487 and later.

Perforce Triggers

This section provides a reference on the triggers specific to Collaborator, added to Perforce by Collaborator Perforce Server integration package.

Trigger Description
ensure-review-started Ensures that a review has been started (created in Collaborator) for the submitted changelist.
ensure-reviewed Ensures that a review has been completed for the submitted changelist.
ensure-content-reviewed Ensures that a review has been completed for the submitted changelist, and that the changelist was not changed after the review was over (that is, that the file contents and the file list are the same).
update-changelist Appends or updates review-specific information in a changelist's description.

For general information on Perforce triggers, see Perforce System Administrator's Guide.

Perforce Changelist Renumbering

Perforce nearly always renumbers changelists upon submission, but when you are doing pre-commit reviews, Collaborator always has the pre-submit number. We have included a script you can customize that will ask Perforce what was a number of the changelist before it was submitted, and update changelists in Collaborator to have the new number. This requires a Collaborator client and server 5.0.5005 or better, and a Perforce client and server 2007.3 or later. This script is intended to be run periodically via cron or a similar task scheduler.

Perforce Changelist Renumbering Script

Support for Branch and Integrate

Collaborator fully supports file branching and integration semantics of Perforce.

  • If files in a changelist are marked for branching, they are not considered changed. The file content itself is not changed; only the file paths are being changed.

  • If files in a changelist are being integrated, this works just like a regular change. Many customers choose to review integrations especially carefully since the changes might interact in unexpected ways.

Support for Copy and Move

Collaborator fully supports file copy and move semantics of Perforce. If a file is copied or moved rather than added from scratch, it will show up that way in the various user interfaces.

Support for Directories

Collaborator partially supports Perforce directories and correctly handles the changes you apply to these.

All files underneath the directories in question will be scanned, uploaded, and represented properly in the GUI. The directories themselves will not be shown in any GUI.

Support for Shelvesets

Collaborator supports adding Perforce shelvesets to reviews.

Known Issues

If you want to use the Mark for Delete on a file and add this file to the newly created Collaborator review, synchronize this file with the depot. Otherwise, this file can be absent from your Perforce workspace and Collaborator will return an exception.

See Also

Integration With Repository Hosting Services
SCM Configuration
Source Control Integrations

Highlight search results