Helix Core is now P4 and Helix Swarm is now P4 Code Review. Learn more >>

Documentation | 2025.2

# Installing Triggers

- If you are using P4 Code Review P4 Server Triggers, the P4 Code Review P4 Server extension must not be installed.

- P4 Code Review does not support P4 Servers configured to use P4AUTH, see Centralized authorization server (P4AUTH) in the P4 Server Administration Documentation.

- P4 Code Review can be connected to P4 Servers (P4D) and commit servers.

To configure P4 Code Review to connect to more than one P4 Server (P4D), see Multiple P4 Server instances.

To configure P4 Code Review to connect to a P4 Server configured to use commit-edge architecture, see Commit-edge deployment.

- P4 Code Review must not be connected to P4 Broker, P4 Proxy, P4 Edge, forwarding replica, or read-only replica servers.

Triggers are still supported, but we recommend you use P4 Server Extensions. P4 Server Extensions are easier to install and maintain than Triggers. For instructions on installing Extensions, see Installing the P4 Code Review P4 Server extension (recommended).

Now that you have a configured instance of P4 Code Review, the last piece is to configure your P4 Server to tell P4 Code Review about interesting events. This can be accomplished through the use of triggers.

For more information about P4 Server triggers, see Triggers in P4 Server Administration Documentation.

## Using triggers to push events to P4 Code Review

P4 Server provides a facility called triggers to customize the operation of the server, or to invoke additional processing for specific kinds of versioning operations. P4 Code Review provides a trigger script written in Perl that notifies P4 Code Review about activity within the P4 Server.

See Trigger options for more information on configuring the Perl trigger.

### Set up P4 Code Review triggers with a Windows or Linux-hosted P4 Server

Many of the steps in this procedure are common to both Windows and Linux-hosted P4 Servers. When there is a difference between the Windows and Linux operating systems, this is indicated in the procedure.

1. Ensure that the required Trigger dependencies have been installed on the machine hosting the P4 Server.
2. Copy the P4 Code Review trigger to the P4 Server

- If your P4 Server is version 2014.1 (or later), we recommend submitting the trigger script,`p4-bin/scripts/swarm-trigger.pl`, to P4 Server and running it from the depot. The recommended depot location is `//.swarm/triggers/swarm-trigger.pl`, especially if you have already setup Comment attachments.
- If your P4 Server is older than version 2014.1, or you prefer that the trigger file exist in the filesystem, you must copy the `p4-bin/scripts/swarm-trigger.pl` script to the server hosting P4 Server. If your P4 Server 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.

3. Trigger requests to P4 Code Review without a valid API token are ignored. Obtain your API token:

   1. Log in to P4 Code Review as a super user.
   2. Click your userid, found at the right of the main toolbar.

   3. Select About Swarm.

      The About Swarm dialog is displayed and P4 Code Review generates an API token if it doesn't already exist.

   4. Make a note of the trigger token value displayed at the bottom of the dialog, you will need the trigger token when you configure P4 Server for P4 Code Review.

   Click on the trigger token to select it and then copy it to your clipboard. You can paste it into the `swarm-trigger.conf` file when you configure P4 Server for P4 Code Review.

4. Configure the trigger.

You need to use the API token established in the previous step.

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

- If you are using the P4 Code Review triggers package described in Install and configure P4 Code Review from a package (recommended), the configuration file is available at `/opt/perforce/etc/swarm-trigger.conf`

- 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 depot location 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 they exist in the same path on all servers.

- If you are not using the P4 Code Review trigger package, 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 depot location 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 they exist 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) Do not use if the Workflow feature is enabled (default)
    # 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) Do not use if the Workflow feature is enabled (default)
    # 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=

    # VERIFY_SSL (optional)
    # If HTTPS is being used on the Swarm web server, then this controls whether
    # the SSL certificate is validated or not. By default this is set to 1, which
    # means any SSL certificates must be valid. If the web server is using a self
    # signed certificate, then this must be set to 0.
    VERIFY_SSL=1

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

Windows only:

You may need to edit the trigger script to specify the full path to `curl.exe` if the `HTTP::Tiny` module is not installed.

Linux only:

`swarm-trigger.pl` looks for configuration in the following files. Variables defined in the later files will override the earlier defined variables of the same name:

- Variables set inside the `swarm-trigger.pl` script itself
- /etc/perforce/swarm-trigger.conf
- /opt/perforce/etc/swarm-trigger.conf
- The `swarm-trigger.conf` file stored in the same directory as `swarm-trigger.pl`.
- Any file passed to the `swarm-trigger.pl` script using the -c command line argument

Windows and Linux:

If you specify ADMIN_USER, the ticket contained in %USERPROFILE%/p4tickets.txt (Windows), $HOME/.p4tickets (Linux), or the optional ticket file specified with the ADMIN_TICKET_FILE must use the port that was used to start P4 Server. For example, if p4d is started with:

    C:\> p4d -p my-helix-core-server:1666 ...

then the ticket for the admin user specified with ADMIN_USER should be established with:

    C:\> p4 -p my-helix-core-server:1666 -u admin_userid login

If the ticket was established using the wrong port, the error message you encounter includes the port that the trigger is attempting to use:

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

5. Linux only: Ensure that the script has execute permissions.

   Skip this step if you have committed the script to the P4 Server.

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

6. Verify that the trigger script executes correctly.

   - For Windows:

   Run:

       C:\>  perl "C:\path\to\swarm-trigger.pl" -t ping -v 0

   Use the full path to `perl` if it is not available in your command path.

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

   Only if using Curl:

   Installation of the triggers may cause a security warning dialog to appear when `curl.exe` executes:

   If this occurs, the triggers hang, creating zombie Perl processes. Due to the way triggers are invoked by P4 Server, the dialog is normally not visible even though Windows is waiting on interaction.

   To resolve this:

   1. Clear the Always ask before opening this file check box and click Run.
   2. Right-click `curl.exe`, select Properties, and click Unblock.

- For Linux:

Skip this step if you have committed the script to the P4 Server.

    $ /path/to/swarm-trigger.pl -t ping -v 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.

Run the trigger script without any arguments to see additional usage information.

7. Update the P4 Server triggers table to run the trigger script.

   - The swarm.shelvedel shelve-delete trigger line was added to P4 Code Review in version 2018.1 and updated in version 2020.1.

     - New installation or upgrading from P4 Code Review 2017.4 and earlier: add the `swarm.shelvedel shelve-delete` trigger line to the P4 Server trigger table if it is not already present.
     - Upgrading from P4 Code Review 2018.x and 2019.x: replace the existing `swarm.shelvedel shelve-delete` trigger line in the P4 Server trigger table with the one supplied in the P4 Code Review version you are upgrading to.
   - Workflow feature:

   The Workflow feature is enabled by default in P4 Code Review 2019.2 and later. The trigger lines required when workflow is enabled are different to those required when workflow is disabled:

   - Workflow feature enabled (default):
     - Comment out the swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines in the P4 Server trigger table if they are present.
     - Add the `swarm.enforce change-submit`, `swarm.strict change-content`, and `swarm.shelvesub shelve-submit` trigger lines to the P4 Server trigger table if they are not already present.
   - Workflow feature disabled:
     - Comment out the `swarm.enforce change-submit`, `swarm.strict change-content`, and `swarm.shelvesub shelve-submit` trigger lines in the P4 Server trigger table if they are present.
     - The swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines are commented out because they are optional. They require that the DEPOT_PATH1 and DEPOT_PATH2 values are configured appropriately. Support for these triggers will be dropped in a later release.
       - The first two lines configure the enforce feature, which rejects any submitted changes that are not tied to an approved review.
       - The second two lines configure the strict feature, which rejects any submitted changes when the contents of the changelist do not match the contents of its associated approved review.
     - If you need to apply enforce or strict to more depot paths, copy the lines and tweak the depot paths as necessary.

   The trigger script can provide the list of trigger lines that should work, with little to no adjustment, by executing it with the `-o` option:

   Windows

       C:\> perl "C:\path\to\swarm-trigger.pl" -o

   Linux

       $ /path/to/swarm-trigger.pl -o

   - The `%quote%c:\path\to\perl.exe%quote%` entry is only required for Windows-hosted systems.
   - An initial tabbed indent is required for each trigger line.
   - Commented out trigger lines are not stored.

   - If you disable the workflow feature in the P4 Code Review config.php file, workflow will not be processed by P4 Code Review but a small overhead is still incurred by the P4 Server each time it runs a workflow trigger script. This overhead can be eliminated by commenting out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit workflow triggers.

   As a P4 Server user with super privileges, edit the P4 Server trigger table by running the `p4 triggers` command and add the following lines (including the initial tab character). Update the `perl.exe`, trigger script, and configuration file paths in each line below to reflect the actual paths on your P4 Server:

   1. If you have committed both the trigger script and the configuration file to the P4 Server:

          	swarm.job        form-commit   job    "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t job        -v %formname%"
          	swarm.user       form-commit   user   "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t user       -v %formname%"
          	swarm.userdel    form-delete   user   "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t userdel    -v %formname%"
          	swarm.group      form-commit   group  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t group      -v %formname%"
          	swarm.groupdel   form-delete   group  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t groupdel   -v %formname%"
          	swarm.changesave form-save     change "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t changesave -v %formname%"
          	swarm.shelve     shelve-commit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t shelve     -v %change%"
          	swarm.commit     change-commit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t commit     -v %change%"
          	swarm.shelvedel  shelve-delete  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t shelvedel  -v %change% -w %client% -u %user% -d %quote%%clientcwd%^^^%quote% -a %quote%%argsQuoted%%quote% -s %quote%%serverVersion%%quote%"
          #	The following three triggers are used by workflow. If workflow is disabled in the Swarm
          #	configuration then they should be disabled.
          	swarm.enforce    change-submit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkenforced -v %change% -u %user%"
          	swarm.strict     change-content //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkstrict   -v %change% -u %user%"
          	swarm.shelvesub  shelve-submit  //...  "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkshelve   -v %change% -u %user%"
          #	The following triggers are only used to prevent a commit without an approved review.
          #	They predate the workflow functionality and should only be used if workflow is disabled.
          #	Support for these will be dropped in a later release.
          #	swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
          #	swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
          #	swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"
          #	swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%c:\path\to\perl.exe%quote% %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"

   2. If you have copied the trigger script and configuration file to common paths on all servers:

       	swarm.job        form-commit   job    "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t job        -v %formname%"
       	swarm.user       form-commit   user   "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t user       -v %formname%"
       	swarm.userdel    form-delete   user   "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t userdel    -v %formname%"
       	swarm.group      form-commit   group  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t group      -v %formname%"
       	swarm.groupdel   form-delete   group  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t groupdel   -v %formname%"
       	swarm.changesave form-save     change "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t changesave -v %formname%"
       	swarm.shelve     shelve-commit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t shelve     -v %change%"
       	swarm.commit     change-commit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t commit     -v %change%"
       	swarm.shelvedel  shelve-delete  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t shelvedel  -v %change% -w %client% -u %user% -d %quote%%clientcwd%^^^%quote% -a %quote%%argsQuoted%%quote% -s %quote%%serverVersion%%quote%"
       #	The following three triggers are used by workflow. If workflow is disabled in the Swarm
       #	configuration then they should be disabled.
       	swarm.enforce    change-submit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t checkenforced -v %change% -u %user%"
       	swarm.strict     change-content //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t checkstrict   -v %change% -u %user%"
       	swarm.shelvesub  shelve-submit  //...  "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t checkshelve   -v %change% -u %user%"
       #	The following triggers are only used to prevent a commit without an approved review.
       #	They predate the workflow functionality and should only be used if workflow is disabled.
       #	Support for these will be dropped in a later release.
       #	swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%"
       #	swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%"
       #	swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"
       #	swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"

   Windows and Linux:

   The use of `%quote%` is not supported on 2010.2 servers (it is harmless though); if you are using this version, ensure that you do not have any spaces in the path to `perl.exe` or the script's path.

   Workflow feature disabled:

   If your P4 Server has SSL enabled and is older than the 2014.1 release, the %serverport% trigger variable does not include the necessary transport indicator, which can cause the enforce and strict triggers to fail.

   To solve this problem, add ssl: immediately before %serverport% in the trigger lines. For example:

       #	The following triggers are only used to prevent a commit without an approved review.
       #	They predate the workflow functionality and should only be used if workflow is disabled.
       #	Support for these will be dropped in a later release.
       #	swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p ssl:%serverport%"
       #	swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p ssl:%serverport%"
       #	swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p ssl:%serverport%"
       #	swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p ssl:%serverport%"

8. Configure the P4 Server to promote all shelved changes.

   When this configurable is set, P4 Code Review 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` option when shelving files to promote their shelves to the commit server when initiating a pre-commit review.

       p4 configure set dm.shelve.promote=1

9. Optionally forward logins to the commit server.

   If you intend to use P4V and its P4 Code Review integration, you should consider forwarding logins to the commit server. See P4V Authentication for details.

10. Depending on your installation type, do one of the following:

- P4 Code Review package installation: Review the post-install configuration options to customize your P4 Code Review installation, see Post-install configuration options.
- P4 Code Review tarball installation: Set up a recurring task to spawn workers, see Set up a recurring task to spawn workers.

Your search for returned results