1 Introduction
Perforce introduced the first server-side trigger in release 99.1 with the pre-submit trigger. This trigger satisfied a long-standing desire in the user community, but demand continued for more hooks. In release 2004.2, Perforce squarely hit the need with the addition of five new trigger types. Release 2005.1 adds yet one more trigger type to this list rounding out one of the categories of triggers to completeness. This paper discusses triggers, techniques for implementing them and purposes for using them. It presumes a general knowledge of scripting. The examples follow in several programming languages. They should be easy to follow with knowledge of general programming, and any more arcane constructs will be explained. The paper also presumes a reasonable knowledge of Perforce scripting alternatives, such as that presented in [Bowles2005]. Although this paper will address the scripting of triggers comprehensively, it will refer to other Perforce scripting contexts and to Perforce commands with an assumption of familiarity.

1.1 What is a trigger?
Triggers are programs that run on the server immediately in response to some welldefined event in Perforce. Therefore, the context for a trigger is running on the server
using the trigger mechanism to start. Triggers are typically written in a shell script such as Perl, Python or Ruby due to the flexibility and facilities they provide. However, triggers can be written in any programming language that can interface with Perforce, including UNIX shell (sh, ksh, csh and work-alikes) and compiled languages like C/C++.

1.2 Types of triggers
Triggers fall into two categories. Pre-submit triggers enable actions in response to the submission of changelists. Form triggers allow actions in response to various stages of the life cycle of a form, regardless of the form type. This section provides a brief overview of the trigger types in preparation for the more detailed discussion.
1.2.1 Pre-submit triggers
There are three types of pre-submit triggers corresponding to different points in the life cycle of a submission.
• “Submit” triggers execute after the changelist has been created but before the files have been transferred, allowing inspection of the changelist details but disallowing file inspection.
• “Content” triggers execute after file transfer but before commit, allowing for inspection of the files.
• “Commit” triggers execute after the commit, allowing inspection of the changelist and file contents, but disallowing canceling of the submission.

1.2.2 Form triggers
Form triggers come in four types depending on the point in the form’s life cycle in which they are invoked.
• “Out” triggers execute when the form is generated and can modify the form before it is presented to the user.
• “In” triggers execute when the form is sent back to Perforce but before it is parsed, also allowing modification of the form on its way in.
• “Save” triggers execute after the form has been parsed but before it is saved, allowing reaction to the form but not modification.
• “Delete” triggers execute before a form is deleted, allowing failure of the deletion.

1.3 Why use a trigger?
Knowing why to use a trigger is partially a matter of knowing what are the competing alternatives. The alternatives naturally come from other contexts, since triggers define a context of their own. This section details the salient operational characteristics of triggers and contrasts them with Perforce alternatives. The three primary alternatives to triggers are wrapper scripts, such as p4wrapper, 1 review daemons, and journal tailers. A variation on the wrapper script would be a script available from the Tools menu in P4Win.

1.3.1 Synchronous execution
Triggers execute synchronously in response to their associated event. This provides an immediacy of response that is sometimes required or at least highly desirable. One option that provides synchronous execution could be an action invoked from a wrapper script such as p4wrapper. Another option would be to forego synchronous execution and rely on frequently running review daemons. Journal tailers would also perform asynchronously, although with very rapid and event-driven response.
1.3.2 Immediate user feedback on error
Triggers can provide messages back to the user, but only on error. Messages are not delivered on successful execution. A wrapper script can deliver messages to the user regardless of whether an error occurs or not. Review daemons and journal tailers can only provide feedback through indirect mechanisms.
1.3.3 Enforceability
Enforceability refers to the ability of an administrator to ensure that the script will run regardless of the client program used to initiate the operation. Because triggers are
installed on and executed by the server in response to server events, they will execute regardless of the client program. Wrapper scripts will only be invoked when the wrapper is used, whereas direct use of p4 or use of a different client program will circumvent the desired action. Review daemons and journal tailers are also enforceable due to their context on the server.

1.3.4 Modify a form
Form triggers can modify a form as it is delivered to the user or as it is sent back to Perforce. Wrapper scripts share this characteristic. Review daemons and journal tailers can not modify forms except to the extent that any user or administrator can after the operation has finished.
1.3.5 Customize any action
Form triggers have a limited ability to customize actions that involve forms, but they do not have the ability to react to any arbitrary command. Similarly, pre-submit triggers can only react to submits. Review daemons can only react to commands whose side effects can be reliably observed, something that is not readily available from the command line in many cases or from review mechanisms. Journal tailers have the ability to react to any action that affects database entries, which includes almost all.
1.3.6 Optimization for bulk processing
The review mechanism gives the ability to process a large number of actions in an orderly and efficient manner as long as those changes impact a counter. This optimization is not readily if at all available to triggers, wrappers or journal tailers due to their association with individual commands or journal entries.

1.3.7 Deterministic execution
Triggers and wrappers provide an exact and deterministic understanding of when they will execute relative to the command that initiates them. Review daemons are generally driven in a time-based manner and therefore do not execute deterministically relative to the Perforce command. Journal tailers are closer to deterministic than review daemons, but can conceivably execute prior to completion of a command.
1.3.8 Summary
The following table summarizes the characteristics of the scripting contexts that compete with triggers for Perforce scripting.

The post How to Write Trigger in Perforce? – Perforce Triggers Guide appeared first on scmGalaxy.