10. 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:
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:
 
The following sections describe how information contained in the trigger parameters file varies among the trigger types:
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 (add).
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.
(XML-format parameters file only) Integer indicating the element type specified by the user: 0=none specified, 2=text, 3=binary, 4=ptext.
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 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.
 
(XML-format parameters file only) Integer indicating the element type specified by the user: 0=none specified, 2=text, 3=binary, 4=ptext.
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 Basis) — 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.
(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.
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.
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.
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>.
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 for a list of commands that can fire this trigger.
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
New user kind (dispatch or cm).
(promote) The number of the AccuWork issue record entered by the user, when prompted by thechange-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 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:
(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.
Sample server_preop_trig rules for Change Packages
The Perl snippets below take the examples provided in the sample server_preop_trig.pl file in the AccuRev installation examples folder one step further and show how you can prevent non-administrators from purging files from higher-level streams, and how to enforce promote-by-issue in non-workspace streams. Depending on the policies at your site, such changes could be considered best practices to ensure that all changes can be tracked to a specific AccuWork (or third-party ITS) issue.
###################################################### CUSTOMIZE ME
#### Add to (or replace) the example code below to
#### implement validation for the PROMOTE command.
######################################################
 
# EXAMPLE VALIDATION:
# only a user listed as an administrator can promote versions
# to a stream in the "admin_stream" list
 
#if ( defined($admin_stream{$stream2}) and `$::AccuRev ismember $principal "$admingrp"` == 0 ) {
# print TIO "Promoting to a stream identified as an 'admin stream' disallowed:\n";
# print TIO "server_preop_trig: You are not in the $admingrp group.\n";
# close TIO;
# exit(1);
#}
# EXAMPLE VALIDATION:
# only a user listed as an administrator can run the Promote
# command without entering a comment
if ( $comment eq "" and `$::AccuRev ismember $principal "$admingrp"` == 0 ) {
print TIO "Empty comments for 'promote' command disallowed:\n";
print TIO "server_preop_trig: You are not in the $admingrp group.\n";
close TIO;
exit(1);
}
# end of EXAMPLE VALIDATION
#This will prevent users from promoting or cross promoting individual files.
#Only users defined in the $admingrp group will be allowed to promote by file.
#This will prevent issues from becoming incomplete which can cause coalescing problems.
#foreach my $changepackage (keys(%{$$xmlinput{'changePackagePromote'}})){
#my @issues = (@{$$xmlinput{'changePackagePromote'}[0]{'changePackageID'}});
my @noissue = (@{$$xmlinput{'changePackagePromote'}});
foreach my $issue (@noissue) {
#foreach my $issue (@issues) {
#print "Array Issue num = $issue\n";
if ($issue == 0 and `$::AccuRev ismember $principal "$admingrp"` == 0 ){
print TIO "Promotion by file is disallowed.\n";
print TIO "You need to promote by issue, please select the issue which needs promotion and
promote\n";
print TIO "Only users in the $admingrp group are able to promote by file as this can cause
incomplete issues.\n";
close TIO;
exit(1);
}
}
# end of EXAMPLE VALIDATION
 
# no problems, allow command to proceed
close TIO;
exit(0);
}
 
#### end of validation for PROMOTE command
 
####
#### Validation for PURGE command
####
 
if ($command eq "purge") {
# at this point, the following variables will have meaningful values:
# $hook Trigger name
# $command AccuRev command being run
# $principal Username of person invoking command
# $ip IP address of AccuRev client machine
# $stream1 Stream from which versions are being purged
# $depot Depot name
# $fromClientPromote Data passed from pre-promote-trig script
# @elems Element list
 
###################################################### CUSTOMIZE ME
#### Add to (or replace) the example code below to
#### implement validation for the PURGE command.
######################################################
 
# EXAMPLE VALIDATION:
# only a user listed as an administrator can promote versions
# to a stream in the "admin_stream" list
 
#if ( defined($admin_stream{$stream1}) and `$::AccuRev ismember $principal "$admingrp"` == 0 ) {
# print TIO "Purging from a stream identified as an 'admin stream' disallowed:\n";
# print TIO "server_preop_trig: You are not in the $admingrp group.\n";
# close TIO;
# exit(1);
#}
# end of EXAMPLE VALIDATION
#Prevent users from purging elements so AccuWork issue will not become incomplete in streams.
unless ( $stream1=~/_$principal/ or `$::AccuRev ismember $principal "$admingrp"` == 1 ) {
print TIO "You can not perform \"Revert to Basis\" or purge operations in streams.\n";
print TIO "This will prevent CR's from disappearing in streams due to them becoming
incomplete issues.\n";
print TIO "Only users in the $admingrp group will be authorized to preform this
operation.\n";
close TIO;
exit(1);
}
 
# no problems, allow command to proceed
close TIO;
exit(0);
}
 
#### end of validation for PURGE command
 
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 for a list of commands that can fire this trigger.
(chws, chstream) The new name of the workspace or stream.
(remove, rmws, reactivate) Name of object targeted by the command.
(remove, rmws, reactivate) Type of object targeted by the command: 1=reference tree; 2=workspace; 3=stream; 5=user; 6=group; 7=sessions
(mkstream, mksnap) The kind of stream being created by the command: regular, passthru, or snapshot.
(setproperty, rmproperty) The name of the stream for which the property is being set or removed.
(setproperty) Specifies whether you are setting properties for a stream (stream) or principal (principal)
(setproperty, rmproperty) The property name. If using a reserved property for a stream, must be either streamStyle (to set a stream’s color) or streamCustomIcon (to decorate a stream with build-related artifacts like icons and tooltips that indicate build success or failure).
(setproperty) The value associated with the property you are setting for a stream or principal. If you are specifying either streamStyle or streamCustomIcon properties, see Encoding of Reserved Stream Properties.
(chuser, chpasswd) AccuRev username being modified.
(ismember, addmember, rmmember) AccuRev group name
(chuser) New user kind (dispatch or cm).
(chuser, chgroup) New AccuRev username or group name.
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 time at which transNum was created.
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 Reserved Stream Properties
In the XML-format server_admin_trig trigger parameters file, the streamStyle and streamCustomIcon reserved stream properties are encoded as follows:
streamStyle
<style>
   <color>
      <background-color>
hex_value</background-color>
   </color>
</style>
streamCustomIcon
<streamicon>
   <image>running | success | warning | failed</image>
   <clickurl>
URL to build machine</clickurl>
   <tooltip>tooltip text</tooltip>
</streamicon>
Restricting the Ability to Set Stream and Principal Properties
If you want to restrict the ability to set stream and principal properties to only those users defined as AccuRev administrators:
1.
Add the following variables to the # set variables section of your server_admin_trig trigger if they have not been defined already:
$streamName = $$xmlinput{'streamName'}[0];
$propertyKind = $$xmlinput{'propertyKind'}[0];
$propertyName = $$xmlinput{'propertyName'}[0];
$propertyValue = $$xmlinput{'propertyValue'}[0];
2.
if (($command eq "setproperty") && ($property_kind eq "principal")) {

    if ( `$::AccuRev ismember $principal "$admingrp"` == 0 ) {
        print TIO "You cannot set a properties for users or groups.\n";
        print TIO "server_admin_trig: You are not in the $admingrp group.\n";
        close TIO;
        exit(1);
    }
    close TIO;
    exit(0);
}
3.
if (($command eq "setproperty") && ($property_kind eq "stream")) {

    if ( defined($admin_stream{$property_stream}) and `$::AccuRev ismember $principal "$admingrp"` == 0 ) {
        print TIO "You cannot set properties for a stream identified as an 'admin stream'.\n";
        print TIO "server_admin_trig: You are not in the $admingrp group.\n";
        close TIO;
        exit(1);
    }
    close TIO;
    exit(0);
}
4.
To restrict the ability to remove principal and stream properties, repeat Step 2 and Step 3, and change occurrences of setproperty to rmproperty.
5.
If you choose to modify the print TIO text, make sure to not change the values of variables such as $admingrp.
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:
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” in the “AccuWork chapter of the AccuRev On-Line Help 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.

Micro Focus