Triggering on forms

To configure Helix Server to run trigger scripts when users edit forms, use form triggers: these are triggers of type form-save, form-in, form-out, form-delete, and form-commit.

Use form triggers to generate customized field values for users, to validate data provided on forms, to notify other users of attempted changes to form data, and to otherwise interact with process control and management tools.

The %specdef% variable is defined for form triggers: it is expanded to the spec string of the form in question. This allows derived APIs to parse forms as part of triggers by loading the spec string as an argument.

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.

The following table describes the fields of a form trigger definition:

Field	Meaning
name	The name of the trigger.
type	form-save: Execute a form trigger after the form contents are parsed, but before the contents are stored in the Helix Server 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 Helix Server. The trigger can modify the form. form-delete: Execute form trigger after the form contents are parsed, but before the form is deleted from the Helix Server database. The trigger cannot modify the form. form-commit: Execute form trigger after the form has been committed for access to automatically-generated fields such as jobname, dates, etc.
path	The name of the type of form, (branch, change, client, depot, group, job, label, protect, server, spec, stream, triggers, typemap, or user).
command	The trigger for Helix Server to run when the type of form specified in the path field is processed. Specify the command in a way that allows Helix Server account to locate and run the command. The command (typically a call to a script) must be quoted, and can take as arguments any argument that your command is capable of parsing, including any applicable Helix Server trigger variables. When your trigger script is stored in the depot, its path must be specified in depot syntax, delimited by percent characters. For example, if your script is stored in the depot as //depot/scripts/myScript.pl, the corresponding value for the command field might be "/usr/bin/perl %//depot/scripts/myScript.pl%". See Storing triggers in the depot for more information. For form-in, form-out, form-save, and form-delete triggers, the data in the specification becomes part of the Helix Server database if the script succeeds. Otherwise, the database is not updated.