Using Perforce with codeBeamer

Perforce Integration

We support external Perforce repositories, so you should have a Perforce server (it can be on localhost also) and know the connection details (protocol, host, port, depot, user, password ...).

Perforce installation on codeBeamer server

Because the Perforce codeBeamer integration uses Perforce client executable ("p4" or "p4.exe") this must be installed on codeBeamer server host and must be executable and available on the PATH of the codebeamer OS user.

Creating a New Perforce Repository

To create new Perforce repository go to the SCM Repositories tab and click on New Repository link.

Select Perforce from the list and click Configure button.

Fill mandatory fields.

Note:

The Perforce URL must include the host name of the Perforce server, and can optionally include the protocol and port number. The default values for url are SSL protocol and 1666 port. The Perforce protocol can be any of the "ssl","tcp", or the standard Perforce protocol values .

Examples for valid Perforce Urls:

• localhost
• ssl:localhost:1666
• tcp:localhost

Depot path is the name of the depot, can be provided with and without "//" as depot prefix. for ex.:

• depot1
• //depot1

If you fill all necessary fields then click on the Save button and the new repository will be created. The system will verify the connection and reject the invalid settings or user/password if necessary.

Managing your Perforce server with codeBeamer

After you have create your Perforce repository in codeBeamer you will see the Perforce changes/commits/diffs in codeBeamer immediately.

But this information is populated only at the time when Perforce repository is created: the new changes in Perforce depot will not be visible unless the repository is refreshed.

To get a better integration you will need to instrument your Perforce server by installing a set of Perforce triggers to your server. These triggers are called ScmLoop and is provided as part of codeBeamer suite to make this integration possible.

By installing ScmLoop triggers you will get following features:

• codeBeamer will control User Permissions: your Perforce server will accept submits only from users who has Permissions to commit, and these Permissions are configured and managed inside your codeBeamer installation.
• codeBeamer will know when a Perforce commit happens, so any new Perforce changes appear inside codeBeamer.
• codeBeamer will automatically bind that appropriate codeBeamer Task to your Perforce commits. See: Tracing Source Code Changes to Requirements, Task and Bugs
• codeBeamer can force Perforce to accept only those commits which has a valid codeBeamer Task associated to. This needs that "Commits/push only with valid codeBeamer Item IDs" option is turned on.
• codeBeamer will send notification email about the new Perforce submits to the appropriate codeBeamer users. See: Tracking Source Code Changes and Developer Team Activity through Commit Notification Emails

Installing ScmLoop: the Perforce triggers

Installing ScmLoop - the codeBeamer integration- means that you install the ScmLoop as triggers on your Perforce server. For more information see: Perforce documentation about Triggers

Important: because Perforce server executes triggers as a specific OS user you will need to be sure that all executables mentioned here is on the PATH of this user, and the ScmLoop installation directory is accessible/executable/writable by this OS user!

Prerequisites:

• Install Java openjdk 1.8 and put on PATH.
• Install Apache Ant and put on PATH.
• Install Perforce client executable and put on the PATH.

Next: Pick a directory where the ScmLoop will be installed . This directory must be accessible and writable by the Perforce user of your OS which executes the triggers. For example use a directory like: /opt/scmloop/.

You can find the scmloop.zip file inside your codeBeamer installation directory as $CB_HOME/tomcat/webapps/cb/scmloop.zip. Copy this file to the Perforce server to the scmloop directory (like /opt/scmloop) and unzip it here.

The "scmloop" or "scmloop.bat" (depending your OS) is the main executable. Edit this, and update these lines:

The CB_BASE_URL variable must contain the HTTP url of your codeBeamer installation, the SCM_DIR must contain the current directory where ScmLoop is installed.

Binding ALL Perforce Depots to codeBeamer's Perforce repositories

After the previous steps ScmLoop is installed on your Perforce host, but no Perforce triggers has been installed yet.

So to get the correct Perforce->codeBeamer integration you will need to install the Perforce triggers for ALL the Perforce Depots you want to manage in codeBeamer. So if you have 10 Depots in Perforce and want to integrate all with codeBeamer then create 10 appropriate repositories in codeBeamer and bind each Depot to codeBeamer as described below.

So to install the ScmLoop trigger go to the ScmLoop installation directory and there you will find a "perforce" directory and an install_triggers.xml Ant script here:

...SCM_DIR...
├── cb-commitclient.txt
├── perforce
│   ├── install_triggers.xml
│   ├── triggers-original.txt
│   ├── triggers.txt
│   ├── unix
│   │   ├── change-commit
│   │   └── change-content
│   └── windows
│       ├── change-commit.bat
│       └── change-content.bat
├── scmloop
├── scmloop.bat
...

Install the triggers by executing this command in $SCM_DIR/perforce directory.

Important: before executing the script ensure that you are logged in to Perforce using a p4 login command using an Perforce user-account which has necessary privileges to install triggers!

ant -f install_triggers.xml

This script will ask about:

• The id number of the codeBeamer repository to bind the Depot to. You can find this on the codeBeamer UI:
• The Depot's path like "//depot"
• The Perforce user and password: the trigger needs a Perforce user and password to get the information necessary from your Perforce server.

Enter these, and the script will install the Perforce triggers. A sample output looks like:

The installation for this Depot is completed: the necessary Perforce triggers are added - can be verified using p4 triggers command.

Troubleshooting Perforce triggers

When Perforce triggers does not work then:

• Check the log file: cb-commitclient.txt
• Check that the Perforce trigger user can read/write/execute the files in the ScmLoop directory
• Check that all your Depots are configured to the appropriate codeBeamer repository!

Permissions: who can submit a change?

After the ScmLoop triggers are installed into Perforce server then codeBeamer will allow only those submits by Perforce users who has appropriate Permissions to submit changes in codeBeamer.

What happens here is:

• Perforce user submits a change using the usual Perforce clients ("p4 submit" command for example or the native UI clients")
• ScmLoop trigger communicates with codeBeamer:
• codeBeamer figures out who is the "codeBeamer account" for the "Perforce submitter", and checks if this codeBeamer account has permission to submit
• codeBeamer allows the submit only if the Perforce user has appropriate permissions
• Perforce client accepts the change or shows the approriate error message

Mapping of Perforce users to codeBeamer users and managing Permissions

In order to make the Permission checks work codeBeamer has to figure out who is the codeBeamer account for an Perforce user. This happens like this:

• The Perforce changeset contains a submitter information in the form like "super <zluspai@intland.com>". This contains the Perforce account name ("super") and the submitter's email address ("zluspai@intland.com").
• codeBeamer first checks if there is the same codeBeamer account exists with the same account name. So if there is a "super" codeBeamer account then this will be used for "super <zluspai@intland.com>" Perforce user.
• If no matching account found then codeBeamer checks the email addresses to find the codeBeamer user. It will only look for the "active" members of project where the SCM repository is located.
  In this example it will look for the 1st active user with "zluspai@intland.com" email address.
  
• If still account found then a special "system" user of codeBeamer is used. This user always exists in the system as global account.

So the best way to map Perforce accounts to codeBeamer accounts is to set the email address inside Perforce to match with the email address in codeBeamer. This screenshot illustrates a correct mapping:

Streams and Branches

We support Perforce branches as streams. You can find more information about this at: branching with streams.

So when you create a repository and set the depot path then we find streams in the depot and you can switch to the selected stream.

On the Changes tab you can switch between streams:

On the Files tab you can switch between streams: