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.

Overview

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:

Flat-text trigger parameters file

XML-format trigger parameters file

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 following sections describe how information contained in the trigger parameters file varies among the trigger types.

Back to top

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.

Parameter

Description

hook

Type of trigger: pre-create.

principal

AccuRev username of person invoking the command.

depot

Name of depot targeted by the command.

stream1

Name of the workspace stream in which the new elements are to be created.

topDir

Pathname to the top-level directory of the user's workspace tree, as it is listed by the show wspaces command.

comment

Zero or more comment lines specified by the user (see Encoding of Command Comments below).

elemType

(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

One or more files/directories to be added to the depot. For general notes, see Encoding of Element Lists below.

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 in CLI Help 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.

Back to top

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.

Parameter

Description

hook

Type of trigger: pre-keep.

principal

AccuRev username of person invoking the command.

depot

Name of depot targeted by the command.

stream1

Name of the workspace stream in which the new versions are to be created.

topDir

Pathname to the top-level directory of the user's workspace tree, as it is listed by the show wspaces command.

comment

Zero or more comment lines specified by the user (see Encoding of Command Comments below).

elemType

(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

A specification for each new element version to be created. For general notes, see Encoding of Element Lists below.

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>
...

Back to top

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.

Parameter

Description

hook

Type of trigger: pre-promote.

principal

AccuRev username of person invoking the command.

depot

Name of depot targeted by the command.

stream1

Name of the workspace or stream that the versions are to be promoted from.

action

(XML-format parameters file only) (purge) The character string purge.

option_I

(XML-format parameters file only) The issue number (or numbers, SPACE-separated) specified by the user with the promote -I command-line option.

stream2

(XML-format parameters file only) Name of the stream that the versions are to be promoted to.

topDir

Pathname to the top-level directory of the user's workspace tree, as it is listed by the show wspaces command.

comment

Zero or more comment lines specified by the user (see Encoding of Command Comments below).

elemType

(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

One or more files/directories to be promoted. For general notes, see Encoding of Element Lists below.

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.

Back to top

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 (above).

The order of the parameters in this table reflects the order in which they appear in the flat-text trigger parameters file.

Parameter

Description

hook

Type of trigger: server-post-promote.

principal

AccuRev username of person invoking the command.

depot

Name of depot targeted by the command.

stream1

Name of the stream that the versions were promoted to.

source_stream

Name of the stream the versions were promoted from.

dest_stream

Name of the stream the versions were promoted to.

comment

Zero or more comment lines specified by the user in the Promote command (see Encoding of Command Comments below).

fromClientPromote

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.

transNum

The transaction number of the Promote transaction that just completed.

transTime

The time of the Promote transaction that just completed.

changePackages

(XML-format parameters file only) A set of <changePackageID> subelements, specifying the same information as <fromClientPromote>.

elemList
elements

A specification for each version that was promoted. For general notes, see Encoding of Element Lists below.

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>

Back to top

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.

Parameter

Description

hook

Type of trigger: server_preop_trig.

command

The user command. See Pre-Operation Triggers for a list of commands that can fire this trigger.

principal

AccuRev username of person invoking the command.

ip

The IP address of the client machine.

stream1

The user's workspace stream.

stream2

The workspace's parent (backing) stream. For promote commands, this is the stream being promoted to.

stream3

The new name of the workspace or stream.

depot

Name of depot targeted by the command.

objectName

Name of object targeted by the command.

objectType

Type of object targeted by the command: 1=reference tree; 2=workspace; 3=stream; 5=user; 6=group

user

AccuRev username being modified.

newKind

New user kind (dispatch or cm).

newName

New AccuRev username.

fromClientPromote

(promote) The number of the AccuWork issue record entered by the user, when prompted by thechange-package-level integration.

changePackagePromote

(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)

The user can also specify issue record(s) through the AccuRev GUI.

issues

(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:

  • Issue number

  • Workflow stage the issue will be associated with after it transitions from its current workflow stage

  • The issue's current workflow stage

  • Whether or not the issue will be complete in the destination stream upon completion of the promote operation

comment

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.

elements

(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.

output_file

(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:

  • The top-level XML element in the output file is <elemList>, not <elements>.

  • 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 CLI Help 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

Back to top

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.

Parameter

Description

hook

Type of trigger: server_admin_trig.

command

The user command. See Pre-Operation Triggers for a list of commands that can fire this trigger.

principal

AccuRev username of person invoking the command.

Also, for (addmember, rmmember), <add> or <remove> elements can contain additional <principal> subelements, which specify group members to be added or removed.

ip

The IP address of the client machine.

stream1

The stream targeted by the user command.

stream2

The parent (backing) stream of stream1.

stream3

(chws, chstream) The new name of the workspace or stream.

depot

Name of depot in which the AccuWork issue database resides.

objectName

(remove, rmws, reactivate) Name of object targeted by the command.

objectType

(remove, rmws, reactivate) Type of object targeted by the command: 1=reference tree; 2=workspace; 3=stream; 5=user; 6=group; 7=sessions

streamType

(mkstream, mksnap) The kind of stream being created by the command: regular, passthru, or snapshot.

streamName

(setproperty, rmproperty) The name of the stream for which the property is being set or removed.

propertyKind

(setproperty) Specifies whether you are setting properties for a stream (stream) or principal (principal)

propertyName

(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).

propertyValue

(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.

user

(mkuser, chuser, chpasswd, ismember) The AccuRev user being operated on.

For (ismember), <user> can specify the name of an AccuRev user or group.

Note: If the name of an AccuRev group is modified, the XML input for server_admin_trig actually has <command> set to “chuser” and <user> set to the name of the group being modified. (Renaming a user and renaming a group are identical operations to the AccuRev server.)

groups

The AccuRev group being operated on.

For (addmember, rmmember), which can modify multiple groups, the <group> elements are contained in a single <groups> element.

newKind

(chuser) New user kind (dispatch or cm).

newName

(chuser, chgroup) New AccuRev username or group name.

fromClientPromote

The number of the AccuWork issue record entered by the user, when prompted by the change-package-level integration.

changePackagePromote

A set of <changePackageID> subelements, specifying the change packages (that is, issue records) specified in the user's command.

comment

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

A set of <elem> subelements, each specifying one element processed by the user's command.

Back to top

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.

Parameter

Description

hook

Type of trigger: server_dispatch_post.

depot

Name of depot targeted by the command.

stream1

The stream targeted by the user command.

fromClientPromote

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 issue number

transNum

The number of the transaction that created this new version of the issue record.

transTime

The time at which transNum was created.

comment

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.

principal

AccuRev username of person invoking the command.

elemList
elements

A set of <elem> subelements, each specifying one element processed by the user's command.

Back to top

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>

Back to top

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>

Back to top

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:

  2. $streamName = $$xmlinput{'streamName'}[0];
    $propertyKind = $$xmlinput{'propertyKind'}[0];
    $propertyName = $$xmlinput{'propertyName'}[0];
    $propertyValue = $$xmlinput{'propertyValue'}[0];
  3. Add the following logic to restrict the ability to set principal properties:

  4. 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);
    }
  5. Add the following logic to restrict the ability to set stream properties:

  6. 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);
    }
  7. To restrict the ability to remove principal and stream properties, repeat Step 2 and Step 3, and change occurrences of setproperty to rmproperty.

  8. If you choose to modify the print TIO text, make sure to not change the values of variables such as $admingrp.

Back to top

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.

Back to top

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.

Back to top

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" in the AccuWork section 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.

Back to top