Perforce 2006.1 Command Reference | ||
<< Previous Chapter p4 tickets |
Table of Contents Index Perforce on the Web |
Next Chapter >> p4 typemap |
Perforce supports nine trigger types, divided into three categories. Changelist submission triggers (change-submit, change-content, and change-commit) are fired when users submit changelists. Form triggers (form-save, form-out, form-in, and form-delete) are fired when users generate or modify 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.
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 may 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 edit specification forms, use form triggers: these are triggers of type form-save, form-in, form-out, and form-delete. Use form triggers to generate customized specifications for users, validate customized specifications, to notify other users of attempted changes to 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.
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.
Field |
Meaning |
---|---|
name |
The user-defined name of the trigger. |
type |
There are nine trigger types, divided into three subtypes: changelist submission triggers, form triggers, and authentication triggers. Changelist submission triggers:
|
|
Form triggers:
|
|
Authentication triggers:
|
path |
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 form triggers (form-save, form-out, form-in, 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). Triggers that fire on the p4 triggers command are ignored. For authentication triggers (auth-check or auth-set), use auth as the path value. |
command |
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. 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. |
-i |
Read the trigger table from standard input without invoking the editor. |
-o |
Write the trigger table to standard output without invoking the editor. |
See the Global Options section. |
Argument |
Description |
Available for type |
---|---|---|
%changelist% |
The number of the changelist being submitted. (The abbreviated form %change% is equivalent to %changelist%.) |
change-submit, |
%client% |
Triggering user's client workspace name. |
all |
%clienthost% |
Hostname of the client. |
all |
%clientip% |
The IP address of the client. |
all |
%serverhost% |
Hostname of the Perforce server. |
all |
%serverip% |
The IP address of the server. |
all |
%serverport% |
The IP address and port of the Perforce server, in the format ip_address:port. |
all |
%serverroot% |
The P4ROOT directory of the Perforce server. |
all |
%user% |
Perforce username of the triggering user. |
all |
%formfile% |
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-save, |
%formname% |
Name of form (for instance, a branch name or a changelist number). |
form-save, |
%formtype% |
Type of form (for instance, branch, change, and so on). |
form-save, |
Old trigger type |
New trigger type (as of 2005.2) |
---|---|
submit |
change-submit |
content |
change-content |
commit |
change-commit |
out |
form-out |
in |
form-in |
save |
form-save |
delete |
form-delete |
Both the first and fourth 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.
Perforce 2006.1 Command Reference | ||
<< Previous Chapter p4 tickets |
Table of Contents Index Perforce on the Web |
Next Chapter >> p4 typemap |