What is Perforce Trigger?
Helix Server supports triggers which are user-written programs or scripts that are called when certain operations are performed. Examples of operations that might fire a trigger are changelist submits, changes to forms, and attempts by users to log in or change passwords.
If the script returns a value of 0, the operation continues. If the script returns any other value, the operation fails.
Helix Server Trigger Use Cases
- To integratte with Jira, as whenever Any changelist submitted with Jira ticket id, it should be updated.
- To validate changelist contents beyond the mechanisms afforded by the protections table. For example, you can use a pre-submit trigger to ensure that whenever file1 is submitted in a changelist, file2 is also submitted.
- To perform some action before or after the execution of a particular command.
- To validate forms, or to provide customized versions of forms. For example, you can use form triggers to generate a customized default workspace view when users run the p4 client command, or to ensure that users always enter a meaningful workspace description.
- To configure Helix Server to work with external authentication mechanisms, such as LDAP or Active Directory.
- To retrieve content from data sources archived outside of the repository.
How to Create triggers in Helix Serer?
To create a trigger and have Helix Server execute it, you must do the following:
- Write the program or script. Triggers can be written in a shell script such as Perl, Python, or Ruby; or they can be written in any programming language that can interface with Helix Server, including UNIX shell and compiled languages like C/C+.
- Triggers have access to trigger variables that can be used to get server state information, execution context, client information, information about the parameters passed to the trigger, and so on. For information about trigger variables, see Trigger script variables.
- Helix Core Trigger script variables Reference Guide
- Helix Core Trigger script variables Reference Guide
- Triggers communicate with the server using trigger variables or by using a dictionary of key/value pairs accessed via STDIN and STDOUT. For more information on these methods, see Communication between a trigger and the server.
- Triggers can also use the command-line client (p4.exe) or the Helix Server scripting APIs (P4Ruby, P4Python, P4PHP) when data is needed that cannot be accessed by trigger variables. For more information, see APIs for Scripting.
- Triggers can be located on the server’s file system or in the depot itself, for information on using a trigger that is located in the depot, see Storing triggers in the depot.
- Triggers can be written for portability across servers.
Use the p4 triggers command to create a trigger definition that determines when the trigger will fire. Trigger definitions are composed of four fields:
- These specify the trigger name,
- The event type that must occur,
- The location of the trigger and,
- In some cases, some file pattern that must be matched in order to fire the trigger.
$ p4 triggers Triggers: relnotecheck change-submit //depot/bld/... "/usr/bin/rcheck.pl %user%" verify_jobs change-submit //depot/... "/usr/bin/job.py %change%"
Each line in the trigger form you fill out when you use the p4 triggers command has four fields. These are briefly described in the following table.
Each line in the trigger form you fill out when you use the p4 triggers command has four fields. These are briefly described in the following table. Values for three of these fields vary with the trigger type; these values are described in additional detail in the sections describing each type of trigger. The name field uses the same format for all trigger types.
|name||The user-defined name of the trigger.
To use the same trigger script with multiple file patterns, list the same trigger multiple times on contiguous lines 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. In this case, only the command of the first such trigger line that matches a path is used.
|type||Triggers are divided into ten categories: submit triggers, push triggers, command triggers, journal-rotate triggers, shelve triggers, edge-server triggers, fix triggers, form triggers, authentication triggers, and archive triggers. One or more types is defined for each of these categories. For example, submit triggers include the change-submit, change-content, change-commit, and change-failed types.
Please consult the section describing the category of interest to determine which types relate to that trigger.
|path||The use of this field varies with the trigger type. For example, for submit, edge server, and shelve triggers, this field is a file pattern in depot syntax. When a user submits a changelist that contains files that match this pattern, the trigger script executes.
Please consult the section describing the trigger of interest to determine which path is appropriate for that trigger.
|command||The trigger for tHelix Server to run when the conditions implied by the trigger definition is satisfied.|
Helix Core Trigger script type Reference Guide
Sample of Helix Server Trigger 1 –
The following code sample is a bash auth-check type trigger that tries to authenticate a user (passed to the script using the %user% variable) using the Active Directory. If that fails, all users have the same “secret” password, and special user bruno is able to authenticate without a password.