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-createtalon 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 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).
|
|
|
|
|
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.
|
|
|
/tools/cont.sh/tools/end.sh
/tools/start.sh
<-- end-of-file of trigger parameters file
<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.)
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:
... 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.
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
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).
|
|
|
|
|
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.
|
|
|
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>.
<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>
...
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.
/tools/cont.sh/tools/end.sh
/tools/start.sh
<-- end-of-file of trigger parameters file
<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>
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.
|
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.
<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>
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).
|
|
|
|
(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:
|
|
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.
|
|
|
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.
|
<elemList> <elem count="1" hierType="serial" elemType="binary"></elem>
<elem count="2" hierType="serial"></elem>
</elemList>
•
|
Each <elem> XML subelement identifies an AccuRev element through the count attribute (representing the position on the command-line); no element pathname is required.
|
•
|
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”.
|
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.
•
|
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:
<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"/>
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:
<ISSUE id="11" apply_transition="false" />
Note: Using promote -q overrides any transition execution behavior specified in the
server_preop_trig script
<output_file> element.
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.
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.
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).
/tools/cont.sh/tools/end.sh
/tools/start.sh
<-- end-of-file of trigger parameters file
•
|
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:
|
•
|
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:
|
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>
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>
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.
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.
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:
<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.
<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.