Swarm 2015.2 Guide (August 2015)

Install the Swarm trigger script on the Perforce server.

If the Swarm trigger script has not already been installed on your Perforce server machine, you need to copy p4-bin/scripts/swarm-trigger.vbs from your Swarm install to the Perforce server machine so that it can be executed by the Perforce server.

Configure the Swarm trigger script.

You need to use the API token established in the Establish trigger token section.

Modify the swarm-trigger.vbs script to set the SWARM_HOST and the SWARM_TOKEN variables appropriately.

Verify that the trigger script executes correctly.

Run:

C:\windows\system32\cscript.exe /nologo "C:\path\to\swarm-trigger.vbs" /type:ping /value:0

You should expect to see no output. If the trigger is misconfigured, such as using an invalid trigger token, you would see an error.

Update the Perforce triggers table to run the trigger script.

As a Perforce user with super privileges, edit the Perforce trigger table by running the p4 triggers command and add the following lines:

swarm.job        form-commit   job    "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:job /value:%formname%"
swarm.user       form-commit   user   "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:user /value:%formname%"
swarm.userdel    form-delete   user   "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:userdel /value:%formname%"
swarm.group      form-commit   group  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:group /value:%formname%"
swarm.groupdel   form-delete   group  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:groupdel /value:%formname%"
swarm.changesave form-save     change "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:changesave /value:%formname%"
swarm.shelve     shelve-commit //...  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:shelve /value:%change%"
swarm.commit     change-commit //...  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:commit /value:%change%"
  

Copy the perl trigger to the Perforce service.

If your Perforce service is version 2014.1 (or newer), we recommend submitting the trigger file, p4-bin/scripts/swarm-trigger.pl, to Perforce and running it from the depot. The recommended depot location would be //.swarm/triggers/swarm-trigger.pl, especially if you have already setup Comment attachments.

If your Perforce service is older than version 2014.1, or prefer that the trigger exist in the filesystem, you must copy the p4-bin/scripts/swarm-trigger.pl script to the Perforce server. If your Perforce service deployment uses the commit-edge architecture, the script must also be copied to all edge servers, and it must exist in the same path on all servers.

Configure the Perl trigger.

You need to use the API token established in the Establish trigger token section.

swarm-trigger.pl can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf, as using the configuration file greatly simplifies upgrades.

If you are using the Swarm triggers package described in Swarm packages, the file is available at /opt/perforce/etc/swarm-trigger.conf, otherwise create swarm-trigger.conf in the same directory as swarm-trigger.pl.

If you submitted the trigger script to the depot in the previous step, you should similarly submit the configuration file to the depot. The recommended path is //.swarm/triggers/swarm-trigger.conf.

If you copied the trigger script to the commit server and all edge servers in the previous step, also copy the configuration file to the commit server and all edge servers, making sure that it exists in the same path on all servers.

The following is a sample of what your swarm-trigger.conf should contain:

# SWARM_HOST (required)
# Hostname of your Swarm instance, with leading "http://" or "https://".
SWARM_HOST="http://my-swarm-host"

# SWARM_TOKEN (required)
# The token used when talking to Swarm to offer some security. To obtain the
# value, log in to Swarm as a super user and select 'About Swarm' to see the
# token value.
SWARM_TOKEN="MY-UUID-STYLE-TOKEN"

# ADMIN_USER (optional)
# For enforcing reviewed changes, optionally specify the normal Perforce user
# with admin privileges (to read keys); if not set, will use whatever Perforce
# user is set in environment.
ADMIN_USER=

# ADMIN_TICKET_FILE (optional)
# For enforcing reviewed changes, optionally specify the location of the
# p4tickets file if different from the default ($HOME/.p4tickets).
# Ensure this user is a member of a group with an 'unlimited' or very long
# timeout; then, manually login as this user from the Perforce server machine to
# set the ticket.
ADMIN_TICKET_FILE=

Modify the swarm-trigger.conf configuration file to set the SWARM_HOST and the SWARM_TOKEN variables appropriately.

p4d -p my-perforce-service:1666 ...

p4 -p my-perforce-service:1666 -u admin_userid login

'swarm.strict.1' validation failed: Invalid login credentials to [port] within this trigger script; please contact your administrator.

Ensure that the script has execute permissions.

$ chmod +x /path/to/swarm-trigger.pl

Verify that the trigger script executes correctly.

/path/to/swarm-trigger.pl -t ping -v 0

Update the Perforce triggers table to run the Perl trigger.

As a Perforce user with super privileges, edit the Perforce triggers table by running the p4 triggers command and add the appropriate set of lines:

Configure the Perforce service to promote all shelved changes.

p4 configure dm.shelve.promote=1

When this configurable is set, Swarm has access to all shelved changelists, which is a requirement for pre-commit reviews. When it is not set, users connected to an edge server must remember to use the -p when shelving files to promote their shelves to the commit server when initiating a pre-commit review.