Perforce Public Knowledge Base - Debugging Triggers
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Debugging Triggers

« Go Back



How do I debug triggers?


This article provides a quick explanation of how triggers work, and outlines a few common usage pitfalls. The definitive reference for triggers is the Triggers and Daemons chapter of the Perforce System Administrator's Guide.

Perforce triggers are superuser defined rules that activate specialized scripts whenever certain client operations are performed. Triggers come in distinct varieties:

  • Changelist submission triggers.
  • Specification triggers.
  • External authentication triggers.
  • Shelving triggers.
  • Fixes triggers.
  • Archive triggers

Changelist submission triggers can be further identified as "submit", "content", or "commit" triggers. The following examples are situations in which changelist submission triggers are commonly employed:

  • Validate text in a change description, such as requiring a bug number.
  • Require that related files be submitted together.
  • Start build processes after successful changelist submission.
  • Ensure that every submit to a particular branch fixes at least one job.

Specification triggers can also be recognized as "save", "out", "in", or "delete" triggers. Examples of procedures suited to specification trigger use are:

  • Validating specifications.
  • Providing customized versions of Perforce specifications.
  • Notifying other users of attempts to change or delete specifications.

External authentication triggers are either "set" or "check" triggers. External authentication triggers run a script that invokes another authentication application such as LDAP or Active Directory to either validate an existing password or set a password.

For examples of triggers, check the Workshop or our System Administrator's Guide.

Note: It is strongly recommended that you develop and test triggers using a duplicate Perforce server. Never implement a new trigger without first testing thoroughly on a non-production server. Use this online form to request a duplicate license.

Trigger debugging basics

First, check that your trigger script runs correctly outside the context of Perforce. This step is required. Run the script from the command line as the same operating system user that runs Perforce.

If the trigger script runs outside of Perforce but fails when called as a Perforce trigger, check the following:

In the p4 triggers form:

  • Is the full pathname to the trigger script specified?
  • Is the full pathname to the calling program (perl.exe, for example) specified?
  • Does the triggers form have two triggers with the same name?

Within the trigger script:

  • Are your environment variables correct?
  • Is the Perforce user, client workspace and password correctly specified for all Perforce commands issued by the trigger?

Special note for Windows NT/2000 services

If you are running Perforce as a Windows service, Perforce runs by default as the unpriviliged LocalSystem user that does not have access to network drives. If your trigger needs access to network drives, run the Perforce service as a user with network privileges, otherwise, such triggers will fail.

Generating error output

Output to the Perforce user

If a trigger script command fails, the command's standard output (not error output) is used as the text of the trigger failure error message. For Perforce server releases up to and including 2007.2, if a trigger script command succeeds (and therefore returns error code 0), standard output is not shown. In 2007.3 and later releases a trigger success message is sent back to the client application.

Not all failed commands generate error messages. If your trigger displays the default error output when it fails, then either no error message is being issued when a command fails, or no message is being written to standard output (STDOUT). The trigger script itself must write errors to STDOUT (which is normally your display) in order for users to get information from the trigger. Capturing error output may require forcing a "failed" exit code by running a non-existent command.

Below is an example of how to set up a trivial trigger in Windows. You will see the "Always succeeds" output from this trigger because it always succeeds.

  1. Open a command prompt.

  2. Set the following environment variables:

    p4 set P4PORT=hostname:portnumber
    p4 set P4USER=Perforce User
    p4 set P4CLIENT=Perforce client workspace
  3. Enter the command:

    p4 triggers

    This will display your triggers specification in your default text editor.

  4. Add the following to the bottom of the trigger specification:

     triggerTest change-submit //depot/... "d:\perforce\triggers\success.bat"

    Note: the trigger name is not on the leftmost column, it is always preceded by whitespace (a space or tab).

  5. Next, create the file success.bat with Notepad on Windows from a command prompt:

    mkdir d:\perforce\triggers\
    cd d:\perforce\triggers
    notepad success.bat

    Note: The "d:\perforce\triggers\" path is for example purposes only. You may store your trigger files in any path accessible by the Perforce service.

  6. Type or paste the following code into success.bat:

    @echo on
    echo Always succeeds.
  7. Save success.bat and quit Notepad.

  8. Launch P4V and turn on p4 reporting commands and p4 command output:

    1. Select the "Edit | Preferences" menu item to open P4V's preferences window.

    2. Select the "Logging" heading to display the P4V logging options.

    3. Select (check) the "Show p4 reporting commands" option.

    4. Select (check) the "Show p4 command output for file operations" option.

    5. Click the "OK" button to save these preferences.

Add or edit any file, and submit. Scroll through the output in the bottom pane's "Log" tab for the "Always succeeds" message. This indicates that the script success.bat was run when the changelist was submitted.

For an example of a trigger failure:

  1. Enter the command:

    p4 triggers

    This will display your triggers specification in your default text editor.

  2. Add the following to the bottom of the trigger specification:

    triggerTest2 change-submit //depot/... "d:\perforce\triggers\fail.bat"
  3. Create the new trigger, "fail.bat":

    notepad fail.bat
  4. Type or paste the following code into the "fail.bat" trigger script:

    @echo off
  5. Save fail.bat and quit Notepad.

Add or edit any file, and submit. The submission will fail, and a message similar to the following will be displayed in the P4V Log pane:

Change 1850 created with 1 open file(s).
Submitting change 1850.
Locking 1 files ...
Submit validation failed -- fix problems then use "p4 submit -c 1850'.
'triggerTest2" validation failed: no error message

To display an error message to the user, you must write to STDOUT prior to running the failed command. For example:

@echo off
echo This trigger always fails!

Now, the modified "fail.bat" script displays an error message to the user:

Change 1851 created with 1 open file(s).
Submitting change 1851.
Locking 1 files ...
Submit validation failed -- fix problems then use "p4 submit -c 1851'.
Submit check "triggerTest2" failed: This trigger always fails!

Once this example works for you, replace the trigger with a script that outputs an exit code of zero or to succeed or fail based on your conditions.

Output to a file

If you require further troubleshooting, you can further modify "fail.bat" to redirect errors to a file. On Bourne shell and Windows scripts, the greater than sign (>) will redirect output to a file, and the 2>&1 notation redirects both output and error messages to a file.

In the following example the "boguscommand" line is modified to redirect error messages:

@echo off
echo This trigger always fails!
boguscommand > errorlog.txt 2>&1

The error from the script is captured in the file, errorlog.txt:

'boguscommand" is not recognized as an internal or external command,
operable program or batch file.

If you have problems with triggers, try the examples above or contact Perforce Support. For more meaningful trigger examples, check the Perforce Workshop.

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255