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 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).
(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:
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:
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).
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>.
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):
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.
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):
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.
The parameters file passed to a server_preop_trig script is in XML format:
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.
|
|
|
|
The trigger parameters file sent to a server_preop_trig script contains an
<output_file> element — for example:
The XML element named <elements> in the trigger parameters file contains the data that the script needs to generate the output file— for example:
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.
|
|
•
|
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”.
|
|
•
|
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:
The XML element named <issues> in the trigger parameters file contains the data that the script needs to generate the output file— for example:
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:
Note: Using promote -q overrides any transition execution behavior specified in the
server_preop_trig script
<output_file> element.
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.
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.
|
|
|
For (ismember, addmember, rmmember), the name of a group member. There can be multiple <principal> elements.
|
|
|
|
|
|
|
|
|
|
|
|
(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) A set of <group> subelements, specifying the groups affected by the user’s command.
|
|
|
(chuser) New user kind ( dispatch or cm).
|
|
|
(chuser, chgroup) New AccuRev username or group name.
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
•
|
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:
In the XML-format server_admin_trig trigger parameters file, the
streamStyle and
streamCustomIcon reserved stream properties are encoded as follows:
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>
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” 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.