Previous Table of Contents Index Next
Perforce 2009.2: Command Reference



p4 triggers
Synopsis
Edit a list of scripts to be run conditionally whenever changelists are submitted, forms are updated, or when integrating Perforce with external authentication mechanisms.
Syntax
p4 [g-opts] triggers
p4 [g-opts] triggers -i
p4 [g-opts] triggers -o
Description
Perforce triggers are user-written scripts that are called by a Perforce server whenever certain operations (such as changelist submission or changes to forms) are performed. If the script returns a value of 0, the operation continues; if the script returns any other value, the operation fails. Upon failure, the script's standard output (not error output) is used as the text of the failed operation's error message.
Perforce supports a wide range of trigger types, divided into five categories. Changelist submission triggers (change-submit, change-content, and change-commit) are fired when users submit changelists. Fix triggers (fix-add and fix-delete) are fired when fixes are added or deleted from changelists by means of the p4 fix, p4 submit, or p4 change commands. Form triggers (form-save, form-out, form-in, form-commit, and form-delete) are fired when users generate or modify data in form specifications. Authentication triggers (auth-check and auth-set) are fired when administrators wish to integrate Perforce with external authentication mechanisms such as LDAP or Active Directory. Finally, Archive triggers (archive) are used to work with content archived outside the Perforce-managed repository.
Use the change-submit trigger type to create triggers that fire after changelist creation, but before files are transferred to the server. Because change-submit triggers fire before files are transferred to the server, submit triggers cannot access file contents. Submit triggers are useful for integration with reporting tools or systems that do not require access to file contents.
Use the change-content trigger type to create triggers that fire after changelist creation and file transfer, but prior to committing the submit to the database.
Use the change-commit trigger type to create triggers that fire after changelist creation, file transfer, and changelist commission to the database. Use commit triggers for processes that assume (or require) the successful submission of a changelist.
Even when a change-submit or change-content trigger script succeeds, the submit can fail because of subsequent trigger failures, or for other reasons. Use change-submit and change-content triggers only for validation, and use change-commit triggers or daemons for operations that are contingent on the successful completion of the submit.
To configure Perforce to run trigger scripts when users fix jobs, use fix triggers: these are triggers of type fix-add and fix-delete. Use fix triggers to execute commands when users add or remove fixes from changelists.
To configure Perforce to run trigger scripts when users edit specification forms, use form triggers: these are triggers of type form-save, form-in, form-out, form-commit, and form-delete. Use form triggers to generate customized specification values for users, validate data submitted in forms, to notify other users of attempted changes to the values stored in specification forms, and to otherwise interact with process control and management tools.
To use an external password authentication manager (such as LDAP or Active Directory) with Perforce, use authentication triggers (auth-check and auth-set). Use the %user% variable to pass the user's username in the command for the script. Passwords typed by the user as part of the authentication process are supplied to authentication scripts as standard input; never on the command line. For further information, see the System Administrator's Guide.
Archive triggers (archive) are a special case, and are reserved for storing, managing, or generating content archived outside of the Perforce repository.
Triggers are run in the order listed in the table; if a trigger script fails for a specified type, subsequent trigger scripts also associated with that type are not run.
To use the same trigger script with multiple file patterns, list the same trigger multiple times in the trigger table. Use exclusionary mappings to prevent files from activating the trigger script; the order of the trigger entries matters, just as it does when exclusionary mappings are used in views. If a particular trigger name and type is listed multiple times, only the script corresponding to the first use of the trigger name and type is activated.
Form Fields
The p4 triggers form contains a single Triggers: field. Like other Perforce forms, indent each row under the Triggers: field with tabs. Each row holds four values:
A run of the same trigger name on contiguous lines is treated as a single trigger, so that multiple paths can be specified. In this case, only the command of the first such trigger line is used.
There are thirteen trigger types, divided into four subtypes: changelist submission triggers, fix triggers, form triggers, and authentication triggers.
change-submit: Execute a changelist trigger after changelist creation, but before file transfer. Trigger cannot access file contents.
change-content: Execute a changelist trigger after changelist creation and file transfer, but before file commit.
To obtain file contents, use commands such as p4 diff2, p4 files, p4 fstat, and p4 print with the revision specifier @=change, where change is the changelist number of the pending changelist as passed to the script in the %changelist% variable.
change-commit: Execute a changelist trigger after changelist creation, file transfer, and changelist commit.
The special variable %jobs% is available for expansion; it expands to one argument for every job listed on the p4 fix command line (or in the Jobs: field of a p4 change or p4 submit form), and must therefore be the last argument supplied to the trigger script.
fix-add: Execute fix trigger prior to adding a fix.
fix-delete: Execute fix trigger prior to deleting a fix.
form-save: Execute a form trigger after the form contents are parsed, but before the contents are stored in the Perforce database. The trigger cannot modify the form specified in %formfile% variable.
form-out: Execute form trigger upon generation of form to end user. The trigger can modify the form.
form-in: Execute form trigger on edited form before contents are parsed and validated by the Perforce server. The trigger can modify the form.
form-delete: Execute form trigger after the form contents are parsed, but before the specification is deleted from the Perforce database. Trigger cannot modify form.
form-commit: Execute form trigger after the form has been committed for access to automatically-generated fields such as jobname, dates, etc.
For job forms, this trigger is run by p4 job as well as p4 fix (after the status is updated). The form-commit trigger has access to the new job name created by p4 job; any form-in and form-save triggers are run before the job name is created.
For job forms, this trigger is also run by p4 change (if a job is added or deleted by editing the Jobs: field of the changelist), and p4 submit (for any jobs present in the Jobs: field of the changelist). In these cases, the special variable %action% is available for expansion on the job form-commit trigger command line. The trigger cannot modify the form.
auth-check: Execute an authentication check trigger to verify a user's password against an external password manager during login, or when setting a new password If an auth-check trigger is present, the Perforce security counter (and any associated password strength requirement) is ignored, as authentication is now controlled by the trigger script.
auth-set: Execute an authentication set trigger to send a new password to an external password manager.
archive: Execute the script when a user accesses any file with a filetype containing the +X filetype modifier.
For read operations, scripts should deliver the file to the user on standard output. For write operations, scripts receive the file on standard input.
For changelist submission triggers (change-submit, change-content, or change-commit), a file pattern in depot syntax. When a user submits a changelist that contains any files that match this file pattern, the script linked to this trigger is run. Use exclusionary mappings to prevent triggers from running on specified files.
For fix triggers (fix-add or fix-delete), use fix as the path value.
For form triggers (form-save, form-out, form-in, form-commit, or form-delete), the name of the type of form, (one of branch, change, client, depot, group, job, label, protect, spec, triggers, typemap, or user).
For authentication triggers (auth-check or auth-set), use auth as the path value.
The command for the Perforce server to run when a matching path applies for the trigger type. Specify the command in a way that allows the Perforce server account to locate and run the command. The command must be quoted, and can take the variables specified below as arguments.
For change-submit and change-content triggers, changelist submission continues if the trigger script exits with 0, or fails if the script exits with a nonzero value. For change-commit triggers, changelist submission succeeds regardless of the trigger script's exit code, but subsequent change-commit triggers do not fire if the script exits with a nonzero value.
For form-in, form-out, form-save, and form-delete triggers, the data in the specification becomes part of the Perforce database if the script exits with 0. Otherwise, the database is not updated.
The form-commit trigger type never rejects a change; it exists primarily so that scripts can access a job number (from the %formname% variable) during the process of job creation.
For fix-add and fix-delete triggers, fix addition or deletion continues if the trigger script exits with 0, or fails if the script exits with a nonzero value.
For auth-check triggers (fired by p4 login), the user's typed password is supplied to the trigger command as standard input. If the trigger executes successfully, the Perforce ticket is issued. The user name is available as %user% to be passed on the command line.
For auth-set triggers, (fired by p4 passwd, but only after also passing an auth-check trigger check) the user's old password and new password are passed to the trigger as standard input. The user name is available as %user% to be passed on the command line.
Options
Usage Notes
Can File Arguments Use
Revision Specifier?
Never use a Perforce command in an out trigger that fires the same out trigger, or infinite recursion will result. For example, never run p4 job -o from within an out trigger script that fires on job specifications.
If you write a trigger that fires on trigger forms, and the trigger fails in such a way that the p4 triggers command no longer works, the only recourse is to remove the db.triggers file in the server root directory.
For example, "pending change 123 added" or "submitted change 124 deleted" are possible %action% values on change forms, and "job000123 created" or "job000123 edited" are possible %action% values for job forms.
%changelist%
%change%
The number of the changelist being submitted. The abbreviated form %change% is equivalent to %changelist%.
A change-submit trigger is passed the pending changelist number; a change-commit trigger receives the committed changelist number.
change-submit,
change-content,
change-commit,
fix-add,
fix-delete,
form-commit
all but archive
all but archive
The IP address of the client.
all but archive
A string of job numbers, expanded to one argument for each job number specified on a p4 fix command or for each job number added to (or removed from) the Jobs: field in a p4 submit, or p4 change form.
fix-add
fix-delete
If a changelist is renumbered on submit, this variable contains the old changelist number.
all but archive
The IP address of the server.
all but archive
The IP address and port of the Perforce server, in the format ip_address:port.
all but archive
The P4ROOT directory of the Perforce server.
all but archive
all but archive
Path to temporary form specification file. To modify the form from an in or out trigger, overwrite this file. The file is read-only for triggers of type save and delete.
form-commit,
form-save,
form-out,
form-in,
form-delete
form-commit,
form-save,
form-out,
form-delete
Type of form (for instance, branch, change, and so on).
form-commit,
form-save,
form-out,
form-in,
form-delete
Operation: read, write, or delete
If the Map: field is relative to P4ROOT, the %file% is a server-side path relative to P4ROOT.
If the Map: field is an absolute path, the %file% is an absolute server-side path.
Pre-submit trigger scripts cannot access submitted file contents from the server, because at the time a pre-submit trigger runs, file contents have not yet been transferred to the server.
Perforce commands in trigger scripts are always run by a specific Perforce user. If no user is specified, an extra Perforce license for a user named SYSTEM (or on UNIX, the user that owns the p4d process) is assumed. To prevent this from happening:
Pass a %user% argument to the script that calls each Perforce command to ensure that each command is called by. For example, if Joe submits a changelist that activates trigger script trigger.pl, and trigger.pl calls the p4 changes command, the script can run the command as p4 -u %user% changes.
Set P4USER for the account that runs the trigger script to the name of an existing user. (If your Perforce server is installed as a service under Windows, note that Windows services cannot have a P4USER value; on Windows, you must therefore pass a user value to each command as described above.)
For the four form trigger types (form-in, form-out, form-save, and form-delete), the %formname% variable is unset on job creation. This limitation is due to the fact that a job's name is unknown to the server until after job creation.
To access a job's name during job creation, use the form-commit trigger; it is the only trigger type that has access to a job's name (in the %formname% variable) during the process of job creation.
After job creation, subsequent user changes to a job correctly set %formname% for use by form trigger scripts.
As of Release 2007.3, trigger standard output is passed to the client program on both success and failure of the trigger script. Prior to this, standard output was only passed to the client program upon failure of a trigger.
You must specify the name of the trigger script or executable in ASCII, even when the server is running in Unicode mode and passes arguments to the trigger script in UTF8.
Examples
Suppose that the trigger table consists of the following entries:
Triggers:
    trig1 change-submit //depot/dir/... "/usr/bin/s1.pl %changelist%"
    trig2 change-submit //depot/dir/file "/usr/bin/s2.pl %user%"
    trig1 change-submit -//depot/dir/z* "/usr/bin/s1.pl %user%"
    trig1 change-submit //depot/dir/zed "/usr/bin/s3.pl %client%"
Both the first and third lines call the script /bin/s1.pl %changelist%, because the first occurrence of a particular trigger name determines which script is run when the trigger name is subsequently used.
No triggers are activated if someone submits file //depot/dir/zebra, because the third line excludes this file. If someone submits //depot/dir/zed, the trig1 script /usr/bin/s1.pl %changelist% is run: although the fourth line overrides the third, only the first script associated with the name trig1 is called.
For more detailed examples, see the System Administrator's Guide.
Related Commands


Previous Table of Contents Index Next

Perforce 2009.2: Command Reference
Copyright 1999-2009 Perforce Software.