AccuRev Triggers : The Trigger Parameters File

The Trigger Parameters File
When a trigger fires and executes a user-supplied script, AccuRev passes two arguments to the script:
The first argument is the pathname of a flat-text file containing information about the transaction that is about to be performed (or was just completed).
The second argument is the pathname of an XML-format file containing the same information. (In some cases, detailed below, the XML-format file contains a small amount of additional information that is not contained in the flat-text file.)
Exceptions: only one argument, the pathname of an XML-format file, is passed to a server_preop_trig script or a server_admin_trig script.
These files are called trigger parameters files. The flat-text file contains a series of values — usually one value per line — in a prescribed order. The XML-format file contains a set of elements below the top-level <triggerInput> element. Each element contains the information for one parameter: the parameter name is the element tag, the parameter value is the element contents (sometimes encoded as a set of subelements). For example, here are two trigger parameters files generated by the same user command:
 
pre-create
talon
talon_dvt_john
4
adding some files
this multi-line
comment has
four lines
C:/wks/talon/dvt_john
john
/tools/cont.sh
/tools/end.sh
/tools/start.sh
<triggerInput>
<hook>pre-create</hook>
<depot>talon</depot>
<stream1>talon_dvt_john</stream1>
<changePackages></changePackages>
<comment>adding some files
this multi-line
comment has
four lines</comment>
<topDir>C:/wks/talon/dvt_john</topDir>
<principal>john</principal>
<elemList>
<elem>/tools/cont.sh</elem>
<elem>/tools/end.sh</elem>
<elem>/tools/start.sh</elem>
</elemList>
</triggerInput>
The information contained in the trigger parameters file varies among the trigger types, as described in the following sections.
Format of the “pre-create-trig” Trigger Parameters File
The following table presents the information in the trigger parameters file sent to a pre-create-trig script. This information describes the creation of one or more new elements to a depot (CLI: add, GUI: Add to Depot).
Note: the trigger fires on creation of a new file or directory element, but not on creation of a new link element (CLI: ln, GUI: Paste Link).
The order of the parameters in this table reflects the order in which they appear in the flat-text trigger parameters file.
AccuRev username of person invoking the command.
(XML-format parameters file only) Integer indicating the element type specified by the user: 0=none specified, 2=text, 3=binary, 4=ptext.
elemList
elements
In the flat-text trigger parameters file, the elements to be created are listed, one per line, at the end of the file:
/tools/cont.sh
/tools/end.sh
/tools/start.sh
<-- end-of-file of trigger parameters file
There is no need to supply an element count, since an end-of-file condition signals the end of the element list.
In the XML-format trigger parameters file, the element paths are encoded as <elem> sub-elements of <elemList>:
<elemList>
<elem>/tools/cont.sh</elem>
<elem>/tools/end.sh</elem>
<elem>/tools/start.sh</elem>
</elemList>
(There is also an <elements> element with the same <elem> sub-element data.)
Overwriting the ‘pre-create-trig’ Trigger Parameters File
A pre-create-trig script must overwrite its flat-text parameters file with data that indicates the type of each element to be created. Each line must describe one new element:
<element-pathname> <element-type>
... where <element-pathname> is a pathname from the input “elemList”, and <element-type> is a numeric code:
1   directory
2   text file
3   binary file
4   ptext file
Make sure that the element-type value is 1 for every directory in the original list. You can’t change the element-type of a directory! You can however, change among the text-file, binary-file, and ptext-file types. For example, you might override AccuRev’s default classification of file ReadMe.html as 2 (text-file), setting the element-type to 3 (binary-file) instead.
See Controlling the Element Type and Exclusive File Locking State on page 40 of the AccuRev CLI User’s Guide for a discussion of element types.
Example: to have an add command create two text-file elements, two binary-file elements, and a directory element, a pre-create-trig script would replace its flat-text parameters file with this data:
/tools/end.sh 2
/tools/icons 1
/tools/icons/end.png 3
/tools/icons/start.png 3
/tools/start.sh 2
Note: there is currently no provision for the script to overwrite the XML-format trigger parameters file. The data to be passed to the AccuRev Server must be in flat-text format.
Format of the “pre-keep-trig” Trigger Parameters File
The following table presents the information in the trigger parameters file sent to a pre-keep-trig script. This information describes the creation of a new versions of one or more existing elements in a depot (CLI: keep, GUI: Keep).
The order of the parameters in this table reflects the order in which they appear in the flat-text trigger parameters file.
 
AccuRev username of person invoking the command.
(XML-format parameters file only) Integer indicating the element type specified by the user: 0=none specified, 2=text, 3=binary, 4=ptext.
elemList
elements
In the flat-text trigger parameters file, the versions to be created are listed, one per line, at the end of the file. Each line contains three specifications:
<element-pathname> <version-ID> <element-type>
There is no need to supply an element count, since an end-of-file condition signals the end of the element list. For example:
/tools/icons/end.png talon_dvt_john/5 3
/tools/icons/end.sh talon_dvt_john/9 2
/tools/icons/start.png talon_dvt_john/2 3
/tools/icons/start.sh talon_dvt_john/13 2
In the XML-format trigger parameters file, each version to be created is encoded as an as <elem> sub-element of <elemList>. The element’s attributes specify the version-ID (stream and version attributes) and the element-type (elemType attribute). The element pathname is encoded as the contents of <elem>.
The following example contains the same data as the flat-text example above:
<elemList>
<elem
stream="talon_dvt_john"
version="5"
elemType="3">/tools/icons/end.png</elem>
<elem
stream="talon_dvt_john"
version="9"
elemType="2">/tools/icons/end.sh</elem>
<elem
stream="talon_dvt_john"
version="2"
elemType="3">/tools/icons/start.png</elem>
<elem
stream="talon_dvt_john"
version="13"
elemType="2">/tools/icons/start.sh</elem>
</elemList>
In either format, the element-type value can be either 2 (text file), 3 (binary file), or 4 (ptext file). Note that different versions of an element can have different types.
In addition to the <elemList> element, the parameters file includes an <elements> element, with additional information on each file: its element-ID and the real version-ID of the workspace’s current version (not the one about to be created):
...
<elem
eid="58"
ver="3/4">/tools/icons/end.png</elem>
...
Format of the “pre-promote-trig” Trigger Parameters File
The following table presents the information in the trigger parameters file sent to a pre-promote-trig script. This information describes the creation of a new versions of one or more existing elements in a depot (CLI: promote, GUI: Promote).
Note: the pre-promote-trig trigger also fires on execution of a CLI purge command (GUI: Revert to Backed) — but only when the version is being purged from a dynamic stream, not a workspace.
The order of the parameters in this table reflects the order in which they appear in the flat-text trigger parameters file.
 
Type of trigger: pre-promote.
AccuRev username of person invoking the command.
(XML-format parameters file only) (purge) The character string purge.
(XML-format parameters file only) The issue number (or numbers, SPACE-separated) specified by the user with the promote –I command-line option.
(XML-format parameters file only) Name of the stream that the versions are to be promoted to.
(XML-format parameters file only) Integer indicating the element type specified by the user: 0=none specified, 2=text, 3=binary, 4=ptext.
elemList
elements
In the flat-text trigger parameters file, the elements to be created are listed, one per line, at the end of the file:
/tools/cont.sh
/tools/end.sh
/tools/start.sh
<-- end-of-file of trigger parameters file
There is no need to supply an element count, since an end-of-file condition signals the end of the element list.
In the XML-format trigger parameters file, the element paths are encoded as <elem> sub-elements of <elemList>:
<elemList>
<elem>/tools/cont.sh</elem>
<elem>/tools/end.sh</elem>
<elem>/tools/start.sh</elem>
</elemList>
In addition to the <elemList> element, the parameters file includes an <elements> element, with additional information on each element: its element-ID and the real version-ID of the version to be promoted):
<elements>
<elem
eid="51"
ver="8/13">/tools/cont.sh</elem>
</elements>
Overwriting the ‘pre-promote-trig’ Trigger Parameters File
A pre-promote-trig script can work in tandem with a server-post-promote-trig script, providing customized “before and after” processing around the execution of Promote commands:
The pre-promote-trig script overwrites its flat-text triggers parameters file.
The first line of the overwritten parameters file becomes the value of the <fromClientPromote> parameter passed to the server-post-promote-trig script.
Note: there is currently no provision for a pre-promote-trig script to pass data to a server-post-promote-trig script by overwriting the XML-format trigger parameters file.
Format of the “server-post-promote-trig” Trigger Parameters File
The following table presents the information in the trigger parameters file sent to a server-post-promote-trig script. This information is generated by AccuRev, and describes the Promote command that has just executed. The first line of this file provides a mechanism for passing user-specified data from a pre-promote-trig script to a server-post-promote-trig script. See Overwriting the ‘pre-promote-trig’ Trigger Parameters File on page 86.
The order of the parameters in this table reflects the order in which they appear in the flat-text trigger parameters file.
 
Type of trigger: server-post-promote.
AccuRev username of person invoking the command.
A single text line containing the issue number (or numbers, SPACE-separated) specified by the user during the Promote command. If no issue number was specified, the flat-text parameters file contains a blank line and the XML-format file contains an empty element.
The transaction number of the Promote transaction that just completed.
The time of the Promote transaction that just completed.
(XML-format parameters file only) A set of <changePackageID> subelements, specifying the same information as <fromClientPromote>.
elemList
elements
The following example shows the data encoded in <elemList> and <elements>:
<elemList>
<elem
stream="9"
version="7"
elemType="2">/dir00/sub00/file04.txt</elem>
</elemList>
<elements>
<elem
eid="8"
ver="9/7">/dir00/sub00/file04.txt</elem>
</elements>
Format of the “server_preop_trig” Trigger Parameters File
The parameters file passed to a server_preop_trig script is in XML format:
<triggerInput>
<hook> ... </hook>
<command> ... </command>
<principal> ... </principal>
<ip> ... </ip>
...
</triggerInput>
The set of subelements under the <triggerInput> element depends on the user’s command—the issues parameter is generated only for the promote command, for example. The following table provides a summary. For full details, see the sample server_preop_trig script in the examples directory in the AccuRev installation area.
 
Type of trigger: server_preop_trig.
The user command. See Server-Side Triggers on page 75 for a list of commands that can fire this trigger.
AccuRev username of person invoking the command.
The workspace’s parent (backing) stream. For promote commands, this is the stream being promoted to.
Type of object targeted by the command: 1=reference tree; 2=workspace; 3=stream; 5=user; 6=group
AccuRev username being modified.
New user kind (dispatch or cm).
New AccuRev username.
(promote) The number of the AccuWork issue record entered by the user, when prompted by the transaction-level integration or the change-package-level integration.
(promote) A set of <changePackageID> subelements, specifying the change packages (that is, issue records) specified in the user’s command.
These forms of the promote command generate a <changePackagePromote> element:
promote –I (user specifies issue record number(s) on the command line)
promote (user prompted to specify issue record number(s) by the transaction-level or change-package-level integration)
promote –Fx (user specifies a set of issue records with an XML file)
(promote) The <issues> element contains <issue> subelements for all issues that are being promoted, whether or not the issue was explicitly selected for the promote (as can be the case when promoting by file, when one or more issues can be implicitly selected). Each <issue> subelement specifies the following information:
Workflow stage the issue will be associated with after it transitions from its current workflow stage
Whether or not the issue will be complete in the destination stream upon completion of the promote operation
Comment string specified by the user. If the comment spans multiple lines, line-terminators are embedded in the string, but the final line does not have a line-terminator.
(add, co, keep) A set of <elem> subelements, each specifying one element processed by the user’s command.
For the add and keep commands, hierType is an <elem> attribute, which indicates the exclusive file locking state specified with the –E command-line option: serial or parallel.
(XML-format parameters file only) The name of the file that the server_preop_trig script creates and AccuRev reads. See Controlling Element Type and Exclusive File Locking with a “server_preop_trig” Script, below.
Controlling Element Type and Exclusive File Locking with a “server_preop_trig” Script
The trigger parameters file sent to a server_preop_trig script contains an <output_file> element — for example:
<triggerInput>
<hook>server_preop_trig</hook>
<output_file>cache/0_0.out</output_file>
...
The script can create a file at this relative pathname (it doesn’t exist when the trigger fires), in order to control the element type and/or exclusive file locking state of some or all of the elements processed by the user command.
The XML element named <elements> in the trigger parameters file contains the data that the script needs to generate the output file— for example:
<elements>
<elem
count="0"
eid="0"
elemType="text"
hierType="parallel">/dir03/sub05/able.txt</elem>
<elem
count="1"
eid="0"
elemType="text"
hierType="parallel">/dir03/sub05/baker.bin</elem>
<elem
count="2"
eid="0"
elemType="text"
hierType="parallel">/dir03/sub05/carr.doc</elem>
</elements>
For each AccuRev element to be processed, <elements> contains information about how the new version of the element will be created — unless the script intervenes. This includes both the element type (elemType attribute) and the exclusive file locking state (hierType attribute).
Note: <elemList> contains a subset of the data in <elements>, and can be safely ignored.
Suppose the example code above was passed to the server_preop_trig script by the add command, which the user invoked to place three files under version control: able.txt, baker.bin, and carr.doc. And suppose that the script decides to specify that:
Elements baker.bin and carr.doc are to be placed in the serial exclusive file locking state.
The first version of baker.bin is to have the binary element type.
In this case, the output file should contain the following code:
<elemList>
<elem count="1" hierType="serial" elemType="binary"></elem>
<elem count="2" hierType="serial"></elem>
</elemList>
Notes:
Each <elem> XML subelement identifies an AccuRev element through the count attribute (representing the position on the command-line); no element pathname is required.
The value of the hierType attribute must be either serial or parallel.
An <elem> is required only for AccuRev elements whose exclusive file locking state is to be changed from the default (or with a keep command, to be changed from its existing state). Thus, there need not be an <elem> for file able.txt, which is to be created in the default locking mode, parallel.
The number of <elem>s need not match the number of AccuRev elements being processed by the command; if there are “too many”, the final <elem>s are silently ignored; if there are “too few”, the final AccuRev elements get the default processing.
A server_preop_trig script can coexist with a pre-create-trig script, both of them making element-type specifications. The pre-create-trig script must specify an element type for every new element; this is not a requirement for the server_preop_trig script. If both scripts specify an element type for the same element, the server_preop_trig script “wins”.
Suppressing Transition Execution on Promote
A workflow can optionally specify a transition to be executed when an issue meeting one or more conditions is promoted into a stream. For example, your workflow might execute a “ready for QA” transition when an issue in the workflow stage Complete is promoted into your integration stream.
You can suppress transition execution:
Using the -q option for the promote command. See the AccuRev® CLI User’s Guide for more information.
Using the server_preop_trig script, as described here.
The trigger parameters file sent to a server_preop_trig script contains an <output_file> element — for example:
<triggerInput>
<hook>server_preop_trig</hook>
<command>promote</command>
<output_file>cache/0_0.out</output_file>
...
The script can create a file at this relative pathname (it doesn’t exist when the trigger fires), in order to control transition execution on some or all of the elements processed by the user command.
The XML element named <issues> in the trigger parameters file contains the data that the script needs to generate the output file— for example:
<issues>
<issue id="11" destination_stage="WIP" current_stage="NEW"
workflow="Enhancement" complete="true"/>
<issue id="12" destination_stage="WIP" current_stage="NEW"
workflow="Enhancement" complete="false"/>
</issues>
The <issue> subelement contains information about how the issue will be modified when it is promoted—unless the script intervenes.
Suppose the example code above was passed to the server_preop_trig script by the promote command, which the user invoked to promote issue 11 and issue 12. And suppose that the script decides to specify that trigger execution for issue 11 should be suppressed. In this case, the output file should contain the following code:
<ISSUES>
<ISSUE id="11" apply_transition="false" />
</ISSUES>
The transition for issue 12 is not executed under any circumstances because it is incomplete.
Note: Using promote -q overrides any transition execution behavior specified in the server_preop_trig script <output_file> element.
Format of the “server_admin_trig” Trigger Parameters File
The parameters file passed to a server_admin_trig script is in XML format: The set of subelements under the <triggerInput> element depends on the user’s command. The following table provides a summary. For full details, see the sample server_admin_trig script in the examples directory in the AccuRev installation area.
 
Type of trigger: server_admin_trig.
The user command. See Server-Side Triggers on page 75 for a list of commands that can fire this trigger.
AccuRev username of person invoking the command.
(remove, rmws, reactivate) Type of object targeted by the command: 1=reference tree; 2=workspace; 3=stream; 5=user; 6=group
(mkstream, mksnap) The kind of stream being created by the command: regular, passthru, or snapshot.
(chuser, chpasswd) AccuRev username being modified.
(chuser) New user kind (dispatch or cm).
(chuser, chgroup) New AccuRev username or group name.
The number of the AccuWork issue record entered by the user, when prompted by the transaction-level integration or the change-package-level integration.
A set of <changePackageID> subelements, specifying the change packages (that is, issue records) specified in the user’s command.
Comment string specified by the user. If the comment spans multiple lines, line-terminators are embedded in the string, but the final line does not have a line-terminator.
elemList
elements
Format of the “server_dispatch_post” Trigger Parameters File
The parameters file passed to a server_dispatch_post script is in flat-text format. The order of the parameters in the table below is the order in which they appear in the file.
 
Type of trigger: server_dispatch_post.
Two SPACE-separated fields:
The number of the transaction that created the previous version of this issue record. (The number 0 indicates that this is a newly created issue record.)
The time at which transNum was created.
Comment string specified by the user. If the comment spans multiple lines, line-terminators are embedded in the string, but the final line does not have a line-terminator.
AccuRev username of person invoking the command.
elemList
elements
Encoding of Element Lists
In both kinds of trigger parameters files, each element is listed by its path relative to the depot’s top-level directory:
/tools/cont.sh
The path begins with a slash in order to simplify constructing the element’s full pathname on the client machine: just append the given element pathname to the topDir pathname (the top-level directory of the user’s workspace tree).
In the flat-text trigger parameters file, the elements (or elements-to-be) to be processed by the user command are listed, one per line, at the end of the file:
/tools/cont.sh
/tools/end.sh
/tools/start.sh
<-- end-of-file of trigger parameters file
(Unlike the set of comment lines, there is no need to supply an element count; an end-of-file condition signals the end of the element list.)
For pre-create-trig and pre-promote-trig, the element pathname appears alone on the line.
For pre-keep-trig, each element is followed by the version-ID of the version about to be created (with the workspace specified by name), followed by the element-type code:
/dir07/sub04/file02.txt rack_dvt_john/3 2
As always the element-type coding is: 1=directory, 2=text file, 3=binary file, 4=ptext file.
For server-post-promote-trig, each element is followed by the real version-ID of the promoted version (with the workspace specified by number), followed by the element-type code:
/doc/Chapter_03.rtf 9/7 4
In the XML-format server_preop_trig trigger parameters file, the element paths are encoded as <elem> sub-elements of the <elemList> element:
<elemList>
<elem>/tools/cont.sh</elem>
<elem>/tools/end.sh</elem>
<elem>/tools/start.sh</elem>
</elemList>
Encoding of Command Comments
In the flat-text trigger parameters file, the user’s comment is indicated by a line-count (0 or greater), followed by the lines of the comment, if any:
4 <-- number of comment lines to follow
adding some files
this multi-line
comment has
four lines
In the XML-format trigger parameters file, the user’s comment is encoded as the contents of the <comment> element: a single string. For a multi-line comment, this string has line-terminators embedded:
<comment>adding some files <-- embedded line-terminator
this multi-line <-- embedded line-terminator
comment has <-- embedded line-terminator
four lines</comment>
Note that the final line-terminator is automatically stripped from all comment strings.
The sample set of trigger scripts includes a Perl script for each kind of trigger. The script’s comments include a detailed description of the layout of the parameters file for that kind of trigger.
Trigger Script Contents
A trigger script can send email, start a build, update a Web site, or perform many other tasks. In particular, you can run AccuRev commands to get more information. One common use of the server-post-promote-trig trigger is to run the hist command using the transaction number of the promotion, generating the list of promoted elements for inclusion in an email notification.
Trigger Script Exit Status
The exit status (return value) of a pre-create-trig, pre-keep-trig, pre-promote-trig, server_preop_trig, or server_admin_trig script is important:
A zero exit status indicates success: the AccuRev command is allowed to proceed.
A non-zero exit status indicates failure: the AccuRev command is canceled and the depot remains unchanged.
File Handling by Trigger Scripts
A trigger script can overwrite its parameters file (after reading it, presumably). This provides a way for the script to communicate with the AccuRev command or with a “downstream” script:
The parameters file for a pre-keep-trig script ends with a series of lines, one per element to be kept:
<pathname-of-element> <version-ID> <element-type>
<pathname-of-element> is not a full file system pathname, but starts at the workspace’s top-level directory (which is included earlier in the parameters file). <version-ID> is the new version to be created for that element. <element-type> is the numeric code 1, 2, 3, or 4, as described above. Note that different versions of an element can have different types.
See sample trigger script addheader.pl in the examples subdirectory of the AccuRev installation directory.
The parameters file for a pre-promote-trig script ends with a series of lines, one per element to be promoted:
<pathname-of-element>
<pathname-of-element> is not a full file system pathname, but starts at the workspace’s top-level directory (which is included earlier in the parameters file).
A pre-promote-trig script can overwrite its parameters file, in order to communicate with a server-post-promote-trig script: the first line of the overwritten parameters file becomes the value of the from_client_promote parameter in the server-post-promote-trig script.
See sample trigger script client_dispatch_promote_custom.pl in the examples/dispatch subdirectory of the AccuRev installation directory, along with server_post_promote.pl in the examples subdirectory. Note: The server_post_promote trigger is a separate trigger action than the Change-Package-Level Integration which is specifically called only for workspace-to-stream promotes (see Change-Package-Level Integration below for more detail).
A trigger script can also send data to STDOUT and STDERR. If the command for which the trigger fired was executed in the AccuRev CLI, this data appears in the user’s command window. If a GUI command caused the trigger to fire, the script’s exit status determines whether the user sees the STDOUT/STDERR data: in the “failure” case (non-zero exit status), the data is displayed in an error-message box; in the “success” (zero exit status) case, the data is discarded.

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com