p4 triggers

Synopsis

Syntax

Description

Perforce supports twelve trigger types, divided into four 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 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 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 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.

Form Fields

Options

-i	Read the trigger table from standard input without invoking the editor.
-o	Write the trigger table to standard output without invoking the editor.
g-opts	See the Global Options section.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
N/A	N/A	super

Warning!

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.

Warning!

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.

• To pass arguments to the trigger script, use the following variables:

  Argument	Description	Available for type
  %action%	Either null or a string reflecting an action taken to a changelist or job. 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.	form-commit
  %changelist% %change%	The number of the changelist being submitted. (The abbreviated form %change% is equivalent to %changelist%.)	change-submit, change-content, change-commit, fix-add, fix-delete, form-commit
  %client%	Triggering user's client workspace name.	all
  %clienthost%	Hostname of the client.	all
  %clientip%	The IP address of the client.	all
  %jobs%	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
  %oldchangelist%	If a changelist is renumbered on submit, this variable contains the old changelist number.	change-commit
  %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-commit, form-save, form-out, form-in, form-delete
  %formname%	Name of form (for instance, a branch name or a changelist number).	form-commit, form-save, form-out, form-delete
  %formtype%	Type of form (for instance, branch, change, and so on).	form-commit, form-save, form-out, form-in, form-delete

• If your trigger script needs to know what files were (or are about to be) submitted in the changelist, use the command p4 opened -ac changelist.

• 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.

• Trigger types were renamed in Release 2005.2. The following old trigger type names will continue to work but are deprecated:

  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

• 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.

Examples

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

To obtain information about the changelist being submitted	p4 describe p4 opened
To aid daemon creation	p4 review p4 reviews p4 counter p4 counters p4 user